The QRtsy Project

QRtsy (pronounced “cue-artsy”) is an experimental Python toolkit for making pretty QR codes.

QRtsy combines a normal QR matrix with a source image, preserves the pixels that a scanner most needs to sample, and leaves the remaining pixels available for the image and optional texture effects. The result is a playground for exploring the tradeoff between visual appearance and scan reliability.

QRtsy is designed primarily as a reusable, encoder-neutral Python library. It also includes an optional Segno integration, a command-line interface, and a local browser application for interactively trying different settings.

QRtsy is alpha software. Artistic QR codes deliberately spend some of the robustness of a conventional QR symbol. Always test generated codes with the actual phones, cameras, print sizes, display sizes, distances, angles, and lighting conditions in which you expect them to be used.

Installation

QRtsy requires Python 3.11 or newer.

It is a good idea to install QRtsy into a dedicated Python virtual environment rather than into your system Python. From the directory where you want to work:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

The rest of the installation instructions below use the standard Python pip command installed within this activated virtual environment. If it's not activated, you'll probably install the library somewhere unexpected and that will just be confusing and maybe even break things. Remember to activate.

Instead of using pip directly, most Python code jockeys these days instead tend to use various third-party project tools to manage project virtual environments like Poetry or UV. Pick your favorite tooling.

To install just the core QRtsy library with the encoder-neutral Pillow renderer:

pip install qrtsy

To install QRtsy with Segno support for the convenience API, command-line interface, and Segno converter plugin:

pip install 'qrtsy[segno]'

Or to install QRtsy with the local browser application, which also includes Segno:

pip install 'qrtsy[server]'

Quickstart: Browser UI

After QRtsy has been installed, the easiest way to explore its features is with the local web application:

qrtsy-server

Then open http://127.0.0.1:8000/ in your web browser.

Upload an image, enter the text or URL to encode, and experiment with the controls while QRtsy updates the preview.

The UI includes full-color, posterized, and monochrome image modes; QR version, mask, and error-correction controls; sampling-core sizing; function-pattern shrinking; several free-pixel texture algorithms; optional luminance compensation; built-in and custom presets; per-setting undo; and PNG download.

The How does this work? link opens the built-in manual at /what. The source for that guide is also readable directly in the repository at docs/what.md.

The server binds to 127.0.0.1 by default. Uploaded and generated images are processed in memory rather than written to the server filesystem.

Quickstart: Python

For most applications, the Segno convenience API is the simplest place to start:

from qrtsy import RenderOptions
from qrtsy.integrations.segno import save

save(
    "https://example.com/",
    "portrait.jpg",
    "qrcode.png",
    RenderOptions(
        module_size=8,
        core_size=3,
        border=4,
    ),
    segno_options={"error": "H", "version": 6},
)

Segno is optional because QRtsy itself does not encode payloads. The core renderer consumes an encoder-neutral semantic ModuleMatrix, so other QR encoders can be adapted without coupling the renderer to Segno.

If you already have a Segno QR code, QRtsy can render that directly:

import segno

from qrtsy import RenderOptions
from qrtsy.integrations.segno import save_qr

qr = segno.make_qr("https://example.com/", error="H")
save_qr(
    qr,
    "portrait.jpg",
    "qrcode.png",
    RenderOptions(module_size=8, core_size=3, border=4),
)

When QRtsy and Segno are installed together, QRtsy also registers a Segno converter named qrtsy:

qr.to_qrtsy(
    "qrcode.png",
    image="portrait.jpg",
    module_size=8,
    core_size=3,
    border=4,
)

For a direct example of the encoder-neutral ModuleMatrix API, see examples/matrix.py.

Quickstart: Command line

The qrtsy command uses the optional Segno integration:

qrtsy \
  'https://example.com/' \
  portrait.jpg \
  qrcode.png \
  --error H \
  --version 6 \
  --module-size 8 \
  --core-size 3 \
  --border 4

The CLI defaults to QR version 6. Use --version auto to let Segno choose the smallest version that fits the payload.

For all available options:

qrtsy --help

Highlights

QRtsy currently supports:

• full-color, posterized, and monochrome image backgrounds;
• cover, contain, and stretch image fitting;
• configurable module size, quiet zone, and central QR sampling-core size;
• semantic treatment of data and QR function-pattern modules;
• independently optional shrinking of finder, separator, alignment, and timing patterns to expose more of the image;
• constrained Floyd–Steinberg dithering at either raster-pixel or sampling-core cell scale, including two-pass forced-core error diffusion;
• configurable dither intensity source, gamma, contrast, brightness, clipping, threshold, and traversal direction;
• optional free-pixel texture using ordered dither, seeded noise, randomized error diffusion, or directional flow diffusion;
• adaptive texture fade to keep texture concentrated in visually suitable image regions;
• QR-aware local luminance compensation;
• immutable built-in presets plus browser-managed custom presets;
• JSON preset import/export;
• an optional Segno adapter and Segno converter plugin;
• a CLI and a Litestar/Uvicorn local experimentation server.

