Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
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)