ghostbt 0.2.0__tar.gz → 0.2.2__tar.gz

{ghostbt-0.2.0 → ghostbt-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ghostbt
-Version: 0.2.0
+Version: 0.2.2
 Summary: Ghost Build Tool - build and package GhostESP native SD apps
 License-Expression: GPL-3.0
 Project-URL: Homepage, https://github.com/GhostESP-Revival/GhostESP
@@ -131,17 +131,31 @@ When loading a `.gtheme`, firmware streams entries into `/mnt/ghostesp/themes/ac
 
 ### PSRAM vs internal RAM
 
-**PSRAM devices:** Up to 32 icons cached in PSRAM, tiled or scaled backgrounds supported. Background images smaller than the screen tile automatically; larger images scale to fill using LVGL zoom. A 128x128 background will scale up to fill any screen. Background images are always loaded into PSRAM.
+**PSRAM devices:** Up to 32 icons cached in PSRAM, tiled or scaled backgrounds supported. Background images smaller than the screen tile automatically; larger images scale to fill using LVGL zoom. A 128x128 background will scale up to fill any screen. Background images are always loaded into PSRAM. Any image format works; deflate-compressed payloads decode into PSRAM.
 
-**Internal-only devices:** 2 icons cached in internal RAM, no background images. Icons fall back to compiled-in artwork when cache is full. The pack still loads colors and icon mappings; only the image cache is limited.
+**Internal-only devices:** 2 icons cached in internal RAM. Background tile (≤32x32) supported — LVGL tiles the small image across the screen. Icon size capped at 32x32 RGB565A8; deflate-compressed payloads rejected. Use the `indexed_4bpp` format for icons and the background tile to fit in internal RAM: a 32x32 indexed icon is 576 bytes vs 3,072 bytes for RGB565A8 (~5x smaller). Icons fall back to compiled-in artwork when the cache is full. The pack still loads colors and icon mappings; only the image cache is limited.
+
+### Image formats
+
+| Format | Code | Size at 32x32 | Notes |
+|--------|------|---------------|-------|
+| `rgb565` | 1 | 2,048 B | No alpha. Best for opaque backgrounds. |
+| `rgb565a8` | 2 | 3,072 B | RGB565 + separate alpha plane. Default for icons. |
+| `indexed_4bpp` | 3 | 576 B | 16-color palette, packed 4-bit pixels. Ideal for internal-RAM devices; the `gbt` tool quantizes the source PNG at build time. |
+
+Set the pack-wide icon format with `icon_format` in the source manifest, or override per-background via the `format` field on each `background_sources` entry. Indexed payloads are always stored uncompressed.
 
 Convert one image directly:
 
 ```bash
+# Default — RGB565A8, 3 KB for 32x32
 gbt asset image ./wifi.png --out ./wifi_l.gimg --width 64 --height 64 --format rgb565a8
+
+# Internal-RAM friendly — indexed 4bpp, 576 B for 32x32
+gbt asset image ./wifi.png --out ./wifi_l.gimg --width 64 --height 64 --format indexed_4bpp
 ```
 
-The generated pack folder contains `manifest.json`, `checksums.json`, and generated `.gimg` files. Asset packs store raw `.gimg` payloads by default so firmware does not run deflate decompression from small UI task stacks. Missing icons are fine; firmware falls back to built-in artwork for any icon not present in the selected pack. Background tiles are loaded from PSRAM only.
+The generated pack folder contains `manifest.json`, `checksums.json`, and generated `.gimg` files. Asset packs store raw `.gimg` payloads by default so firmware does not run deflate decompression from small UI task stacks. Missing icons are fine; firmware falls back to built-in artwork for any icon not present in the selected pack. Full-screen background images are loaded into PSRAM only; the smaller tiled background path works on internal-RAM devices at ≤32x32.
 
 ## Requirements
 

{ghostbt-0.2.0 → ghostbt-0.2.2}/README.md

@@ -105,17 +105,31 @@ When loading a `.gtheme`, firmware streams entries into `/mnt/ghostesp/themes/ac
 
 ### PSRAM vs internal RAM
 
-**PSRAM devices:** Up to 32 icons cached in PSRAM, tiled or scaled backgrounds supported. Background images smaller than the screen tile automatically; larger images scale to fill using LVGL zoom. A 128x128 background will scale up to fill any screen. Background images are always loaded into PSRAM.
+**PSRAM devices:** Up to 32 icons cached in PSRAM, tiled or scaled backgrounds supported. Background images smaller than the screen tile automatically; larger images scale to fill using LVGL zoom. A 128x128 background will scale up to fill any screen. Background images are always loaded into PSRAM. Any image format works; deflate-compressed payloads decode into PSRAM.
 
-**Internal-only devices:** 2 icons cached in internal RAM, no background images. Icons fall back to compiled-in artwork when cache is full. The pack still loads colors and icon mappings; only the image cache is limited.
+**Internal-only devices:** 2 icons cached in internal RAM. Background tile (≤32x32) supported — LVGL tiles the small image across the screen. Icon size capped at 32x32 RGB565A8; deflate-compressed payloads rejected. Use the `indexed_4bpp` format for icons and the background tile to fit in internal RAM: a 32x32 indexed icon is 576 bytes vs 3,072 bytes for RGB565A8 (~5x smaller). Icons fall back to compiled-in artwork when the cache is full. The pack still loads colors and icon mappings; only the image cache is limited.
+
+### Image formats
+
+| Format | Code | Size at 32x32 | Notes |
+|--------|------|---------------|-------|
+| `rgb565` | 1 | 2,048 B | No alpha. Best for opaque backgrounds. |
+| `rgb565a8` | 2 | 3,072 B | RGB565 + separate alpha plane. Default for icons. |
+| `indexed_4bpp` | 3 | 576 B | 16-color palette, packed 4-bit pixels. Ideal for internal-RAM devices; the `gbt` tool quantizes the source PNG at build time. |
+
+Set the pack-wide icon format with `icon_format` in the source manifest, or override per-background via the `format` field on each `background_sources` entry. Indexed payloads are always stored uncompressed.
 
 Convert one image directly:
 
 ```bash
+# Default — RGB565A8, 3 KB for 32x32
 gbt asset image ./wifi.png --out ./wifi_l.gimg --width 64 --height 64 --format rgb565a8
+
+# Internal-RAM friendly — indexed 4bpp, 576 B for 32x32
+gbt asset image ./wifi.png --out ./wifi_l.gimg --width 64 --height 64 --format indexed_4bpp
 ```
 
-The generated pack folder contains `manifest.json`, `checksums.json`, and generated `.gimg` files. Asset packs store raw `.gimg` payloads by default so firmware does not run deflate decompression from small UI task stacks. Missing icons are fine; firmware falls back to built-in artwork for any icon not present in the selected pack. Background tiles are loaded from PSRAM only.
+The generated pack folder contains `manifest.json`, `checksums.json`, and generated `.gimg` files. Asset packs store raw `.gimg` payloads by default so firmware does not run deflate decompression from small UI task stacks. Missing icons are fine; firmware falls back to built-in artwork for any icon not present in the selected pack. Full-screen background images are loaded into PSRAM only; the smaller tiled background path works on internal-RAM devices at ≤32x32.
 
 ## Requirements
 

ghostbt-0.2.2/ghostbt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

{ghostbt-0.2.0 → ghostbt-0.2.2}/ghostbt/asset.py

@@ -4,7 +4,7 @@ import shutil
 import struct
 import sys
 
-from .icon import png_to_rgb565, png_to_rgb565a8
+from .icon import png_to_indexed_4bpp, png_to_rgb565, png_to_rgb565a8
 from .utils import checksum_bytes, checksum_file, deflate_raw
 
 
@@ -13,15 +13,23 @@ IMAGE_VERSION = 1
 
 FORMAT_RGB565 = 1
 FORMAT_RGB565A8 = 2
+FORMAT_INDEXED_4BPP = 3
 FORMAT_BY_NAME = {
     "rgb565": FORMAT_RGB565,
     "rgb565a8": FORMAT_RGB565A8,
+    "indexed_4bpp": FORMAT_INDEXED_4BPP,
 }
 
 COMPRESSION_NONE = 0
 COMPRESSION_DEFLATE_RAW = 1
 
 DEFAULT_ICON_VARIANTS = (32, 64)
+DEFAULT_BACKGROUND_VARIANTS = {
+    "full": {"width": 240, "height": 320, "format": "rgb565", "output": "bg/bg_full.gimg"},
+    "half": {"width": 120, "height": 160, "format": "indexed_4bpp", "output": "bg/bg_half.gimg"},
+    "tiny": {"width": 80, "height": 107, "format": "indexed_4bpp", "output": "bg/bg_tiny.gimg"},
+    "tile": {"width": 32, "height": 32, "format": "indexed_4bpp", "output": "bg/bg_tile.gimg"},
+}
 VARIANT_LABELS = {
     32: "s",
     64: "l",
@@ -50,6 +58,8 @@ def _image_payload(src: pathlib.Path, width: int, height: int, fmt: str) -> byte
         return png_to_rgb565a8(src, width, height)
     if fmt == "rgb565":
         return png_to_rgb565(src, width, height)
+    if fmt == "indexed_4bpp":
+        return png_to_indexed_4bpp(src, width, height)
     raise ValueError(f"unsupported image format: {fmt}")
 
 
@@ -69,7 +79,9 @@ def write_asset_image(
     raw = _image_payload(src, width, height, fmt)
     payload = raw
     compression = COMPRESSION_NONE
-    if compress:
+    if compress and fmt != "indexed_4bpp":
+        # Indexed 4bpp is always stored uncompressed — the firmware rejects
+        # deflated indexed payloads, and 4-bit data doesn't deflate well.
         compressed = deflate_raw(raw)
         if len(compressed) < len(raw):
             payload = compressed
@@ -112,6 +124,28 @@ def _parse_variant_sizes(values) -> tuple[int, ...]:
     return sizes
 
 
+def _background_variant_specs(spec: dict) -> dict:
+    variants = spec.get("variants", DEFAULT_BACKGROUND_VARIANTS)
+    if variants is True:
+        variants = DEFAULT_BACKGROUND_VARIANTS
+    if not isinstance(variants, dict):
+        raise ValueError("background variants must be an object or true")
+
+    out = {}
+    for name, defaults in DEFAULT_BACKGROUND_VARIANTS.items():
+        value = variants.get(name)
+        if value is False or value is None:
+            continue
+        if value is True:
+            value = {}
+        if not isinstance(value, dict):
+            raise ValueError(f"background variant {name!r} must be an object, true, or false")
+        merged = dict(defaults)
+        merged.update(value)
+        out[name] = merged
+    return out
+
+
 def _copy_runtime_manifest(manifest: dict) -> dict:
     runtime = dict(manifest)
     for key in (
@@ -207,6 +241,24 @@ def make_asset_pack(
         if not src.is_file():
             print(f"warning: background source not found: {src}", file=sys.stderr)
             continue
+
+        if spec.get("variants") is not None or key == "background":
+            backgrounds = dict(runtime_manifest.get("backgrounds", {}))
+            for variant_name, variant in _background_variant_specs(spec).items():
+                rel_out = variant.get("output", f"bg/bg_{variant_name}.gimg")
+                write_asset_image(
+                    src,
+                    package_dir / rel_out,
+                    int(variant["width"]),
+                    int(variant["height"]),
+                    variant.get("format", "indexed_4bpp"),
+                    compress=compress,
+                )
+                backgrounds[variant_name] = rel_out
+            if backgrounds:
+                runtime_manifest["backgrounds"] = backgrounds
+            continue
+
         width = int(spec.get("width", 64 if key == "bg_tile" else 240))
         height = int(spec.get("height", 64 if key == "bg_tile" else 320))
         fmt = spec.get("format", "rgb565")

{ghostbt-0.2.0 → ghostbt-0.2.2}/ghostbt/cli.py

@@ -74,7 +74,7 @@ def main(argv=None) -> int:
     p_asset_image.add_argument("--out", required=True, help="Output .gimg path")
     p_asset_image.add_argument("--width", type=int, required=True, help="Output width in pixels")
     p_asset_image.add_argument("--height", type=int, required=True, help="Output height in pixels")
-    p_asset_image.add_argument("--format", choices=["rgb565", "rgb565a8"], default="rgb565a8",
+    p_asset_image.add_argument("--format", choices=["rgb565", "rgb565a8", "indexed_4bpp"], default="rgb565a8",
                                help="Pixel format (default: rgb565a8)")
     p_asset_image.add_argument("--no-compress", action="store_true", help="Store raw payload without deflate compression")
 

{ghostbt-0.2.0 → ghostbt-0.2.2}/ghostbt/icon.py

@@ -163,3 +163,71 @@ def png_to_rgb565(src: pathlib.Path, width: int, height: int) -> bytes:
         out[i * 2] = rgb565 & 0xFF
         out[i * 2 + 1] = (rgb565 >> 8) & 0xFF
     return bytes(out)
+
+
+def png_to_indexed_4bpp(src: pathlib.Path, width: int, height: int) -> bytes:
+    """Quantize an RGBA PNG to a 16-color palette and emit [palette][pixels].
+
+    Output layout (matches the firmware's GIMG_FORMAT_INDEXED_4BPP):
+      - 64 bytes: 16 x lv_color32_t palette in (B, G, R, A) memory order
+      - ceil(W*H/2) bytes: packed 4-bit indices, low nibble = even pixel
+    """
+    in_w, in_h, rgba = _read_png_rgba(src)
+    rgba = _resize_nearest(in_w, in_h, rgba, width, height)
+    pixel_count = width * height
+
+    # Coarse-quantize each pixel to a 4-4-4-1 key and tally occurrences.
+    # 4-4-4 RGB gives 4096 buckets; we keep the 16 most populated.
+    coarse_counts: dict[tuple[int, int, int, int], int] = {}
+    pixel_keys: list[tuple[int, int, int, int]] = [None] * pixel_count
+    for i in range(pixel_count):
+        r, g, b, a = rgba[i * 4:i * 4 + 4]
+        key = (r >> 4, g >> 4, b >> 4, 1 if a >= 128 else 0)
+        pixel_keys[i] = key
+        coarse_counts[key] = coarse_counts.get(key, 0) + 1
+
+    sorted_keys = sorted(coarse_counts.items(), key=lambda kv: -kv[1])
+    palette_keys = [k for k, _ in sorted_keys[:16]]
+    while len(palette_keys) < 16:
+        palette_keys.append((0, 0, 0, 1))
+
+    # Map each pixel to a palette slot. In-gamut pixels hit the dict; the
+    # remainder fall back to nearest-neighbour in 4-4-4-1 space.
+    key_to_pal = {k: i for i, k in enumerate(palette_keys)}
+    pixel_indices = bytearray(pixel_count)
+    for i, key in enumerate(pixel_keys):
+        idx = key_to_pal.get(key)
+        if idx is not None:
+            pixel_indices[i] = idx
+            continue
+        best = 0
+        best_d = 0x7FFFFFFF
+        for j, pk in enumerate(palette_keys):
+            d = (
+                (key[0] - pk[0]) ** 2
+                + (key[1] - pk[1]) ** 2
+                + (key[2] - pk[2]) ** 2
+                + (key[3] - pk[3]) ** 2
+            )
+            if d < best_d:
+                best_d = d
+                best = j
+        pixel_indices[i] = best
+
+    palette_bytes = bytearray()
+    for qr, qg, qb, qa in palette_keys:
+        r = (qr << 4) | 0x0F
+        g = (qg << 4) | 0x0F
+        b = (qb << 4) | 0x0F
+        a = 255 if qa else 0
+        palette_bytes.extend(struct.pack("<BBBB", b, g, r, a))
+
+    packed_count = (pixel_count + 1) // 2
+    pixel_bytes = bytearray(packed_count)
+    for i in range(pixel_count):
+        if i & 1:
+            pixel_bytes[i >> 1] |= pixel_indices[i] << 4
+        else:
+            pixel_bytes[i >> 1] |= pixel_indices[i]
+
+    return bytes(palette_bytes) + bytes(pixel_bytes)

{ghostbt-0.2.0 → ghostbt-0.2.2}/ghostbt.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ghostbt
-Version: 0.2.0
+Version: 0.2.2
 Summary: Ghost Build Tool - build and package GhostESP native SD apps
 License-Expression: GPL-3.0
 Project-URL: Homepage, https://github.com/GhostESP-Revival/GhostESP
@@ -131,17 +131,31 @@ When loading a `.gtheme`, firmware streams entries into `/mnt/ghostesp/themes/ac
 
 ### PSRAM vs internal RAM
 
-**PSRAM devices:** Up to 32 icons cached in PSRAM, tiled or scaled backgrounds supported. Background images smaller than the screen tile automatically; larger images scale to fill using LVGL zoom. A 128x128 background will scale up to fill any screen. Background images are always loaded into PSRAM.
+**PSRAM devices:** Up to 32 icons cached in PSRAM, tiled or scaled backgrounds supported. Background images smaller than the screen tile automatically; larger images scale to fill using LVGL zoom. A 128x128 background will scale up to fill any screen. Background images are always loaded into PSRAM. Any image format works; deflate-compressed payloads decode into PSRAM.
 
-**Internal-only devices:** 2 icons cached in internal RAM, no background images. Icons fall back to compiled-in artwork when cache is full. The pack still loads colors and icon mappings; only the image cache is limited.
+**Internal-only devices:** 2 icons cached in internal RAM. Background tile (≤32x32) supported — LVGL tiles the small image across the screen. Icon size capped at 32x32 RGB565A8; deflate-compressed payloads rejected. Use the `indexed_4bpp` format for icons and the background tile to fit in internal RAM: a 32x32 indexed icon is 576 bytes vs 3,072 bytes for RGB565A8 (~5x smaller). Icons fall back to compiled-in artwork when the cache is full. The pack still loads colors and icon mappings; only the image cache is limited.
+
+### Image formats
+
+| Format | Code | Size at 32x32 | Notes |
+|--------|------|---------------|-------|
+| `rgb565` | 1 | 2,048 B | No alpha. Best for opaque backgrounds. |
+| `rgb565a8` | 2 | 3,072 B | RGB565 + separate alpha plane. Default for icons. |
+| `indexed_4bpp` | 3 | 576 B | 16-color palette, packed 4-bit pixels. Ideal for internal-RAM devices; the `gbt` tool quantizes the source PNG at build time. |
+
+Set the pack-wide icon format with `icon_format` in the source manifest, or override per-background via the `format` field on each `background_sources` entry. Indexed payloads are always stored uncompressed.
 
 Convert one image directly:
 
 ```bash
+# Default — RGB565A8, 3 KB for 32x32
 gbt asset image ./wifi.png --out ./wifi_l.gimg --width 64 --height 64 --format rgb565a8
+
+# Internal-RAM friendly — indexed 4bpp, 576 B for 32x32
+gbt asset image ./wifi.png --out ./wifi_l.gimg --width 64 --height 64 --format indexed_4bpp
 ```
 
-The generated pack folder contains `manifest.json`, `checksums.json`, and generated `.gimg` files. Asset packs store raw `.gimg` payloads by default so firmware does not run deflate decompression from small UI task stacks. Missing icons are fine; firmware falls back to built-in artwork for any icon not present in the selected pack. Background tiles are loaded from PSRAM only.
+The generated pack folder contains `manifest.json`, `checksums.json`, and generated `.gimg` files. Asset packs store raw `.gimg` payloads by default so firmware does not run deflate decompression from small UI task stacks. Missing icons are fine; firmware falls back to built-in artwork for any icon not present in the selected pack. Full-screen background images are loaded into PSRAM only; the smaller tiled background path works on internal-RAM devices at ≤32x32.
 
 ## Requirements
 

{ghostbt-0.2.0 → ghostbt-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ghostbt"
-version = "0.2.0"
+version = "0.2.2"
 description = "Ghost Build Tool - build and package GhostESP native SD apps"
 readme = "README.md"
 requires-python = ">=3.8"

ghostbt-0.2.0/ghostbt/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"