scrollkit 0.8.3__py3-none-any.whl

scrollkit/simulator/bitmaptools.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Desktop emulation of CircuitPython's ``bitmaptools`` C module.
+
+ScrollKit's span/rect painters, overlay-mask, and bitmap-text all express bounded
+work through ``bitmaptools.fill_region`` / ``bitmaptools.blit`` so the SAME code
+runs on the device (where ``bitmaptools`` is a built-in) and on the desktop
+simulator (where this shim provides it). The display resolves which module to use
+via ``display.gfx``.
+
+Semantics mirror the device for the subset ScrollKit uses:
+- ``fill_region`` fills the HALF-OPEN rectangle ``[x1, x2) x [y1, y2)`` clipped to
+  the bitmap; an empty/inverted region is a no-op.
+- ``blit`` copies a source sub-rectangle into the destination at ``(x, y)`` with
+  ``skip_index`` transparency, clipped at all four edges (incl. negative offsets).
+
+Desktop-only — never imported on CircuitPython (the device uses the real module).
+A golden corpus captured on a real board pins this shim's fidelity
+(``test/unit/display/test_bitmaptools_shim.py``); if it ever diverges, fix the
+shim, never the shared effect logic.
+"""
+
+
+def fill_region(bitmap, x1, y1, x2, y2, value):
+    """Fill the half-open rectangle ``[x1, x2) x [y1, y2)`` with ``value``.
+
+    Clipped to the bitmap. Matching CircuitPython, an inverted or empty region
+    (``x1 >= x2`` or ``y1 >= y2``) is a no-op — the bounds are NOT reordered, so
+    the simulator and device agree.
+    """
+    if x1 >= x2 or y1 >= y2:
+        return
+    w = bitmap.width
+    h = bitmap.height
+    xa = x1 if x1 > 0 else 0
+    ya = y1 if y1 > 0 else 0
+    xb = x2 if x2 < w else w
+    yb = y2 if y2 < h else h
+    if xb <= xa or yb <= ya:
+        return
+    bitmap._buffer[ya:yb, xa:xb] = value
+
+
+def blit(dest, source, x, y, *, x1=0, y1=0, x2=None, y2=None, skip_index=None):
+    """Copy ``source`` (sub-rect ``[x1,x2) x [y1,y2)``) into ``dest`` at ``(x, y)``.
+
+    Honors ``skip_index`` transparency and clips at every edge, including negative
+    destination offsets. Delegates to the simulator ``Bitmap.blit``, which already
+    implements the CircuitPython clipping/transparency rules.
+    """
+    dest.blit(x, y, source, x1=x1, y1=y1, x2=x2, y2=y2, skip_index=skip_index)

scrollkit/simulator/core/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Core simulator components."""
+
+from .led_matrix import LEDMatrix
+from .pixel_buffer import PixelBuffer
+from .color_utils import *
+
+__all__ = ['LEDMatrix', 'PixelBuffer']

