Erich Blume
33463764d1
Single-file Go tool implementing the QArt technique (Russ Cox, 2012) using only the public rsc.io/qr API. Generates QR codes whose data modules form a recognizable image by exploiting error correction freedom via GF(2) Gaussian elimination. Includes a web UI with live-updating sliders for version, mask, rotation, dx/dy offset, and scale. Keyboard shortcuts for rapid iteration. Also works as a CLI for batch generation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| .gitignore | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| mise.toml | ||
| README.md | ||
QArt Tuner
Generate QR codes whose data modules form a recognizable image.
This implements the QArt technique invented by Russ Cox. The trick: QR error correction gives some freedom in choosing bit values. By picking bits that satisfy the Reed-Solomon constraints and match a target image's brightness, the QR modules themselves draw a picture — no logo overlay, no center cutout.
This tool uses the rsc.io/qr library (BSD 3-clause) for QR layout, data encoding, and GF(256) arithmetic. The image-targeting algorithm — contrast-priority bit selection via GF(2) Gaussian elimination — is an original implementation based on the technique description in Russ Cox's blog post.
Quick start
# Launch the interactive web UI
QART_IMAGE=~/path/to/photo.png mise run serve
# Or with a custom URL and port
QART_URL=https://example.com QART_IMAGE=photo.png QART_PORT=9090 mise run serve
The web UI lets you adjust version, mask, rotation, x/y offset, and scale with
live preview. Keyboard shortcuts: arrow keys (dx/dy), [/] (mask), -/=
(version), r (rotate).
CLI usage
# Single image
mise x go -- go run . -url "https://docs.eblu.me" -image photo.png -out qart.png \
-version 6 -mask 4 -dx 6 -dy 4 -scale 8
# All 8 mask variants
mise x go -- go run . -url "https://docs.eblu.me" -image photo.png -out qart.png -all-masks
Flags
| Flag | Default | Description |
|---|---|---|
-url |
(required) | URL to encode in the QR code |
-image |
(required) | Source photo (PNG or JPEG) |
-out |
qart.png |
Output file path |
-version |
6 |
QR version (1-8, higher = more modules = more detail) |
-mask |
0 |
QR mask pattern (0-7, affects visual texture) |
-scale |
8 |
Pixels per QR module |
-rotation |
0 |
Quarter turns (0-3) |
-dx |
0 |
Horizontal image offset (-15 to 15) |
-dy |
0 |
Vertical image offset (-15 to 15) |
-dither |
false |
Enable Floyd-Steinberg dithering |
-seed |
(random) | RNG seed for reproducible output |
-all-masks |
false |
Generate all 8 mask variants |
-serve |
false |
Launch web UI instead of writing a file |
-port |
8088 |
Web UI port |
Tips
- Version controls QR density. Higher = more modules = finer image detail, but the code becomes harder to scan at small sizes.
- Mask dramatically affects which pixels the algorithm can control. Try all 8 — the best one varies per image.
- dx/dy offsets shift the image relative to the QR structure. Use this to avoid the central alignment dot landing on an eye (it makes you look unhinged).
- The QR code uses error correction level L (lowest) to maximize the number of bits available for image rendering.
Credits
The QArt technique was invented by Russ Cox and described in his 2012 blog post QArt Codes. The rsc.io/qr library provides the QR code primitives this tool builds on. Thank you, Russ.
This tool was written by Claude Code (Opus 4.6) with direction from Erich Blume. The image-targeting algorithm is an original implementation based on the technique description — not a copy of rsc's reference implementation.