Files
openhmi-nx/docs/RENDER.md
T
mangavalkandClaude Opus 5.5 49fee337d7 Render Intelligent-only components; fonts follow the display direction
- SLText, TextSelect, DataRecord, FileBrowser pixel-exact against the Intelligent simulator;
  ComboBox and Switch with approximate anti-aliased edges; media/file components draw nothing
- fonts: header byte 3 = 0x0A + direction, glyphs in the direction's pixel order, Intelligent
  glyph data 4-byte aligned -- reproduces the Editor's own font conversion byte for byte
- Intelligent 3D frames: left edge drawn over the bottom edge

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

7.4 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)

Intelligent-only components, checked against the Intelligent simulator (5 test pages, 23 TextSelects, several of each other type):

Component Match Notes
SLText 100 % text from the top-left inside the frame
TextSelect (hig, val, borders, fonts, cut cells) 100 % see rules below
DataRecord (header, 1-5 columns, styles) 100 % records only exist at run time
FileBrowser 100 % frame and fill; the file list only exists at run time
ExPicture, video, audio, Gmov, FileStream nothing drawn (same as the simulator) they show content only once a file is loaded
ComboBox ~99 % structure exact; anti-aliased corners and arrow approximate
Switch ~88-97 % structure exact; anti-aliased knob and track edges approximate

Rules learned from the Editor

  • Colours: RGB565 is expanded differently per series. Basic replicates the top bits (r<<3 | r>>2); Intelligent scales (r*255//31, g*255//63), so 0xC618 shows as (198,195,198) on Basic and (197,194,197) on Intelligent.
  • Intelligent 3D frames draw the left edge after the bottom one (dark bottom-left corner on 3D down); Basic draws it the other way round.
  • TextSelect: items (path, CR LF separated) in cells of hig rows inside the frame; the selected cell starts at iy + (ih - hig) // 2 and its two pco1 lines are mirrored (top and iy + ih - 1 - (ih - hig) // 2); selected text pco2, others pco; val out of range selects item 0; the list wraps around. Text is centred in its full cell and clipped to the frame; a cell cut by the screen bottom centres in the part on screen. Rows within hig of the top/bottom edge fade into bco: 7-bit alpha (127 // hig) * d, blended (fg*a + bg*(127-a)) // 127.
  • DataRecord: dez columns named by dir (^-separated); column lines in gdc every (iw - 1) // dez px, the last (iw - 1) % dez columns one px wider; header hig rows in bco1, names in pco1 placed by xcen, vertically centred.
  • Switch: track bco/bco2 (on), knob pco/pco2, text txt = "off/on" in pco1 centred in [h, w) (off) or [0, w-h) (on). ComboBox: text placed by xcen/ycen over the whole box, pco3 arrow wid px wide 4.5 px from the right edge. Corner radius for both: dis * h // 200, square below 3 px; rounded shapes are inset half a pixel (outer ring 50 %, blended linearly).
  • Intelligent pictures with alpha (format 4, 7-bit alpha a): 8-bit alpha is 2*a (127 = 255), blended as bg + round((src - bg) * alpha / 255) per channel. Exact against the Intelligent simulator (342 samples). The Editor canvas blends slightly differently (up to 3 levels off at high alpha); the renderer follows the simulator, i.e. the display.
  • 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.