blumeops/utils/qart

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.