QRtsy

Content

Image

QR rendering

Free-pixel texture

Advanced compensation

Presets & browser features

The pipeline

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

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.

The browser can also compare the eight standard QR masks. QR optimized uses the encoder's normal QR mask-penalty selection. Image optimized instead renders every mask and chooses the one with the lowest normalized mean RGB difference from the fitted source image over the encoded QR region. The All 8 masks view shows both scores for every candidate. The image-difference score is an appearance metric, not a measure of scan reliability.

Sampling cores

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.

Module tinting can adapt those forced dark/light colors toward the local source image color. QRtsy limits the resulting luminance so a dark core remains dark and a light core remains light. A custom Python ModuleStyle can also replace the default centered square with another core geometry; the same style is applied to synthetic canvas modules.

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.

Canvas margin

The optional canvas margin extends the output beyond the QR code and its quiet zone in whole-module increments. QRtsy fills that outer area with synthetic dark/light modules generated deterministically from the canvas seed. These are decorative rather than encoded QR modules, but they use the same core style and can participate in module tinting, free-pixel texture, and monochrome dithering.

The QR quiet zone remains between the encoded symbol and this decorative margin. When Image fit area is set to QR code, the source image is fitted only under the encoded QR region and the outer canvas starts from the selected background color. When it is set to Canvas, the fitted source image also extends through the decorative margin; the quiet zone is still replaced by the background color.

Image preparation

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 fitted either to the encoded QR region or to the full decorative canvas, then resized according to the Fit setting: cover, contain, or stretch. The quiet zone always uses the selected background color. Full-color mode keeps the fitted RGB values. Posterized mode quantizes each channel to the requested number of levels. With dithering disabled, Monochrome mode converts the fitted image to grayscale. With Floyd-Steinberg dithering enabled, QRtsy instead derives a scalar intensity from either linear-light luminance or the source green channel and feeds that value into the dither pipeline.

Monochrome dithering.

Conventional Floyd-Steinberg dithering normally chooses black or white for a pixel, measures the resulting intensity error, and distributes that error to pixels that have not been processed yet. QRtsy's pixel-sized mode keeps that conventional constrained behavior while forcing required QR sampling pixels to their QR values.

The core-sized mode follows the technique used by Andrew Taylor's dithered QR generator. Each dither cell is exactly the same size as the sampling core. With the common module_size = 3 × core_size arrangement, every QR module therefore becomes a 3×3 dither-cell grid whose center cell carries the QR sample. QRtsy first forces those center cells and diffuses each resulting intensity error into all eight neighboring cells. It then makes a second Floyd-Steinberg pass over only the free cells, renormalizing the diffusion kernel whenever a neighboring cell is fixed by the QR code or a protected function pattern. This two-pass treatment is what makes otherwise random-looking QR cores blend much more naturally into the one-bit image.

Core-sized dithering requires module_size / core_size to be an odd integer so the sampling core lands exactly on one dither cell. QRtsy normally derives dither intensity from linear-light luminance. Taylor instead uses the green channel, then applies gamma 2.2, contrast, brightness, and a 0.05-0.95 intensity clamp before diffusion. QRtsy exposes each of those preprocessing choices independently; the andrew-taylor preset selects Taylor's values. The threshold then controls the black/white decision point. Serpentine mode alternates row direction; the preset disables it because Taylor's implementation scans every row left-to-right.

Free-pixel texture.

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 visually pleasing texture to the background.

The texture controls determine both how candidate free blocks are selected and how visible texture is distributed among them. The texture mode chooses the placement algorithm, while density, masking, and strength control how much texture appears, where it is allowed to appear, and how strongly each visible block contrasts with the underlying image.

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

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).

The built-in andrew-taylor preset selects a 3×3 core-cell layout, monochrome Floyd-Steinberg dithering, Taylor-style core-error diffusion, green-channel input with gamma 2.2 and a 0.05-0.95 intensity clamp, fixed left-to-right traversal, full finder/timing/alignment patterns, core-sampled separators, and stretch-to-square image fitting. It also keeps QRtsy's four-module quiet zone; Taylor's generator itself emits no margin and warns that one should be added for real use. The server defaults of Version 6 and High error correction match Taylor's generator defaults, but version, error correction, and mask are encoder choices and are intentionally not part of renderer presets.

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 does not maintain a custom-preset registry. Custom presets will therefore seem to disappear whenever the server version is updated. Browser storage is a convenience rather than long-term storage.

The preset selector also acts as a simple state indicator: it shows the currently applied preset while the current render settings still match that preset, and is blank after those settings have been changed. The Save action is enabled only in that changed state and opens a dialog for a new preset name and optional description.

The separate Export / Import section can round-trip render settings as named JSON presets. If the current settings match an existing preset, JSON export reuses that preset's name and description. Otherwise it asks for a name and optional description before exporting. Importing one of these files adds it to the Presets section and selects it, but does not change the current render settings until Apply is selected.

The "Export settings as CLI/Python" is intended for reproducibility beyond the qrtsy-server UI: the export includes a CLI invocation and equivalent Python example covering the payload, encoder selections, source/fill information, output name, and all current RenderOptions.

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 so QRtsy uses four modules as its default. Reducing the margin is allowed, but it 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.

The optional decorative canvas margin sits outside this quiet zone; increasing the canvas margin does not reduce the configured quiet-zone width.