Most of these controls exist because there is no single “best” artistic QR code. A setting that looks great for one photograph, payload, output size, and scanner may perform badly for another.

How it works

QRtsy separates QR encoding from QR rendering.

An encoder adapter converts a QR symbol into a semantic matrix whose modules are classified as data, finder, separator, timing, alignment, format, version, fixed dark, and so on. This is more information than a simple dark/light matrix and lets the renderer treat different parts of the QR symbol differently.

For image-bearing modules, QRtsy can replace only a centered sampling core with the required black or white QR value instead of painting the entire module. The surrounding pixels remain available to show the source image. QR function patterns can remain fully rendered, or selected patterns can be shrunk explicitly for more aggressive experiments.

In monochrome mode, dithering can operate either on individual raster pixels or on square cells the same size as the sampling core. Core-sized dithering can use Andrew Taylor's two-pass technique: first diffuse the error introduced by forced QR cores into their neighbors, then Floyd–Steinberg-dither only the remaining free cells.

Optional texture passes can make the regular sampling-core grid less visually obvious. Optional local compensation can then nudge free pixels within each module to recover some of the luminance changed by forced QR pixels and texture.

For a walkthrough of the rendering pipeline, every UI setting, QR anatomy, texture modes, compensation, and scannability tradeoffs, see docs/what.md.

Presets

QRtsy currently ships with four built-in renderer presets:

• default — the normal RenderOptions defaults;
• scan-priority — a more conservative starting point with a four-module quiet zone, large sampling cores, protected timing patterns, and no optional texture or compensation;
• small-core-textured — a more aggressive experimental style using one-pixel cores and randomized error-diffusion texture;
• andrew-taylor — reproduces Andrew Taylor's 3×3 monochrome dither treatment with core-sized two-pass diffusion, green-channel/gamma preprocessing, full finder/timing/alignment patterns, and independently shrunk separators.

For example:

from qrtsy import get_builtin_preset
from qrtsy.integrations.segno import save

options = get_builtin_preset("scan-priority").options
save("https://example.com/", "portrait.jpg", "qrcode.png", options)

Built-in presets are immutable package data. Custom presets are application-owned state: the browser UI stores them in that browser's local storage and validates or migrates them through QRtsy before saving them. They can also be exported to or imported from JSON.

Scannability

QR error correction helps recover damaged codewords, but it does not make arbitrary artistic changes safe. QRtsy intentionally exposes controls that can make a symbol less robust.

A few practical rules of thumb:

• larger sampling cores are generally more scannable than smaller ones;
• leaving finder, alignment, and timing structures intact is generally more scannable than shrinking them;
• keep the default four-module quiet zone unless you have a reason to reduce it;
• texture and compensation are aesthetic tools; they can't increase scanning robustness;
• test the final physical or displayed result, not just a large desktop preview.

The built-in scan-priority preset is a useful conservative starting point, but it is still not a guarantee. See the scannability discussion for more detail.

Development

The project uses Poetry and Poe the Poet:

poetry install --all-extras
poetry run poe check

Useful development tasks include:

poetry run poe lint
poetry run poe format
poetry run poe typecheck
poetry run poe test
poetry run poe coverage
poetry run poe docs
poetry run poe build
poetry run poe server

poe check runs project validation, linting, format checking, type checking, tests, and a documentation-generation consistency check.

The server manual is generated from docs/what.md by docs/build_docs.py.

Current limitations

QRtsy is still deliberately experimental. Among the current limitations:

• output is raster/Pillow only;
• the QRtsy-supplied Segno adapter does not support Micro QR;
• local compensation can be slow;
• the renderer does not calculate or enforce a Reed–Solomon damage budget;
• Segno-specific module classification remains isolated behind the adapter because Segno documents that interface as experimental.

Expect APIs and rendering behavior to change while the project is in alpha.

Acknowledgements

QRtsy owes its biggest debt to Andrew Taylor's Dithered QR Code Generator and his excellent explanation of how the technique works. His use of small forced QR samples and error diffusion was the starting point for much of this experimentation. The built-in andrew-taylor preset now reproduces that core 3×3/two-pass rendering treatment.

QRtsy does not try to reinvent QR encoding itself. The first supplied integration uses Segno, whose encoder, semantic module output, and plugin architecture make it a particularly useful match for the project.

The built-in manual contains additional links to QR standards, tutorials, research papers, and other aesthetic QR-code projects.

The QRtsy project icon was generated by the QRtsy server app using Painter Artist by Gan Khoon Lay from Noun Project (licensed under CC BY 3.0) as the background image.

License

QRtsy is released under the MIT License.

“QR Code” is a registered trademark of DENSO WAVE INCORPORATED.