MT-LOGO-RENDER(1) User Commands MT-LOGO-RENDER(1)
NAME
mt-logo-render - real Pillow renderer for the mt-logo recipe schema
SYNOPSIS
render.py RECIPE.json -o OUT.png [--no-qr] [--qr-payload TEXT]
[--qr-primary]
render.py --read-anchor OUT.png
DESCRIPTION
Renders a parametric logo from a JSON recipe, real 32-bit RGBA output.
Every render self-verifies: a real scannable QR corner badge and match‐
ing PNG metadata, both encoding the recipe's canonical SHA256 id -- see
hee-qr(1) to read either back.
This is the real, missing pixel-rendering half of the vendored up‐
stream/mt-logo-render (recipe.rs), which only ever defined the data
model, never the actual rendering code.
DEPENDENCIES
Pillow and qrcode are imported at module level, so both are required be‐
fore even --help will run -- without them the tool traces back on import
rather than printing usage. On Debian: python3-pil and python3-qrcode,
no pip needed. zbar-tools is not needed to render, only to verify a
render.
QR SIZING
The QR is drawn at an exact integer number of pixels per module and is
never resampled; it is padded out to its target size inside the white
quiet-zone box. Before 2026-09-19 it was drawn oversized and then shrunk
to the target with NEAREST, which at a fractional factor drops module
rows unevenly -- the PNG still looked like a QR and silently did not de‐
code, and not even monotonically in canvas size (issue 774).
Two pixels per module is the floor, measured against zbarimg: at one
pixel per module a decode is luck. A small canvas therefore gets a QR
taking a larger share of it than the nominal 22%, and if not even one
pixel per module fits, the QR is omitted and the reason is printed on
stderr rather than a code being drawn that cannot be scanned.
QR PRIMARY LAYOUT
With --qr-primary the QR's white quiet-zone box targets 68% of the can‐
vas's short side. Because a module is a whole number of pixels and is
never resampled, the box as drawn lands between about 57% and 68% of
that side, and the dark module grid inside it covers roughly 45-50% of
the canvas -- the balance is quiet zone, which the format requires.
That box -- the box, not the bare module grid, so its white padding is
included -- is centered on both axes, to within the pixel that integer
division can cost. Measured at 512x512 with a 57-character payload: dark
grid x 140..372, y 140..372, so left, right, top and bottom margins are
all 140.
The logo badge is 13% of the short side, in the bottom-right corner, in‐
set by the same 3% the default layout insets its QR by. It is sized from
the gap the centered box actually leaves, so it never touches the quiet
zone; where no corner is clear of the box the badge is omitted and says
so on stderr.
RECIPE SCHEMA
shape circle | square | triangle | hex
size "WxH", 16..4096 each dimension
base_color
"#RGB" / "#RRGGBB" or a PIL-recognized name
accent_color
same format, optional
fill solid | pie:DEG | split:N | stripe:N
mark check | x | dot
badge corner_dot | corner_check
label <=4 chars, centered
glyph any unicode, centered (real color emoji via NotoColorEmoji when
applicable, not a missing-glyph box)
OPTIONS
-o OUT.png
Output path. Required unless --read-anchor.
--no-qr
Skip the scannable QR corner badge.
--qr-payload TEXT
Put TEXT in the QR instead of the recipe's anchor URL. Default,
and the behaviour when the flag is absent:
https://spencer.blog.tcos.us/?hash=RECIPE_ID. Used for payloads
that are not the anchor, such as the keyhole token
HK1:kid:half_a.
--qr-primary
Inverse layout: the QR becomes the main element and the rendered
logo becomes the corner badge. For a token scanned off a phone,
where the default 22%-of-canvas corner QR is not a usable target.
Absent this flag the layout is exactly the default one. See QR
PRIMARY LAYOUT below for the share of the canvas it targets and
where the badge goes.
--read-anchor OUT.png
Read the embedded recipe/hash back out instead of rendering. Same
as hee-qr(1)'s PNG-metadata path.
EXAMPLES
render.py hee-recipe.json -o hee-logo.png
render.py --read-anchor hee-logo.png
render.py hee-recipe.json -o token.png --qr-primary \
--qr-payload "HK1:KID:HALFA"
VERIFICATION
sha256sum OUT.png real, reproducible, bit-for-bit across runs
zbarimg --raw OUT.png scans the real QR out of the pixels
tests/test_rrr_qr.py renders at 128..1024 and asserts zbarimg reads
back exactly the payload that went in. It needs python3-qrcode and
zbar-tools, skips when either is absent, and runs in CI where both
are installed.
ORGANIZATION
Twin Cities Open Systems - Operations LLC
IANA Private Enterprise Number: 1.3.6.1.4.1.66550
SEE ALSO
hee-qr(1)
HEE 2026-09-19 MT-LOGO-RENDER(1)