Files
openhmi-nx/docs/RENDER.md
T
mangavalkandClaude Opus 5.5 842591a14c Render QR codes pixel-exact with an own encoder
nxhmi.qr is a dependency-free QR encoder. Measured in the Editor
simulator: numeric/alphanumeric/byte mode by content, level L, mask 0,
smallest version; scaled to w - 2*dis by width (not clipped to h), last
column run one pixel narrower, logo centred, nothing when too small.
Basic rendering is now 20/20 pixel-exact.

Also: unknown component kinds give a clean CLI error instead of a
traceback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 16:17:23 +01:00

4.7 KiB

Page rendering vs. Nextion Editor

python -m nxhmi render project.HMI out/ draws every page the way Nextion Editor 1.68 shows it on its canvas. Verified by capturing the Editor's canvas at 100 % zoom and comparing pixel by pixel (ignoring the Editor's yellow name tags and its 2-px selection outline).

Results

The demo project (demo/demo.HMI, built by examples/make_demo.py):

Page Differing pixels Notes
home 25 name-tag edges (checkbox, buttons)
controls 5 name-tag edges
gallery 1 name-tag edge

A real 6-page user project (pictures, 32-px bitmap font, texts, 3D buttons, sliders): every page pixel-identical apart from 0-5 px at name-tag edges.

Per component (dedicated test pages):

Component Match Notes
text (all xcen/ycen, solid / crop / image background, border, 3D up/down) 100 %
text with word wrap 100 % the text block is aligned as a whole, lines left-aligned in it
number (plain, fixed length, hex, currency, negative), xfloat 100 %
button, dual-state button (colour and picture skins, on/off) 100 % "on" with 3D style is drawn pressed (3D down)
scrolling text (static) 100 %
progress bar (horizontal, vertical, picture mode) 100 %
slider (horizontal, vertical, auto cursor, picture background and cursor) 100 % auto cursor = square as thick as the slider; position truncates
checkbox (3D down, border, flat) 100 %
picture, crop (also smaller than the component) 100 % only the picture's real area is drawn
waveform (frame + grid) 100 % horizontal grid lines count from the bottom
gauge (every angle, needle width 1-8, odd/even/non-square sizes) 100 % the needle routine, see below
radio (all sizes, also non-square) 100 % the display's own circle routine, see below
QR code (byte/alphanumeric/numeric text, versions 1-8, margins, colours, logo, Latin-1) 100 % own encoder (nxhmi.qr), see below
hotspot, touch cap, timer, variable nothing drawn (same as the Editor)

Rules learned from the Editor

  • Text never starts above/left of its box: centring clamps at 0 (a 32-px font in a 30-px box starts at the top).
  • Text is laid out inside the border: 1 px for 3D styles, borderw for style "border".
  • 3D colours are fixed: light (230,226,230), dark (65,68,65) -- top/left light for 3D up/auto, dark for 3D down.
  • Buttons with a picture background (sta crop or image) get no frame.
  • Pictures are pasted at their real size; a smaller picture leaves the rest untouched.
  • Checkbox: bco fill, style frame, checked = pco square from w/4 to 3w/4.
  • Radio: circle sized by the component width (clipped to the box); ring radius r = (w-1)//2 around (r, r), colour (65,68,65), filled with bco; checked = pco dot of radius r // 2.
  • Circles (radio, and the display's cir/cirs commands): incremental midpoint routine -- start at x = r, y = 0; plot the 8 symmetric points; y += 1; if x*x - x + y*y + 2*y > r*r + 1 then x -= 1; repeat while x >= y. Filled circles are every pixel inside that ring. Verified for every radius 1..159 against the Editor's simulator.
  • Gauge needle (verified on 112 needles): centre (w//2, h//2), length h//2 - wid (the height sets it, also for non-square gauges, so the needle can leave the box). Tip = centre + (int(-len*cos a), int(-len*sin a)) with val in degrees, 0 = left, 90 = up, where sin/cos are taken after reducing the angle to 0..90 degrees (so sin 30 is a hair under 0.5 and 24*sin 30 truncates to 11). The line runs from the tip to the centre: step the major axis, minor offset (k*minor + minor - 1) // major. Width > 1: every line pixel is stamped with a wid x wid square starting at -(wid//2).
  • QR code: the text's bytes (iso-8859-1) encoded in numeric mode if all digits, alphanumeric if all in 0-9A-Z $%*+-./:, else byte mode; error correction L, mask 0 always, the smallest version that fits. Drawn into a square of w - 2*dis px at (dis, dis) -- sized by the width only and not clipped to h; pixel p shows module p*N//size. Dark runs are drawn column by column and the last one (last column, reaching the bottom) is one pixel narrower. Fewer pixels than modules or empty text: only the bco background. sta 1: picture pic pasted centred in the box. Big codes can exceed a Basic display's RAM (the Editor refuses to compile), the canvas still draws them.
  • Slider: auto cursor (255) is a square as thick as the slider; position = int(frac * free).
  • Waveform: vertical grid lines from the left edge, horizontal ones counted from the bottom.

Not covered yet: Intelligent-only components (need Intelligent picture format 4), anti-aliased fonts, pressed/runtime states.