Pictures with compressed quality < 100 (JPEG variant of format 4)

Header byte 1 = quality; data type 0 = baseline JPEG of the picture padded with black to
multiples of 16 and then rotated for the display direction (libjpeg/Pillow, 4:2:0, 96 dpi),
byte-identical to the Editor for opaque pictures (18/18); alpha runs cover the padded picture.
add_picture(quality=), CLI add-picture -q, MCP add_picture quality; decoder in to_image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-16 13:22:25 +01:00
1 parent 55c2f9d6b6
commit c102157ac2
8 files changed
+152 -23

No files matched your search

+5 -2
View File
@@ -126,7 +126,7 @@ def cmd_add_picture(a):
from . import project
h = HMIFile.load(a.hmi)
with open(a.image, "rb") as f:
pid = project.add_picture(h, f.read())
pid = project.add_picture(h, f.read(), quality=a.quality)
h.save(a.out or a.hmi)
print("added picture id", pid)
@@ -195,7 +195,10 @@ def main(argv=None):
s.add_argument("--encoding", default="ascii", choices=["ascii", "iso-8859-1"])
s.add_argument("--fixed-width", type=int); s.add_argument("-o", "--out"); s.set_defaults(f=cmd_add_font)
s = sub.add_parser("add-picture", help="add a picture (png/jpg/bmp; needs Pillow)")
s.add_argument("hmi"); s.add_argument("image"); s.add_argument("-o", "--out"); s.set_defaults(f=cmd_add_picture)
s.add_argument("hmi"); s.add_argument("image"); s.add_argument("-o", "--out")
s.add_argument("-q", "--quality", type=int, default=100,
help="1-99: store as JPEG (Intelligent only, like the Editor's compressed quality)")
s.set_defaults(f=cmd_add_picture)
s = sub.add_parser("new-page", help="add an empty page"); s.add_argument("hmi"); s.add_argument("name")
s.add_argument("-o", "--out"); s.set_defaults(f=cmd_new_page)
s = sub.add_parser("dump", help="print pages as JSON"); s.add_argument("hmi"); s.add_argument("--page")
+5 -4
View File
@@ -150,10 +150,10 @@ def t_new_project(path, model="NX4832T035_011", first_page="page0", portrait=Fal
return t_info(path)
def t_add_picture(path, image_path):
def t_add_picture(path, image_path, quality=100):
h = _load(path)
with open(image_path, "rb") as f:
pid = project.add_picture(h, f.read())
pid = project.add_picture(h, f.read(), quality=int(quality))
h.save(path)
return {"picture_id": pid}
@@ -240,8 +240,9 @@ TOOLS = {
"new_project": (t_new_project, "Create a new project file (refuses to overwrite). Models: see nxhmi.models. "
"Landscape unless portrait is true; encoding as in the Editor (iso-8859-1, utf-8, gb2312, ...).",
{"path": S, "model": S, "first_page": S, "portrait": {"type": "boolean"}, "encoding": S}, ["path"]),
"add_picture": (t_add_picture, "Add a picture from an image file (png/jpg/bmp); returns its picture id.",
{"path": S, "image_path": S}, ["path", "image_path"]),
"add_picture": (t_add_picture, "Add a picture from an image file (png/jpg/bmp); returns its picture id. "
"quality 1-99 stores a JPEG (Intelligent displays only, smaller), default 100.",
{"path": S, "image_path": S, "quality": {"type": "integer"}}, ["path", "image_path"]),
"add_font": (t_add_font, "Add a font rasterized from a TrueType file (omit ttf_path for the bundled CC0 font).",
{"path": S, "height": {"type": "integer"}, "ttf_path": S, "encoding": S}, ["path", "height"]),
"verify": (t_verify, "Check every checksum in the project.", {"path": S}, ["path"]),
+94 -10
View File
@@ -103,6 +103,57 @@ def make_picture(rgb565: bytes, width: int, height: int, direction: int = 1) ->
return bytes([0x0A + direction % 4, 0x64, 0x01, 0x00]) + struct.pack("<IIHHII", 0, 24, width, height, len(rgb565), 0) + rgb565
def _alpha_runs(alpha) -> bytes:
"""7-bit alpha, run-length coded: a byte with bit 7 set is one pixel, else (value, count)."""
out, i, n = bytearray(), 0, len(alpha)
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(out)
def encode_jpeg(pixels_rgba, width: int, height: int, direction: int = 0, quality: int = 80) -> bytes:
"""Format-4 ``N.i`` with "compressed quality" below 100 (Intelligent series). The picture is
padded with black to multiples of 16 (right/bottom), rotated into stored order for the display
direction, and saved as a baseline JPEG (libjpeg via Pillow: given quality, 4:2:0, 96 dpi);
header byte 1 = quality; then the same 7-bit alpha runs as the run-length variant, over the
padded picture (padding transparent).
Byte-identical to Nextion Editor 1.68 for opaque pictures. Transparent pictures: the Editor
passes colours through premultiplied alpha first; this is approximated (a few levels off in
some pixels), the result is still a valid picture."""
import io
from PIL import Image
pw0, ph0 = -(-width // 16) * 16, -(-height // 16) * 16
src = [[(0, 0, 0, 0)] * pw0 for _ in range(ph0)] # padding: black, transparent
opaque = True
for y in range(height):
for x in range(width):
c = tuple(pixels_rgba(x, y)) + (255,)
a = c[3]
opaque = opaque and a * 127 // 255 == 127
if a < 255: # premultiplied round trip (GDI+-like); fully transparent -> black
c = tuple(0 if a == 0 else min(255, (((v * a + 127) // 255) * ((255 << 16) // a)) >> 16)
for v in c[:3]) + (a,)
src[y][x] = c
order = stored_order(pw0, ph0, direction)
jw, jh = (ph0, pw0) if direction % 2 else (pw0, ph0)
img = Image.new("RGB", (jw, jh))
img.putdata([src[y][x][:3] for x, y in order])
buf = io.BytesIO()
img.save(buf, "JPEG", quality=quality, subsampling=2, dpi=(96, 96))
out = bytearray(struct.pack("<IIIII", 0, jw, jh, 0, 0)) + buf.getvalue()
aoff = 0
if not opaque: # alpha covers the padded picture too
aoff = len(out)
out += _alpha_runs([src[y][x][3] * 127 // 255 for x, y in order])
return bytes([0x0A + direction % 4, quality, 0x01, 0x04]) + struct.pack("<IIHHII", 0, 24, width, height, len(out), aoff) + bytes(out)
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;
@@ -154,32 +205,63 @@ def encode_format4(pixels_rgba, width: int, height: int, direction: int = 0) ->
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
aoff = len(out)
out += _alpha_runs(alpha)
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):
def from_image_file(data: bytes, direction: int = 1, series: int = 0, quality: int = 100):
"""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."""
series 0 (Basic) writes format 0, series 3 (Intelligent) format 4 with alpha: run-length coded
at quality 100, a JPEG below (the Editor's "Compressed quality setting", 1-99)."""
from PIL import Image
img = Image.open(io.BytesIO(data))
ftype = (img.format or "png").lower()[:3]
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)
if quality < 100:
pic = encode_jpeg(lambda x, y: rgba[x, y], w, h, direction, quality)
else:
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 is_jpeg(blob: bytes) -> bool:
"""Format-4 picture stored as JPEG (quality below 100): data starts with type word 0."""
return info(blob)["format"] == 4 and struct.unpack_from("<I", blob, 24)[0] == 0
def decode_jpeg(blob: bytes):
"""JPEG-variant format-4 ``N.i`` -> Pillow image in display orientation (RGBA if it has alpha)."""
from PIL import Image
w, h, plen, aoff = struct.unpack_from("<HHII", blob, 12)
p = blob[24:24 + plen]
_, jw, jh = struct.unpack_from("<III", p, 0)
j = Image.open(io.BytesIO(p[20:aoff or len(p)])).convert("RGB")
direction = (blob[0] - 0x0A) % 4
pw0, ph0 = (jh, jw) if direction % 2 else (jw, jh)
order = stored_order(pw0, ph0, direction)
stored = list(j.getdata())
alpha = None
if aoff:
alpha, a, i = [], p[aoff:], 0
while i < len(a):
if a[i] & 0x80:
alpha.append(a[i] & 0x7F); i += 1
else:
alpha += [a[i]] * a[i + 1]; i += 2
img = Image.new("RGBA" if alpha else "RGB", (w, h))
out = img.load()
for i, (x, y) in enumerate(order):
if x < w and y < h:
out[x, y] = stored[i] + ((255 if alpha[i] == 127 else 2 * alpha[i],) if alpha else ())
return img
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)
@@ -243,6 +325,8 @@ def to_image(blob: bytes):
w, h = d["width"], d["height"]
direction = (blob[0] - 0x0A) % 4
order = stored_order(w, h, direction)
if d["format"] == 4 and is_jpeg(blob):
return decode_jpeg(blob)
if d["format"] == 4:
_, _, px, alpha = decode_format4(blob)
elif d["format"] == 0:
+4 -3
View File
@@ -214,16 +214,17 @@ def main_insert_resource(main: bytes, rtype: str, name: str) -> bytes:
return bytes(b)
def add_picture(h: HMIFile, image_file: bytes) -> int:
def add_picture(h: HMIFile, image_file: bytes, quality: int = 100) -> int:
"""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."""
for the project's display direction. ``quality`` < 100 (Intelligent only) stores a JPEG, like
the Editor's "Compressed quality setting"."""
from . import pictures
n = 0
while h.find("%d.i" % n):
n += 1
main = h.read("main.HMI")
pic, src = pictures.from_image_file(image_file, direction=main[12] % 4, series=main[11])
pic, src = pictures.from_image_file(image_file, direction=main[12] % 4, series=main[11], quality=quality)
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))