scrollkit/simulator/core/color_utils.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Color manipulation utilities for LED simulation."""
+
+def rgb565_to_rgb888(color565):
+    """Convert RGB565 color to RGB888 (standard 24-bit RGB).
+    
+    Args:
+        color565: 16-bit color value in RGB565 format
+        
+    Returns:
+        Tuple of (r, g, b) values in 0-255 range
+    """
+    r = ((color565 >> 11) & 0x1F) << 3
+    g = ((color565 >> 5) & 0x3F) << 2
+    b = (color565 & 0x1F) << 3
+    
+    # Add the MSB bits to the LSB for better color accuracy
+    r |= r >> 5
+    g |= g >> 6
+    b |= b >> 5
+    
+    return (r, g, b)
+
+
+def rgb888_to_rgb565(r, g, b):
+    """Convert RGB888 color to RGB565.
+    
+    Args:
+        r: Red component (0-255)
+        g: Green component (0-255)
+        b: Blue component (0-255)
+        
+    Returns:
+        16-bit color value in RGB565 format
+    """
+    return ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
+
+
+def apply_brightness(color, brightness):
+    """Apply brightness adjustment to RGB color.
+    
+    Args:
+        color: Tuple of (r, g, b) values
+        brightness: Float from 0.0 to 1.0
+        
+    Returns:
+        Tuple of brightness-adjusted (r, g, b) values
+    """
+    return tuple(int(c * brightness) for c in color)
+
+
+# Common color constants matching CircuitPython
+BLACK = 0x0000
+WHITE = 0xFFFF
+RED = 0xF800
+GREEN = 0x07E0
+BLUE = 0x001F
+CYAN = 0x07FF
+MAGENTA = 0xF81F
+YELLOW = 0xFFE0
+ORANGE = 0xFD20
+PURPLE = 0x8010

scrollkit/simulator/core/device_benchmarks.json

@@ -0,0 +1,254 @@
+{
+  "board": "adafruit_matrixportal_s3",
+  "cp": "9.1.0",
+  "benchmarks": [
+    {
+      "name": "noop_loop_iter",
+      "category": "compute",
+      "value": 2018.74,
+      "note": "for-loop overhead (subtracted below)",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "int_add",
+      "category": "compute",
+      "value": 1538.09,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "int_mul",
+      "category": "compute",
+      "value": 1684.57,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "float_add",
+      "category": "compute",
+      "value": 2069.09,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "float_mul",
+      "category": "compute",
+      "value": 2066.04,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "list_index",
+      "category": "compute",
+      "value": 2917.48,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "dict_get",
+      "category": "compute",
+      "value": 2337.65,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "func_call",
+      "category": "compute",
+      "value": 4661.56,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "attr_access",
+      "category": "compute",
+      "value": 2259.83,
+      "note": "",
+      "iters": 20000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "bitmap_setpixel",
+      "category": "pixel_interpreted",
+      "value": 6996.15,
+      "note": "bmp[x,y]=1",
+      "iters": 10000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "bitmap_getpixel",
+      "category": "pixel_interpreted",
+      "value": 6690.98,
+      "note": "",
+      "iters": 10000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "bitmap_fill_64x32",
+      "category": "bulk_c",
+      "value": 8926.39,
+      "note": "C fill 2048 px",
+      "iters": 4000,
+      "unit": "ns/call"
+    },
+    {
+      "name": "bitmaptools_blit_16x16",
+      "category": "bulk_c",
+      "value": 159462.0,
+      "note": "C blit 256 px",
+      "iters": 4000,
+      "unit": "ns/call"
+    },
+    {
+      "name": "bitmaptools_fill_region",
+      "category": "bulk_c",
+      "value": 147049.0,
+      "note": "512 px",
+      "iters": 4000,
+      "unit": "ns/call"
+    },
+    {
+      "name": "bitmaptools_draw_line",
+      "category": "bulk_c",
+      "value": 29617.3,
+      "note": "",
+      "iters": 4000,
+      "unit": "ns/call"
+    },
+    {
+      "name": "palette_set",
+      "category": "display_obj",
+      "value": 2629.09,
+      "note": "",
+      "iters": 10000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "tilegrid_create",
+      "category": "display_obj",
+      "value": 47607.4,
+      "note": "alloc+init",
+      "iters": 500,
+      "unit": "ns/call"
+    },
+    {
+      "name": "tilegrid_move_x",
+      "category": "display_obj",
+      "value": 2491.76,
+      "note": "",
+      "iters": 10000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "group_append_pop_pair",
+      "category": "display_obj",
+      "value": 10721.8,
+      "note": "",
+      "iters": 3000,
+      "unit": "ns/pair"
+    },
+    {
+      "name": "bitmap_alloc_32x16",
+      "category": "memory",
+      "value": 123291.0,
+      "note": "",
+      "iters": 1000,
+      "unit": "ns/alloc"
+    },
+    {
+      "name": "bytearray_alloc_256",
+      "category": "memory",
+      "value": 73989.8,
+      "note": "",
+      "iters": 2000,
+      "unit": "ns/alloc"
+    },
+    {
+      "name": "gc_collect",
+      "category": "memory",
+      "value": 899251.0,
+      "note": "clean heap",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "monotonic_ns_call",
+      "category": "io",
+      "value": 8848.57,
+      "note": "",
+      "iters": 10000,
+      "unit": "ns/op"
+    },
+    {
+      "name": "refresh_empty_bd1",
+      "category": "refresh",
+      "value": 14241.3,
+      "note": "bit_depth=1, empty group",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "refresh_full_bd1",
+      "category": "refresh",
+      "value": 4312130.0,
+      "note": "bit_depth=1, 64x32 recomposite",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "refresh_empty_bd2",
+      "category": "refresh",
+      "value": 15259.0,
+      "note": "bit_depth=2, empty group",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "refresh_full_bd2",
+      "category": "refresh",
+      "value": 4372150.0,
+      "note": "bit_depth=2, 64x32 recomposite",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "refresh_empty_bd4",
+      "category": "refresh",
+      "value": 17293.1,
+      "note": "bit_depth=4, empty group",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "refresh_full_bd4",
+      "category": "refresh",
+      "value": 4492190.0,
+      "note": "bit_depth=4, 64x32 recomposite",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "refresh_empty_bd6",
+      "category": "refresh",
+      "value": 14241.3,
+      "note": "bit_depth=6, empty group",
+      "iters": 30,
+      "unit": "ns/call"
+    },
+    {
+      "name": "refresh_full_bd6",
+      "category": "refresh",
+      "value": 13691200.0,
+      "note": "bit_depth=6, 64x32 recomposite",
+      "iters": 30,
+      "unit": "ns/call"
+    }
+  ]
+}

scrollkit/simulator/core/feasibility.py

@@ -0,0 +1,160 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Turn accumulated modeled frame costs into a human/AI-readable feasibility report.
+
+Answers: "would this app actually run on the real hardware?" — estimated hardware
+FPS, where the per-frame time goes, estimated peak RAM vs budget, and actionable
+warnings. Always labels itself as an estimate when the profile is uncalibrated.
+
+Desktop/simulator only.
+"""
+
+import math
+
+
+def _one_sig_fig(x):
+    """Round to one significant figure (so '~5 FPS', not '5.37 FPS')."""
+    if x <= 0:
+        return 0
+    d = math.floor(math.log10(x))
+    factor = 10 ** d
+    return round(x / factor) * factor
+
+
+def _median(values):
+    s = sorted(values)
+    n = len(s)
+    if n == 0:
+        return 0.0
+    mid = n // 2
+    return s[mid] if n % 2 else (s[mid - 1] + s[mid]) / 2.0
+
+
+class FeasibilityReport:
+    """Estimated hardware performance for a run, built from a PerformanceManager."""
+
+    def __init__(self, profile_name, confidence, source, calibrated,
+                 est_hw_fps, median_frame_ms, worst_frame_ms, breakdown_ms,
+                 est_peak_ram_bytes, ram_budget_bytes, warnings):
+        self.profile_name = profile_name
+        self.confidence = confidence
+        self.source = source
+        self.calibrated = calibrated
+        self.est_hw_fps = est_hw_fps          # None if no frames were rendered
+        self.median_frame_ms = median_frame_ms
+        self.worst_frame_ms = worst_frame_ms
+        self.breakdown_ms = breakdown_ms      # {category: ms} averaged per frame
+        self.est_peak_ram_bytes = est_peak_ram_bytes
+        self.ram_budget_bytes = ram_budget_bytes
+        self.warnings = warnings
+
+    # ------------------------------------------------------------------
+    @classmethod
+    def from_manager(cls, manager):
+        profile = manager.profile
+        frames = manager.frames
+        n = len(frames)
+
+        if n == 0:
+            return cls(profile.name, profile.confidence, profile.source,
+                       profile.is_calibrated, None, 0.0, 0.0, {},
+                       manager.estimated_peak_ram_bytes(), profile.usable_ram_bytes,
+                       ["No frames rendered yet — run the app (and call show()) first."])
+
+        totals_us = [f.total_us for f in frames]
+        median_us = _median(totals_us)
+        worst_us = max(totals_us)
+        est_fps = (1_000_000.0 / median_us) if median_us > 0 else None
+
+        # Average per-category breakdown (ms), and which category dominates.
+        cats = ("bitmap_rebuild_us", "refresh_us", "pixel_writes_us", "gc_us",
+                "bulk_ops_us")
+        breakdown_ms = {}
+        for cat in cats:
+            avg_us = sum(getattr(f, cat) for f in frames) / n
+            breakdown_ms[cat.replace("_us", "")] = avg_us / 1000.0
+        dominant = max(breakdown_ms, key=lambda k: breakdown_ms[k])
+
+        peak_ram = manager.estimated_peak_ram_bytes()
+        budget = profile.usable_ram_bytes
+
+        warnings = []
+        if est_fps is not None and est_fps < 1:
+            warnings.append(
+                "Frame would take ~%d ms on hardware (~%s FPS) — effectively frozen."
+                % (round(median_us / 1000.0), _fps_text(est_fps, profile.is_calibrated)))
+        elif est_fps is not None and est_fps < 10:
+            warnings.append(
+                "Frame would take ~%d ms on hardware (~%s FPS%s). Scrolling will stutter."
+                % (round(median_us / 1000.0), _fps_text(est_fps, profile.is_calibrated),
+                   "" if profile.is_calibrated else ", ESTIMATE"))
+        if dominant == "bitmap_rebuild" and breakdown_ms["bitmap_rebuild"] > 0 \
+                and breakdown_ms["bitmap_rebuild"] >= 0.5 * (median_us / 1000.0):
+            warnings.append(
+                "draw_text rebuilds a glyph bitmap every frame (the dominant cost on "
+                "hardware). Cache the Label/content and only change .text when it "
+                "actually changes, instead of redrawing every frame.")
+        if peak_ram > budget:
+            warnings.append(
+                "Estimated peak RAM ~%d KB exceeds the modeled device budget of %d KB "
+                "— won't fit. Reduce content/effects or disable the web server."
+                % (peak_ram // 1024, budget // 1024))
+        elif peak_ram > 0.8 * budget:
+            warnings.append(
+                "Estimated peak RAM ~%d KB is close to the %d KB budget — little "
+                "headroom on hardware." % (peak_ram // 1024, budget // 1024))
+
+        return cls(profile.name, profile.confidence, profile.source,
+                   profile.is_calibrated, est_fps, median_us / 1000.0,
+                   worst_us / 1000.0, breakdown_ms, peak_ram, budget, warnings)
+
+    # ------------------------------------------------------------------
+    def as_dict(self):
+        return {
+            "profile": self.profile_name,
+            "confidence": self.confidence,
+            "calibrated": self.calibrated,
+            "source": self.source,
+            "estimated_hardware_fps": self.est_hw_fps,
+            "median_frame_ms": round(self.median_frame_ms, 2),
+            "worst_frame_ms": round(self.worst_frame_ms, 2),
+            "breakdown_ms": {k: round(v, 2) for k, v in self.breakdown_ms.items()},
+            "estimated_peak_ram_bytes": self.est_peak_ram_bytes,
+            "ram_budget_bytes": self.ram_budget_bytes,
+            "warnings": list(self.warnings),
+        }
+
+    def as_text(self):
+        lines = ["=== Hardware feasibility: %s ===" % self.profile_name]
+        if self.calibrated:
+            lines.append("  Confidence: MEASURED on device (%s)" % self.source)
+        else:
+            lines.append("  Confidence: ROUGH ESTIMATE, not measured on device (%s)"
+                         % self.source)
+        if self.est_hw_fps is None:
+            lines.append("  Estimated hardware FPS: n/a (no frames rendered)")
+        else:
+            lines.append("  Estimated hardware FPS: ~%s   (median frame ~%d ms, worst ~%d ms)"
+                         % (_fps_text(self.est_hw_fps, self.calibrated),
+                            round(self.median_frame_ms), round(self.worst_frame_ms)))
+        if self.breakdown_ms:
+            parts = sorted(self.breakdown_ms.items(), key=lambda kv: -kv[1])
+            lines.append("  Per-frame cost (avg): "
+                         + " | ".join("%s %.1f ms" % (k, v) for k, v in parts))
+        lines.append("  Estimated peak RAM: %d KB / %d KB budget"
+                     % (self.est_peak_ram_bytes // 1024, self.ram_budget_bytes // 1024))
+        if self.warnings:
+            lines.append("  Warnings:")
+            for w in self.warnings:
+                lines.append("    - " + w)
+        else:
+            lines.append("  No feasibility warnings.")
+        return "\n".join(lines)
+
+
+def _fps_text(fps, calibrated):
+    if fps is None:
+        return "n/a"
+    if calibrated:
+        return "%.1f" % fps
+    sig = _one_sig_fig(fps)
+    return ("%g" % sig)