QArt Tuner
Generates QR codes whose data modules form a recognizable image, using the QArt technique by Russ Cox. Lives in utils/qart/.
Quick Reference
| Item | Value |
|---|---|
| Source | utils/qart/main.go |
| Language | Go (managed via mise) |
| Dependency | rsc.io/qr (BSD 3-clause) |
| Launch web UI | QART_IMAGE=photo.png mise run serve (from utils/qart/) |
| CLI | mise x go -- go run . -url URL -image IMG -out out.png |
How It Works
QR error correction (Reed-Solomon coding) allows some data and check bits to be freely chosen. The tool:
- Builds a QR code plan for the given URL and version
- Converts the source photo to a grayscale brightness grid at QR module resolution
- For each ECC block, models the data/check bit relationships as a matrix over GF(2)
- Uses Gaussian elimination to find which bits can be independently assigned
- Assigns bits to match the target image brightness, prioritizing high-contrast areas
The result is a valid, scannable QR code whose black/white modules approximate the source image.
Web UI
The interactive tuner (-serve flag) provides sliders for all parameters with live preview.
Keyboard shortcuts: arrow keys (dx/dy offset), [/] (mask), -/= (version), r (rotate).
Parameters
| Parameter | Range | Effect |
|---|---|---|
| version | 1-8 | QR density — higher = more modules = finer detail |
| mask | 0-7 | QR mask pattern — dramatically affects which pixels are controllable |
| dx/dy | -15 to 15 | Shifts image relative to QR structure (avoids alignment dot on eyes) |
| rotation | 0-3 | Quarter turns |
| scale | 1-16 | Output pixels per QR module |
| dither | on/off | Floyd-Steinberg dithering |
Credits
- Technique: Russ Cox, QArt Codes (2012)
- QR library: rsc.io/qr — QR layout, encoding, GF(256) arithmetic
- Implementation: Claude Code (Opus 4.6) with direction from Erich Blume
Related
- mise-tasks — Task runner for BlumeOps operations