In a local check, both PNG examples decoded to their original URL. This tutorial separates three checks: whether the file decodes, whether its payload matches your input, and whether the final design works in its intended setting. Treat these as separate acceptance steps—not a single “image saved successfully” check.
1. Generate PNG and SVG files with Segno
Segno is a pure-Python QR encoder with no required dependencies. Start here if you want both output formats without installing an image-processing library. [2]
Install it in your project’s Python environment:
python -m pip install segno
Save this as generate_qr.py:
import segno
payload = "https://example.com"
qr = segno.make_qr(
payload,
error="m",
boost_error=False,
)
qr.save(
"example.png",
scale=10,
border=4,
dark="black",
light="white",
)
qr.save(
"example.svg",
scale=10,
border=4,
dark="black",
light="white",
)
print("Version:", qr.version)
print("Error correction:", qr.error)
print("PNG dimensions:", qr.symbol_size(scale=10, border=4))
Run it with:
python generate_qr.py
The important settings are:
make_qr()creates a regular QR Code, never a Micro QR Code. Segno’s generalmake()function can choose Micro QR for suitable short inputs. [1]error="m", boost_error=Falseselects level M explicitly. Without disabling boosting, Segno may increase error correction when it can do so without increasing the symbol version. [3]scale=10makes each PNG module—the small square in the symbol—10 pixels wide.border=4supplies a four-module quiet zone. Explicit black and white colors avoid a transparent background in these exports. [4]
The four-module margin is not decorative padding: DENSO WAVE specifies that regular QR Codes require a clear margin four modules wide on every side. Keep text, borders, and artwork out of it. [5]
2. Alternative: Generate a PNG with qrcode
Use this route instead if you prefer the qrcode API. Install its Pillow extra for the image workflow below. The project currently declares Python 3.9 or newer, below Python 4. [6]
python -m pip install "qrcode[pil]"
import qrcode
payload = "https://example.com"
qr = qrcode.QRCode(
version=None,
error_correction=qrcode.constants.ERROR_CORRECT_M,
box_size=10,
border=4,
)
qr.add_data(payload)
qr.make(fit=True)
image = qr.make_image(fill_color="black", back_color="white")
image.save("example-qrcode.png")
Here, version=None with fit=True lets the library choose the symbol version. box_size controls pixels per module, while border controls the margin in modules. [6]
You do not need both generation libraries. Pick one, then test its exported file.
3. Decode the saved PNG in Python
An automated round-trip check should reopen the file from disk and compare the decoded text with the expected payload. OpenCV provides QRCodeDetector and a detectAndDecode() method for this purpose. [7]
For an environment without OpenCV, install the headless package; this example needs no GUI. If an OpenCV package is already installed, use it rather than adding a second variant. The package maintainers warn against installing multiple variants together because they share the cv2 namespace. [8]
python -m pip install opencv-python-headless
Save this as test_qr.py in the folder containing your generated PNG:
from pathlib import Path
import cv2
path = Path("example.png")
expected = "https://example.com"
image = cv2.imread(str(path), cv2.IMREAD_GRAYSCALE)
if image is None:
raise RuntimeError(f"Could not read image: {path.resolve()}")
decoded, points, _ = cv2.QRCodeDetector().detectAndDecode(image)
if points is None:
raise RuntimeError("No QR code detected")
if decoded == "":
raise RuntimeError("QR code detected, but decoding returned no text")
if decoded != expected:
raise RuntimeError(
f"Payload mismatch: expected {expected!r}, got {decoded!r}"
)
print(f"PASS: {path.name} decodes to {decoded!r}")
Run:
python test_qr.py
For the alternative generator, change the filename to example-qrcode.png. Keep expected identical to the text you intended to encode.
imread() loads the image; the detector returns decoded text, detected corner points, and an optional rectified image. This example is deliberately limited to a nonempty text URL—not arbitrary binary payloads. [9]
A passing result means this decoder recovered the expected text from this PNG. Do not use that result as your only release criterion.
4. Check the final asset and destination
Use this release checklist after the automated test:
- Inspect the actual delivery file. If you place the QR code in a document, web page, or label layout, test that finished layout too—not only the original PNG.
- For SVG, test a rendered result. Render it in the intended browser or design application, then scan the displayed result or decode a raster export. The PNG test above does not validate the SVG rendering.
- Compare the payload before opening it. For a URL, check the scheme, hostname, path, and query string against your intended destination.
- Open the destination separately. Confirm the page and any redirects behave as intended. Payload equality and destination behavior are different acceptance checks.
- Try representative phones and conditions. Include the intended viewing distance, lighting, and physical size. For print, scan an actual-size proof on the intended material before a larger run.
These are recommended acceptance steps; no phone or print results are claimed for this tutorial.
Size, format, and error correction: what to change first
Increase module size without removing the margin
For a square symbol with N modules per side, a four-module border and 10 pixels per module produce a PNG width of (N + 8) × 10 pixels. This follows the same symbol-plus-margin calculation shown by DENSO WAVE. It is not a universal minimum print size. [5]
If the final result is difficult to scan, first try a larger placement or regenerate the PNG with a larger integer scale. Segno documents scale as the number of pixels per PNG module. [4]
Keep both export formats when useful
The Segno example saves one encoded symbol in PNG and SVG formats. Use the PNG for the automated check shown here; retain the SVG when your layout workflow accepts it. Test whichever rendering actually reaches users. [1]
Do not treat high error correction as a styling guarantee
Higher error correction adds recovery capability but can require a larger symbol for the same payload. DENSO WAVE describes restoration rates in terms of codewords—not a guaranteed percentage of image area that you can cover with a logo. [10]
Start with the plain examples. If you later add logos, rounded modules, or gradients, repeat the checks on that final version. The qrcode documentation specifically warns that styled codes are not guaranteed to work with every reader. [6]
What this test does—and does not—prove
The practical workflow is generate → save → decode → compare → test the final presentation.
A successful decode is not a standards-conformance certificate. ISO/IEC 18004:2024 covers encoding, symbol formats, dimensions, error correction, decoding, and production quality requirements—a broader scope than the round-trip check in this tutorial. [11]
References
[1] Segno creation guide — https://segno.readthedocs.io/en/latest/make.html
[2] Segno overview — https://segno.readthedocs.io/en/latest/
[3] Segno error-correction boosting — https://segno.readthedocs.io/en/latest/boost-error-correction-level.html
[4] Segno serialization guide — https://segno.readthedocs.io/en/latest/serializers.html
[5] DENSO WAVE: margins and code area — https://www.qrcode.com/en/howto/code.html
[6] qrcode project documentation — https://pypi.org/project/qrcode/
[7] OpenCV QRCodeDetector — https://docs.opencv.org/4.13.0/de/dc3/classcv_1_1QRCodeDetector.html
[8] OpenCV Python package documentation — https://pypi.org/project/opencv-python-headless/
[9] OpenCV image reading and writing — https://docs.opencv.org/4.13.0/d4/da8/group__imgcodecs.html
[10] DENSO WAVE: error correction — https://www.qrcode.com/en/about/error_correction.html
[11] ISO/IEC 18004:2024 abstract — https://www.iso.org/standard/83389.html



