Intelligent pictures (format 4) and direction-aware picture order

Format 4 decoded from Editor output: control words of eight 4-bit ops
(runs up to 13, 12-bit long runs, literal blocks) over 8 colour slots,
plus a run-length 7-bit alpha section. The encoder reproduces all 28
Editor samples byte for byte and the Editor keeps our pictures as is.

Pictures are stored rotated by the display direction, byte 0 of N.i is
0x0A + direction; this applies to format 0 too. add_picture now writes
the right format and order for the project; the renderer decodes format
4 and blends alpha.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-15 16:49:01 +01:00
1 parent a93cb58b96
commit 193bcd5d97
8 files changed
+301 -56

No files matched your search

+189 -35
View File
@@ -13,18 +13,34 @@
``N.i`` header (24 bytes) + pixels::
0 4 0B 64 01 <format> format 0 = raw RGB565 (Basic series), 4 = compressed (Intelligent; OPEN)
0 4 <0A + direction> 64 01 <format> format 0 = raw RGB565 (Basic), 4 = run-length (Intelligent)
4 4 0
8 4 24 (data offset)
12 2 width 14 2 height
16 4 data length (format 0: width * height * 2)
20 4 0
20 4 0; format 4: offset of the alpha section inside the data, 0 = no alpha
Format 0 pixels are RGB565 little-endian, converted by plain truncation (r>>3, g>>2, b>>3) and
stored in the panel's native order: rotated 90 degrees, i.e. for each source column x, the rows
from bottom to top -- byte offset 2 * (x * height + (height - 1 - y)). Verified pixel-exact against
Editor output for a 480x320 and a 64x64 picture on a project with display direction 270 (OPEN:
other directions, main.HMI byte 13).
Pixels are RGB565 little-endian, converted by plain truncation (r>>3, g>>2, b>>3), stored in the
panel's order: the picture rotated by the project's display direction (main.HMI byte 12), see
``stored_order`` -- a landscape Basic project (direction 1) stores column by column, bottom to top.
Verified pixel-exact against Editor output for both formats and all four directions (format 4)
or direction 1 (format 0). Format 0 data is just the pixels; format 4 is below.
Format 4 data (Intelligent series), decoded from Editor output (see docs/FORMAT.md):
u32 1, u32 stored width, u32 stored height (swapped for directions 1 and 3), u32 0, u32 0,
then blocks. Each block is a u32 control word of
eight 4-bit ops (low nibble first) followed by its colours (RGB565 LE, pixels in storage order):
- op 1..13: a run of that many pixels in the colour of the op's slot (slot = nibble index);
- op 14: a run whose 12-bit length is in the next three nibbles (colour of the op's slot);
- op 15: literal pixels, 12-bit count in the next three nibbles; the colours follow the
control word directly and end the block;
- op 0: nothing.
A run block is followed by 8 colour slots (the last block only by the slots it uses).
Alpha section: one byte per pixel run -- with bit 7 set, a single pixel of alpha `b & 0x7F`;
otherwise `b` is the alpha and the next byte the run length. Alpha is 7-bit (`a * 127 // 255`);
fully transparent pixels store colour 0.
Pillow is only needed for converting to/from image files.
"""
@@ -34,7 +50,6 @@ import io
import struct
IS_MAGIC = b"\x0a\x64\x01\x01"
I_MAGIC = b"\x0b\x64\x01"
def source_info(blob: bytes) -> dict:
@@ -59,44 +74,183 @@ def info(blob: bytes) -> dict:
return {"format": blob[3], "width": w, "height": h, "length": n}
def to_rgb565(pixels_rgb, width: int, height: int) -> bytes:
"""pixels_rgb: callable (x, y) -> (r, g, b)."""
out = bytearray(width * height * 2)
for x in range(width):
for y in range(height):
r, g, b = pixels_rgb(x, y)[:3]
v = (r >> 3) << 11 | (g >> 2) << 5 | (b >> 3)
struct.pack_into("<H", out, 2 * (x * height + (height - 1 - y)), v)
return bytes(out)
def stored_order(width: int, height: int, direction: int = 1):
"""(x, y) of each stored pixel, in storage order, for a project display direction (main.HMI
byte 12): the picture rotated with the panel. 0 = row by row; 1 = column by column, each
bottom to top; 2 = rows from the bottom, right to left; 3 = columns from the right, top down.
Measured for both formats in Nextion Editor 1.68."""
d = direction % 4
if d == 0:
return [(x, y) for y in range(height) for x in range(width)]
if d == 1:
return [(x, height - 1 - y) for x in range(width) for y in range(height)]
if d == 2:
return [(width - 1 - x, height - 1 - y) for y in range(height) for x in range(width)]
return [(width - 1 - x, y) for x in range(width) for y in range(height)]
def make_picture(rgb565: bytes, width: int, height: int) -> bytes:
return I_MAGIC + b"\x00" + struct.pack("<IIHHII", 0, 24, width, height, len(rgb565), 0) + rgb565
def _565(c) -> int:
return (c[0] >> 3) << 11 | (c[1] >> 2) << 5 | (c[2] >> 3)
def from_image_file(data: bytes):
"""Image file bytes (png/jpg/bmp) -> (N.i blob, N.is blob). Needs Pillow."""
def to_rgb565(pixels_rgb, width: int, height: int, direction: int = 1) -> bytes:
"""Format-0 pixel data. pixels_rgb: callable (x, y) -> (r, g, b); truncated to RGB565."""
return struct.pack("<%dH" % (width * height), *[_565(pixels_rgb(x, y)) for x, y in stored_order(width, height, direction)])
def make_picture(rgb565: bytes, width: int, height: int, direction: int = 1) -> bytes:
"""Format-0 ``N.i``. Byte 0 is 0x0A + the project's display direction."""
return bytes([0x0A + direction % 4, 0x64, 0x01, 0x00]) + struct.pack("<IIHHII", 0, 24, width, height, len(rgb565), 0) + rgb565
def encode_format4(pixels_rgba, width: int, height: int, direction: int = 0) -> bytes:
"""Format-4 ``N.i`` (Intelligent series), byte-identical to Nextion Editor 1.68's output.
pixels_rgba: callable (x, y) -> (r, g, b[, a]). Colours run in groups of up to 13 pixels;
eight ops make a block; blocks of eight 13-runs of one colour merge into a long run (op 14),
blocks of eight single pixels into a literal block (op 15)."""
order = stored_order(width, height, direction)
rgba = [tuple(pixels_rgba(x, y)) + (255,) for x, y in order]
px = [_565(c) if c[3] else 0 for c in rgba]
alpha = [c[3] * 127 // 255 for c in rgba]
has_alpha = any(a != 127 for a in alpha)
n = len(px)
ops, i = [], 0
while i < n:
j = i
while j < n and px[j] == px[i] and j - i < 13:
j += 1
ops.append((px[i], j - i))
i = j
blocks = [ops[k:k + 8] for k in range(0, len(ops), 8)]
pw, ph = (height, width) if direction % 2 else (width, height)
out = bytearray(struct.pack("<IIIII", 1, pw, ph, 0, 0))
def long_run(b, colour):
return len(b) == 8 and all(c == colour and length == 13 for c, length in b)
def literal(b):
return len(b) == 8 and all(length == 1 for _, length in b)
k = 0
while k < len(blocks):
b = blocks[k]
if long_run(b, b[0][0]):
m = k
while m < len(blocks) and long_run(blocks[m], b[0][0]) and (m - k + 1) * 104 <= 0xFFF:
m += 1
out += struct.pack("<I8H", 14 | (m - k) * 104 << 4, *[b[0][0]] * 8)
k = m
elif literal(b):
m = k
while m < len(blocks) and literal(blocks[m]) and (m - k + 1) * 8 <= 0xFFF:
m += 1
cols = [c for bb in blocks[k:m] for c, _ in bb]
out += struct.pack("<I%dH" % len(cols), 15 | len(cols) << 4, *cols)
k = m
else:
ctrl = 0
for slot, (_, length) in enumerate(b):
ctrl |= length << (4 * slot)
out += struct.pack("<I8H", ctrl, *([c for c, _ in b] + [0] * (8 - len(b))))
k += 1
aoff = 0
if has_alpha:
aoff, i = len(out), 0
while i < n:
j = i
while j < n and alpha[j] == alpha[i] and j - i < 255:
j += 1
out += bytes([0x80 | alpha[i]]) if j - i == 1 else bytes([alpha[i], j - i])
i = j
return bytes([0x0A + direction % 4, 0x64, 0x01, 0x04]) + struct.pack("<IIHHII", 0, 24, width, height, len(out), aoff) + bytes(out)
def from_image_file(data: bytes, direction: int = 1, series: int = 0):
"""Image file bytes (png/jpg/bmp) -> (N.i blob, N.is blob). Needs Pillow.
series 0 (Basic) writes format 0, series 3 (Intelligent) format 4 with alpha."""
from PIL import Image
img = Image.open(io.BytesIO(data))
ftype = (img.format or "png").lower()[:3]
rgb = img.convert("RGB")
px = rgb.load()
w, h = rgb.size
return make_picture(to_rgb565(lambda x, y: px[x, y], w, h), w, h), make_source(data, w, h, ftype)
w, h = img.size
if series == 3 and w * h > 2: # the Editor keeps 1-2 pixel pictures in format 0
rgba = img.convert("RGBA").load()
pic = encode_format4(lambda x, y: rgba[x, y], w, h, direction)
else:
rgb = img.convert("RGB").load()
pic = make_picture(to_rgb565(lambda x, y: rgb[x, y], w, h, direction), w, h, direction)
return pic, make_source(data, w, h, ftype)
def decode_format4(blob: bytes):
"""Format-4 ``N.i`` -> (width, height, [rgb565 per pixel], [alpha 0..127] or None), in storage order."""
w, h, plen, aoff = struct.unpack_from("<HHII", blob, 12)
p = blob[24:24 + plen]
n = w * h
end = aoff or len(p)
px = []
o = 20
while len(px) < n and o + 4 <= end:
ctrl, = struct.unpack_from("<I", p, o)
o += 4
nib = [(ctrl >> (4 * i)) & 15 for i in range(8)] + [0, 0, 0]
i, runs, literal = 0, [], 0
while i < 8:
op = nib[i]
if op == 15:
literal = nib[i + 1] | nib[i + 2] << 4 | nib[i + 3] << 8
break
if op == 14:
runs.append((i, nib[i + 1] | nib[i + 2] << 4 | nib[i + 3] << 8))
i += 4
continue
if op:
runs.append((i, op))
i += 1
if literal:
px.extend(struct.unpack_from("<%dH" % literal, p, o))
o += 2 * literal
continue
used = 0
for slot, length in runs:
colour, = struct.unpack_from("<H", p, o + 2 * slot)
px.extend([colour] * length)
used = slot + 1
o += 2 * (8 if len(px) < n else used)
if len(px) < n:
raise ValueError("format 4 picture: %d of %d pixels decoded" % (len(px), n))
alpha = None
if aoff:
alpha, q = [], aoff
while len(alpha) < n:
v = p[q]
if v & 0x80:
alpha.append(v & 0x7F)
q += 1
else:
alpha.extend([v] * p[q + 1])
q += 2
return w, h, px[:n], (alpha[:n] if alpha else None)
def _rgb(v: int):
r, g, b = v >> 11, (v >> 5) & 63, v & 31
return (r << 3 | r >> 2, g << 2 | g >> 4, b << 3 | b >> 2)
def to_image(blob: bytes):
"""Decode a format-0 ``N.i`` to a Pillow image."""
"""Decode an ``N.i`` (format 0 or 4) to a Pillow image; RGBA when the picture has alpha."""
from PIL import Image
d = info(blob)
if d["format"] != 0:
raise NotImplementedError("picture format %d (Intelligent compressed) not supported yet" % d["format"])
w, h = d["width"], d["height"]
img = Image.new("RGB", (w, h))
px = img.load()
for x in range(w):
for y in range(h):
v, = struct.unpack_from("<H", blob, 24 + 2 * (x * h + (h - 1 - y)))
r, g, b = v >> 11, (v >> 5) & 63, v & 31
px[x, y] = (r << 3 | r >> 2, g << 2 | g >> 4, b << 3 | b >> 2)
direction = (blob[0] - 0x0A) % 4
order = stored_order(w, h, direction)
if d["format"] == 4:
_, _, px, alpha = decode_format4(blob)
elif d["format"] == 0:
px, alpha = struct.unpack_from("<%dH" % (w * h), blob, 24), None
else:
raise NotImplementedError("picture format %d not supported" % d["format"])
img = Image.new("RGBA" if alpha else "RGB", (w, h))
out = img.load()
for i, (x, y) in enumerate(order):
out[x, y] = _rgb(px[i]) + (((alpha[i] * 255 + 63) // 127,) if alpha else ())
return img
+5 -2
View File
@@ -215,12 +215,15 @@ def main_insert_resource(main: bytes, rtype: str, name: str) -> bytes:
def add_picture(h: HMIFile, image_file: bytes) -> int:
"""Add a picture (png/jpg/bmp bytes) to the project; returns its picture id. Basic series only."""
"""Add a picture (png/jpg/bmp bytes) to the project; returns its picture id. Written the way
the Editor would: format 0 on Basic, format 4 (with alpha) on Intelligent displays, rotated
for the project's display direction."""
from . import pictures
n = 0
while h.find("%d.i" % n):
n += 1
pic, src = pictures.from_image_file(image_file)
main = h.read("main.HMI")
pic, src = pictures.from_image_file(image_file, direction=main[12] % 4, series=main[11])
h.write("%d.is" % n, src)
h.write("%d.i" % n, pic)
h.write("main.HMI", main_insert_resource(h.read("main.HMI"), "i", "%d.i" % n))
+4 -1
View File
@@ -185,7 +185,10 @@ class Renderer:
w = min(w, src.width - sx)
h = min(h, src.height - sy)
if w > 0 and h > 0:
img.paste(src.crop((sx, sy, sx + w, sy + h)), (dx, dy))
part = src.crop((sx, sy, sx + w, sy + h))
# Intelligent pictures can carry alpha: blended over what is below (blend not yet
# compared with the Editor pixel by pixel)
img.paste(part, (dx, dy), part if part.mode == "RGBA" else None)
def _box(self, c):
x, y, w, h = c.get("x"), c.get("y"), c.get("w"), c.get("h")