From c102157ac22793629f3569d5a8bdc492587c8392 Mon Sep 17 00:00:00 2001 From: MangaValk Date: Mon, 16 Nov 2026 13:22:25 +0100 Subject: [PATCH] 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 --- README.md | 2 +- docs/COVERAGE.md | 3 +- docs/FORMAT.md | 12 ++++- src/nxhmi/cli.py | 7 ++- src/nxhmi/mcp_server.py | 9 ++-- src/nxhmi/pictures.py | 104 ++++++++++++++++++++++++++++++++++++---- src/nxhmi/project.py | 7 +-- tests/test_media.py | 31 ++++++++++++ 8 files changed, 152 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 341bb5f..7d80929 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Every percentage is a count with a stated basis, so it can be checked (details i | Checksums (`.HMI`) | **100 %** (3/3) | page, project header, file table | | Component types (read, write, create) | **100 %** (31/31) | all types in the Editor's toolbox, incl. 11 Intelligent-only | | Display series | **40 %** (2/5) | Basic (T) and Intelligent (P) confirmed; Discovery, Enhanced, Edge not sampled | -| Picture formats | **100 %** (2/2) | raw RGB565 (Basic) and run-length + alpha (Intelligent), byte-identical to the Editor, every display direction | +| Picture formats | **100 %** (2/2) | raw RGB565 (Basic) and run-length + alpha or JPEG for quality < 100 (Intelligent), byte-identical to the Editor (transparent JPEG pictures: near-identical), every display direction | | Font modes | **100 %** (2/2) | black/white and "anti-aliased" (a header flag; glyphs stay 1-bit, verified in the simulator); Editor fonts with overhanging glyphs round-trip byte-identical | | Readable attribute names in JSON | **100 %** (31/31 types) | every value list the Editor documents, incl. the Intelligent-only types and load effects | | Rendering, Basic components | **100 %** (20/20 pixel-exact) | incl. gauges and QR codes (own encoder, no dependencies) | diff --git a/docs/COVERAGE.md b/docs/COVERAGE.md index 0fb963c..d3745e8 100644 --- a/docs/COVERAGE.md +++ b/docs/COVERAGE.md @@ -13,7 +13,7 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th | Checksums (page, project header, file table) | **complete**, verified | | Components | **31 / 31 types** (20 Basic + 11 Intelligent-only) read/write/create | | Readable JSON (enum names, colours) | done for every value list the Editor documents | -| Pictures | **complete**: format 0 (Basic) and format 4 (Intelligent, with alpha), all display directions | +| Pictures | **complete**: format 0 (Basic) and format 4 (Intelligent, with alpha; run-length or JPEG for quality < 100), all display directions | | Fonts | **complete** for single-byte encodings: black/white and the anti-aliasing flag, overhanging glyphs, all display directions | | Rendering pages like the Editor | **pixel-identical** for every Basic component and 9 of 11 Intelligent-only ones; ComboBox and Switch approximate at anti-aliased edges | | New projects from scratch | `project.new_project(model)` for 12 Basic/Intelligent models; the generated demo is byte-identical to the Editor's re-save | @@ -93,7 +93,6 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th ### `.HMI` side | Item | Notes | |---|---| -| Picture quality below 100 (Editor picture list "Q:") | not studied | | Multi-byte encodings (GB2312, Big5, ...) | only single-byte fonts studied | | Other display series | Discovery / Enhanced / Edge not sampled; only Basic + Intelligent templates | | Display direction | byte 12 decoded and written (`new_project(portrait=...)`); picture order verified for all four (format 4); font glyph order for 90° only | diff --git a/docs/FORMAT.md b/docs/FORMAT.md index 13061f2..ba75da2 100644 --- a/docs/FORMAT.md +++ b/docs/FORMAT.md @@ -235,7 +235,17 @@ four directions, with and without alpha): - Pictures of 1-2 pixels stay format 0 (seen: 1x1, 2x1, 1x2; 8x1 is converted); nxhmi does the same. The Editor shows a message box per picture while converting format-0 pictures it finds in an Intelligent project. -- **OPEN**: the "Q:100" quality shown in the Editor's picture list -- only quality 100 studied. +- Compressed quality (picture list right-click > "Compressed quality setting", 1-99; shown as + "Q:nn"): header byte 1 = quality (100 = 0x64 for the run-length variant). Data: u32 **0** + (JPEG), u32 width and height padded up to multiples of 16, u32 0, u32 0, then a baseline JPEG + of the padded picture (black padding at the right/bottom, *then* rotated into stored order), + 4:2:0, 96 dpi JFIF -- byte-identical to libjpeg (Pillow) at that quality for opaque pictures + (18/18 samples: qualities 1/30/50/99, landscape and portrait). Then, if the picture has alpha, + the same alpha run section, covering the *padded* picture (padding alpha 0), at the offset in + header +20. With alpha the Editor first passes the colours through premultiplied alpha; nxhmi + approximates that step (JPEG a few levels off in some pixels; alpha section identical). The + simulator decodes the JPEG like libjpeg (opaque pictures render pixel-exact); transparent ones + blend within 1 level. Adding a picture = `N.is` + `N.i` + a `i`/`N.i` resource-list entry (kept grouped with the other `i` entries) -- verified in the Editor. diff --git a/src/nxhmi/cli.py b/src/nxhmi/cli.py index e9d34f1..d28377c 100644 --- a/src/nxhmi/cli.py +++ b/src/nxhmi/cli.py @@ -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") diff --git a/src/nxhmi/mcp_server.py b/src/nxhmi/mcp_server.py index cb1b599..d165711 100644 --- a/src/nxhmi/mcp_server.py +++ b/src/nxhmi/mcp_server.py @@ -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"]), diff --git a/src/nxhmi/pictures.py b/src/nxhmi/pictures.py index d7bf989..2dc02c0 100644 --- a/src/nxhmi/pictures.py +++ b/src/nxhmi/pictures.py @@ -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(" 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(" 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(" (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(" Pillow image in display orientation (RGBA if it has alpha).""" + from PIL import Image + w, h, plen, aoff = struct.unpack_from(" (width, height, [rgb565 per pixel], [alpha 0..127] or None), in storage order.""" w, h, plen, aoff = struct.unpack_from(" 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)) diff --git a/tests/test_media.py b/tests/test_media.py index c36d593..94c9974 100644 --- a/tests/test_media.py +++ b/tests/test_media.py @@ -95,6 +95,37 @@ class Format4(unittest.TestCase): self.assertEqual(img.getpixel((1, 0))[3], 226) # 227 * 127 // 255 = 113 -> 226 self.assertEqual(img.getpixel((2, 0))[3], 2) + @unittest.skipUnless(HAVE_PIL, "needs Pillow") + def test_jpeg_quality(self): + # "Compressed quality setting" < 100: JPEG, padded to 16 px with black, rotated by direction, + # header byte 1 = quality (layout byte-identical to Nextion Editor 1.68 for opaque pictures) + import io + from PIL import Image + f = lambda x, y: (x * 6, y * 8, (x * y) % 256) + blob = pictures.encode_jpeg(f, 40, 30, 0, 50) + self.assertEqual(blob[:2], bytes([0x0A, 0x32])) + self.assertTrue(pictures.is_jpeg(blob)) + self.assertEqual(struct.unpack_from("