QRtsy

Content

Image

QR rendering

Free-pixel texture

Advanced compensation

Presets & browser features

The pipeline

Encode first, then add art.

The core QRtsy renderer does not encode payloads. It accepts a semantic ModuleMatrix: a square grid whose cells know both their required dark/light value and their role: data, finder, timing, alignment, format, version, separator, and so on. The included Segno integration creates that semantic matrix from a Segno QR code. The renderer then combines the matrix with an image and RenderOptions.

Keeping those jobs separate is useful. Segno can stay very good at QR encoding and QRtsy can stay focused on the pretty post-processing. It also means another QR encoder can be adapted later without rewriting the artistic renderer.

QR anatomy

Not all squares have the same job.

The semantic matrix helps QRtsy to keep track of the different roles for each square (aka module). The large corner finders help a scanner locate and orient the symbol. Timing patterns establish the module grid. Alignment patterns help compensate for distortion. Format modules identify the error-correction level and mask, and version modules appear on larger versions. Data modules carry the encoded payload and its error-correction codewords.

QRtsy treats these roles differently. Data, format, version, and the fixed dark module use central sampling cores by default. Finder, separator, timing, and alignment modules remain full-sized unless their corresponding shrink switch is enabled.

Sampling cores

The center of the square does the heavy lifting.

A QR module occupies module size × module size output pixels. For shrinkable modules, QRtsy forces only a centered core size × core size square to the required QR endpoint color and leaves the surrounding pixels available for the image and optional texture. Smaller cores reveal more image; larger cores give the scanner a more conventional target.

Some of these techniques push the boundaries of what is allowed by the standard and what is reliably scanned in the real world. Scanner sampling behavior varies, so the right core size is an empirical choice for the way the final image will actually be used.

Image preparation

Fit it, and maybe simplify.

When no source image is uploaded, the server starts with a solid white background; the Background color control can replace that with another solid color. A supplied image is first resized to the QR content area (as governed by the "Fit" settings: cover, contain, or stretch). Full-color mode keeps the original RGB values. Posterized mode quantizes each channel to the requested number of levels. Monochrome mode converts the image to grayscale. Note that the monochrome/grayscale processing option is not yet optimized and is currently a work-in-progress currently producing some visual artifacts that I haven't yet debugged.

Monochrome dithering.

Fuzzy pictures can be pretty too.

Conventional Floyd–Steinberg dithering normally chooses black or white for a pixel, measures the resulting luminance error, and distributes that error to pixels that have not been processed yet. In QRtsy, the required QR sample pixels are fixed to their QR value and, when appropriate, the resulting error is allowed to diffuse into neighboring free pixels.

The threshold moves the black/white decision point. Serpentine mode alternates row direction so the error does not always march across the image from the same side.

Free-pixel texture.

Noise can also be pretty.

Free-pixel texture operates on core-sized blocks that do not overlap required QR samples. The goal is to make the regular sampling-core pattern less obvious by adding some visually pleasing texture to the background.

Advanced compensation

Also known as luminance correction or local compensation. I haven't decided on the best terminology for this.

A forced dark core in a pale module removes luminance; a forced light core in a dark module adds it. Texture can change the module's average luminance too. Local compensation runs after the required cores and texture have been rendered, compares each module against the prepared source image, and nudges the remaining free pixels toward the original total luminance. The effect can be subtle and not always so pretty. I'm still experimenting with this algorithm so it might improve in later iterations.

The luminance compensation correction is the slowest part of many high-resolution renders, which is why it is disabled by default. It's generally best to experiment with the other settings first and then try adding luminance compensation as a final tweak before generating the final image to download.

Presets

It's annoying to keep track of all your favorite settings.

Most of the rendering options are serialized into RenderOptions which we can save as presets. Presets intentionally do not capture the uploaded image, fallback background color, payload, QR version, mask, or error-correction level (I might change some of this later).

Built-in presets are immutable package data. Custom presets created in the server UI are application-owned state and live entirely in browser storage under a key containing the QRtsy version. The server validates and migrates preset data but does not maintain a mutable custom-preset registry. Custom presets will therefore seem to disappear whenever the server version is updated. Browser storage is a convenience, not long-term storage, so export any custom presets you want to save reliably for later use.

Scannability

QR error correction can recover damaged codewords, but artistic rendering is still spending robustness. Higher error-correction levels provide more recovery capacity, while also reducing payload capacity for a given version.

The standard QR quiet zone around the margin is four modules wide. QRtsy defaults to a smaller value because it is an experimentation tool, but reducing the margin is one more thing that can make real-world scanning less forgiving. A code that scans from your monitor under office lighting is just a first test. To test it robustly, print it, shrink it, tilt it, crumple the paper a bit, and maybe borrow somebody else's phone.