perf: crop element transforms, composite dlimg in place, cache fonts and QR codes

[balloob]

Summary

Four performance fixes — one worst-case (per-element transforms) and three steady-state (dlimg, fonts, QR). No visual change: the transform change is verified pixel-identical to the previous full-canvas path (see tests).

Findings addressed

• B1 — per-element transforms were ~1000× more expensive than needed. _render_transformed transformed and alpha-composited the entire canvas per transformed element (measured: 40 small rects on 800×480 → 0.3 ms plain vs 496 ms with rotation: 45 on each). New apply_transform_region crops the layer to the pivot-centered bounding radius (mirror and rotation are isometries about the pivot, so every non-transparent pixel stays within the farthest-bbox-corner distance), plus a resampling margin, transforms just that crop, and composites it back at the right offset. Cost is now proportional to the element, not the canvas.
• B3 — dlimg composited the whole canvas three times per image. Replaced the full-canvas Image.new + paste + alpha_composite + paste-back (~35× overhead) with an in-place ctx.img.alpha_composite(source, (x, y)), clipping to the canvas first so a partially off-canvas image still doesn't raise.
• B4 — fonts re-read from disk every render. generate_image builds a fresh FontManager per call, so its cache never survived — every render re-ran ImageFont.truetype (blocking disk I/O on the event loop). Added a module-level (path, size) truetype cache shared across instances, mirroring the existing MDI font cache. The per-instance cache (and clear_cache) are unchanged.
• B5 — QR codes regenerated every render. Generation is ~5 ms (mostly the library's best-mask-pattern search over all 8 masks) and dashboards re-render the same QR (Wi-Fi creds, URL) every update. Added an LRU cache (maxsize=32) keyed by (data, boxsize, border, fill, back) holding the rendered RGBA image.

Correctness of B1

apply_transform_region is proven equivalent to apply_transform + full composite: mirror (reflection across an axis through the pivot) and rotation (about the pivot) both preserve distance to the pivot, so a crop of radius ⌈max-corner-distance⌉ + 2px (the +2 covers the BICUBIC kernel support), clipped to the canvas, contains all source and transformed pixels; transforming it about the translated pivot yields identical output. Verified numerically over a battery of cases (rotation, mirror+rotation, off-center pivot, near-edge clipping) — all pixel-identical.

Tests

Unit tests assert apply_transform_region matches the full path pixel-for-pixel across rotation / mirror+rotation / off-center pivot / near-edge clipping, that the font cache is shared across FontManager instances and keyed on size, and that identical QR inputs reuse a cached render. No new failures (pre-existing tests/visual/* byte-snapshot failures under Pillow 12 are unrelated).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/odl_renderer/elements/media.py	94.44%	1 Missing ⚠️
src/odl_renderer/transforms.py	96.15%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!