ocdkit 0.0.4__tar.gz → 0.0.5__tar.gz

{ocdkit-0.0.4 → ocdkit-0.0.5}/.gitignore

@@ -6,6 +6,17 @@
 # Local tooling
 .claude/
 
+# Local machine-specific config for bench / coverage scripts
+scripts/coverage_cross_device.env
+scripts/bench_paths.env
+
+# Generated artifacts from bench / demo scripts
+scripts/bench_*.png
+scripts/check_*.png
+scripts/check_*.svg
+scripts/check_*.html
+figures/
+
 # Editor / NAS junk
 *.bak
 .!*

{ocdkit-0.0.4/src/ocdkit.egg-info → ocdkit-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ocdkit
-Version: 0.0.4
+Version: 0.0.5
 Summary: Obsessive Coder's Dependency Toolkit — Python utilities for array manipulation, GPU dispatch, image I/O, morphology, and plotting.
 License: BSD-3-Clause
 Requires-Python: >=3.11
@@ -11,6 +11,7 @@ Requires-Dist: scipy
 Requires-Dist: scikit-image>=0.26
 Requires-Dist: tifffile
 Requires-Dist: imagecodecs
+Requires-Dist: opencodecs>=0.1.12
 Requires-Dist: matplotlib
 Requires-Dist: fastremap
 Requires-Dist: edt
@@ -24,6 +25,7 @@ Requires-Dist: cmap
 Requires-Dist: tqdm
 Requires-Dist: platformdirs
 Requires-Dist: cryptography
+Requires-Dist: lxml
 Provides-Extra: viewer
 Requires-Dist: fastapi; extra == "viewer"
 Requires-Dist: uvicorn[standard]; extra == "viewer"

{ocdkit-0.0.4 → ocdkit-0.0.5}/badges/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 43.71%"><title>coverage: 43.71%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#e05d44"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">43.71%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">43.71%</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 44.55%"><title>coverage: 44.55%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#e05d44"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">44.55%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">44.55%</text></g></svg>

{ocdkit-0.0.4 → ocdkit-0.0.5}/badges/tests.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="68" height="20" role="img" aria-label="tests: 400"><title>tests: 400</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="68" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="37" height="20" fill="#555"/><rect x="37" width="31" height="20" fill="#4c1"/><rect width="68" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="195" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">tests</text><text x="195" y="140" transform="scale(.1)" fill="#fff" textLength="270">tests</text><text aria-hidden="true" x="515" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">400</text><text x="515" y="140" transform="scale(.1)" fill="#fff" textLength="210">400</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="68" height="20" role="img" aria-label="tests: 408"><title>tests: 408</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="68" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="37" height="20" fill="#555"/><rect x="37" width="31" height="20" fill="#4c1"/><rect width="68" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="195" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">tests</text><text x="195" y="140" transform="scale(.1)" fill="#fff" textLength="270">tests</text><text aria-hidden="true" x="515" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">408</text><text x="515" y="140" transform="scale(.1)" fill="#fff" textLength="210">408</text></g></svg>

{ocdkit-0.0.4 → ocdkit-0.0.5}/docs/plot-backend-roadmap.md

@@ -1,18 +1,17 @@
 # Plot backend roadmap
 
 **Status:** Design discussion / pending decision.
-**Owner:** kevin@kanvasbio.com
-**Driver:** matplotlib accounts for ~80% of warm-call time in `hiprpy.plot.plot_spectra` (~115 ms of ~140 ms) and ~1.5 s of cold-import overhead. We also want native hover/tooltip behavior like the classification-debugger GUI, which matplotlib can't deliver inline.
+**Driver:** matplotlib accounts for ~80% of warm-call time in a typical spectra-plotting call (~115 ms of ~140 ms) and ~1.5 s of cold-import overhead. We also want native hover/tooltip behavior like the classification-debugger GUI, which matplotlib can't deliver inline.
 
 ## Context
 
-`ocdkit.plot` and `hiprpy.plot` already own ~10 K LOC of plotting code:
+`ocdkit.plot` and a downstream plot package together own ~10 K LOC of plotting code:
 
 | Package | LOC |
 |---|---|
 | `ocdkit.plot` (figure, grid, label, color, defaults, display, contour, export) | 1,935 |
-| `hiprpy.plot` non-WGPU (datashade, cell, text, barcode, line, background, …) | 4,641 |
-| `hiprpy.plot.wgpu` (lines, scatter, aggregators — already custom GPU primitives) | 4,783 |
+| Downstream non-WGPU plot code (datashade, cell, text, barcode, line, background, …) | 4,641 |
+| Downstream WGPU plot code (lines, scatter, aggregators — already custom GPU primitives) | 4,783 |
 
 What we still depend on matplotlib for is narrow: 2D Cartesian axes, ticks, labels, legends, image display, save-to-PNG/PDF/SVG, inline-in-Jupyter. **Not** 3D, animation, multi-backend abstraction (Qt/GTK/MacOSX), most chart types, complex tick locators/formatters, or any of the other ~180 K LOC of matplotlib's surface.
 
@@ -29,7 +28,7 @@ Shallow-cloned each candidate, counted Python LOC excluding tests, sphinx, sampl
 | plotly | 66 MB | 13 K relevant (+ ~600 K autogen) | JS bundle as data | Most LOC is auto-generated trait validators |
 | datoviz | 137 MB | 8 K Py wrapper | 140 K C++ Vulkan engine | Heaviest binary footprint, fastest renderer |
 | vispy | 11 MB | 32 K | None — pure Py + OpenGL | OpenGL stack, not WGPU |
-| pygfx | 84 MB | 20 K | None — uses `wgpu-py` | Same backend ocdkit/hiprpy already use |
+| pygfx | 84 MB | 20 K | None — uses `wgpu-py` | Same backend ocdkit already uses |
 
 ## Tradeoff summary
 
@@ -63,20 +62,20 @@ If pygfx covers ≥80% of our needs at ≥80% of the visual quality, **adopt pyg
 
 ### Step 2 (only if pygfx is insufficient): roll our own
 
-Estimated scope, building on existing `hiprpy.plot.wgpu.lines`:
+Estimated scope, building on the existing WGPU line rasterizer:
 
 | Module | LOC est. | Notes |
 |---|---|---|
 | `ocdkit.plot.figure_v2` | 400 | New `Figure` class owning the wgpu canvas + axes layout; coexists with current matplotlib `figure()` so migration is piecewise |
 | `ocdkit.plot.axis` | 800 | `LinearAxis`, `LogAxis` — tick locator + formatter + render-time placement. The matplotlib equivalent is ~3 K LOC; we don't need most of it |
-| `hiprpy.plot.wgpu.text` | 600 | FreeType-rendered glyph atlas + WGSL textured-quad shader. The one piece of genuinely new rasterization work |
+| `ocdkit.plot.wgpu.text` | 600 | FreeType-rendered glyph atlas + WGSL textured-quad shader. The one piece of genuinely new rasterization work |
 | `ocdkit.plot.legend` | 200 | Boxed layout: text + marker swatches |
 | `ocdkit.plot.hover` | 300 | Mouse → data-coord lookup → DOM/Jupyter tooltip overlay. Generalize the classification-debugger pattern |
 | `ocdkit.plot.export` | 400 | PNG (numpy→PIL), SVG (string templates), maybe PDF (skip if PIL→PNG covers science exports) |
 | Migration: rewrite `plot_spectra`, `plot_image_grid`, `key_slice_grid`, `label_axes` against new primitives | ~600 | Mostly drop-in replacements at the call sites |
 | **Total** | **~3.3 K** | New code, all in our control |
 
-Plus: deletion of matplotlib-specific code paths in `hiprpy.plot` (~1 K LOC saved) and removal of matplotlib runtime dep.
+Plus: deletion of matplotlib-specific code paths in the downstream plot package (~1 K LOC saved) and removal of matplotlib runtime dep.
 
 ### Why not pygfx + own axes?
 
@@ -91,6 +90,6 @@ A hybrid path is also viable: use pygfx for the rasterization layer (lines/text/
 
 ## Concrete next action
 
-Spike `plot_spectra_pygfx` using `scope.mixed_spectra[-1]` from `notebooks/hiprpy_demo_notebook.ipynb` as the test case. Compare visual output side-by-side with `plot_spectra_wgpu` and `plot_spectra_cpu`. Decide pygfx-vs-roll-own from that single comparison.
+Spike `plot_spectra_pygfx` against a representative spectra notebook (e.g. `scope.mixed_spectra[-1]` from any existing demo). Compare visual output side-by-side with `plot_spectra_wgpu` and `plot_spectra_cpu`. Decide pygfx-vs-roll-own from that single comparison.
 
 If the answer ends up being "pygfx + own axis layer", the new module structure would live in `ocdkit.plot.gfx_*` (parallel to the current matplotlib-based modules) so the migration is a per-call-site flip rather than a big-bang rewrite.

{ocdkit-0.0.4 → ocdkit-0.0.5}/pyproject.toml

@@ -19,6 +19,10 @@ dependencies = [
     "scikit-image>=0.26",
     "tifffile",
     "imagecodecs",
+    # opencodecs.uhdr.read_thumbnail_bytes (≥0.1.12) is the fast path
+    # in resolve_uhdr_thumb_bytes; ≥0.1.10 has the _fast_log2 fix
+    # required for correct gain-map encoding via encode_native.
+    "opencodecs>=0.1.12",
     "matplotlib",
     "fastremap",
     "edt",
@@ -32,6 +36,7 @@ dependencies = [
     "tqdm",
     "platformdirs",
     "cryptography",
+    "lxml",
 ]
 
 [project.optional-dependencies]
@@ -82,11 +87,7 @@ testpaths = ["tests"]
 source = ["ocdkit"]
 
 [tool.coverage.paths]
-source = [
-    "src/ocdkit",
-    "/Volumes/DataDrive/ocdkit/src/ocdkit",
-    "/home/kcutler/DataDrive/ocdkit/src/ocdkit",
-]
+source = ["src/ocdkit"]
 
 [tool.coverage.report]
 show_missing = true

{ocdkit-0.0.4 → ocdkit-0.0.5}/scripts/bench_contour_alignment.py

@@ -24,8 +24,7 @@ import numpy as np
 sys.path.insert(0, str(Path(__file__).parent))
 
 from bench_vector_contours import vector_contours_fast
-from bench_vector_contours_tier2 import vector_contours_marching
-from ocdkit.plot.contour import vector_contours
+from ocdkit.plot.contour import vector_contours, vector_contours_marching
 
 
 def make_mask():
@@ -73,7 +72,7 @@ def main():
                              color='red', linewidth=1.5)
 
     fig.tight_layout()
-    out = Path('/Volumes/DataDrive/ocdkit/scripts/bench_contour_alignment.png')
+    out = Path(__file__).resolve().parent / 'bench_contour_alignment.png'
     fig.savefig(out, dpi=150, bbox_inches='tight')
     print(f"saved: {out}")
 

ocdkit-0.0.5/scripts/bench_hdr_cmap.py

@@ -0,0 +1,181 @@
+"""Demo: HDR-lifted colormaps through the css-img / SVG image_grid pipe.
+
+Renders a grayscale gradient with viridis / magma / inferno / rdbu in:
+  - SDR (uint8 P3, current default behavior)
+  - HDR (float linear-P3 with values > 1.0, peak ≈ 1600 nits)
+
+Saves figures/hdr_cmap_demo.svg — open in Safari to see HDR on an EDR
+display (Chrome on macOS works too). Also prints the lifted LUTs'
+out-of-SDR-range fractions so you can confirm the lift actually used
+the headroom.
+"""
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+
+import matplotlib.pyplot as plt
+plt.rcParams.update({
+    'figure.facecolor': 'none',
+    'axes.facecolor':  'none',
+    'savefig.facecolor': 'none',
+    'axes.edgecolor':  'gray',
+    'axes.labelcolor': 'gray',
+    'xtick.color':     'gray',
+    'ytick.color':     'gray',
+    'text.color':      'gray',
+    'axes.titlecolor': 'gray',
+})
+
+REPO = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO / 'src'))
+
+from ocdkit.plot.hdr_cmap import (  # noqa: E402
+    make_hdr_cmap_lut, apply_hdr_cmap,
+    SDR_WHITE_NITS, HDR_PEAK_NITS_DEFAULT,
+)
+from ocdkit.plot import imshow  # noqa: E402
+
+# linear Display-P3 → Y (relative luminance)
+P3_Y_WEIGHTS = np.array([0.2289745641, 0.6917385218, 0.0792869141])
+
+
+def lut_stats(name):
+    sdr = make_hdr_cmap_lut(name, hdr_jz=0.155,
+                             hdr_peak_nits=SDR_WHITE_NITS)  # SDR baseline
+    hdr = make_hdr_cmap_lut(name, hdr_peak_nits=HDR_PEAK_NITS_DEFAULT)
+    # both LUTs are linear-P3 normalized so 1.0 ≡ their respective peak.
+    # Convert to absolute nits via Y-weighted sum × peak-nits.
+    peak_sdr_nits = float((sdr @ P3_Y_WEIGHTS).max() * SDR_WHITE_NITS)
+    peak_hdr_nits = float((hdr @ P3_Y_WEIGHTS).max() * HDR_PEAK_NITS_DEFAULT)
+    print(
+        f"  {name:12s}  "
+        f"SDR peak Y={peak_sdr_nits:6.1f} nits   "
+        f"HDR peak Y={peak_hdr_nits:6.1f} nits   "
+        f"lift {peak_hdr_nits / max(peak_sdr_nits, 1e-3):4.2f}x"
+    )
+
+
+def main():
+    print("Lift stats (peak_mult=7.88 ≈ 1600 nits):")
+    for name in ('viridis', 'magma', 'inferno', 'plasma',
+                 'cividis', 'RdBu', 'twilight'):
+        lut_stats(name)
+
+    H, W = 64, 1024
+    grad = np.tile(np.linspace(0, 1, W, dtype=np.float32), (H, 1))
+
+    figures_dir = REPO / 'figures'
+    figures_dir.mkdir(exist_ok=True)
+
+    print("\nFull pipeline (HDR + SDR side by side):")
+    cmaps = ['viridis', 'magma', 'inferno', 'plasma', 'cividis']
+    for name in cmaps:
+        t0 = time.perf_counter()
+        rgb_hdr = apply_hdr_cmap(grad, name)
+        dt = (time.perf_counter() - t0) * 1000
+        peak_nits = float((rgb_hdr @ P3_Y_WEIGHTS).max() * HDR_PEAK_NITS_DEFAULT)
+        print(f"  apply_hdr_cmap({name})   {dt:6.1f} ms   "
+              f"linear-P3 max={float(rgb_hdr.max()):.3f}  "
+              f"peak Y={peak_nits:6.1f} nits  dtype={rgb_hdr.dtype}")
+
+    # Two routes through the new `cmap=` kwarg on imshow:
+    out_hdr = figures_dir / 'hdr_cmap_demo_hdr.svg'
+    out_sdr = figures_dir / 'hdr_cmap_demo_sdr.svg'
+
+    # HDR route: pre-applied float linear-P3 tiles. (imshow's per-call
+    # cmap kwarg applies one cmap to all 2D items, so to show per-cmap
+    # tiles in a single grid we apply manually here.)
+    hdr_tiles = [apply_hdr_cmap(grad, c) for c in cmaps]
+    fig_hdr = imshow(hdr_tiles, figsize=2, titles=cmaps)
+    out_hdr.write_text(fig_hdr._inner.to_string())
+    print(f"\nSaved HDR demo:  {out_hdr}")
+
+    # SDR baseline through the same `cmap=` kwarg, using hdr=False.
+    from cmap import Colormap
+    sdr_tiles = []
+    for c in cmaps:
+        cm = Colormap(c)
+        rgba = np.asarray(cm(grad))
+        sdr_tiles.append((rgba[..., :3] * 255).astype(np.uint8))
+    fig_sdr = imshow(sdr_tiles, figsize=2, titles=cmaps)
+    out_sdr.write_text(fig_sdr._inner.to_string())
+    print(f"Saved SDR demo:  {out_sdr}")
+
+    # And one figure exercising the new imshow(cmap=, hdr=True) wiring
+    # directly on a single 2D array.
+    out_kw = figures_dir / 'hdr_cmap_demo_kwarg.svg'
+    fig_kw = imshow(grad, cmap='viridis', hdr=True, figsize=4,
+                    titles='imshow(grad, cmap="viridis", hdr=True)')
+    out_kw.write_text(fig_kw._inner.to_string())
+    print(f"Saved kwarg demo: {out_kw}")
+
+    # ─────────────────────────────────────────────────────────────────
+    # SDR-fallback A/B test
+    # ─────────────────────────────────────────────────────────────────
+    # LEFT tile  : jxl-p3, uint8 sRGB-curve viridis (native SDR cmap).
+    # RIGHT tile : Ultra-HDR JPEG (apply_hdr_cmap → linear-P3 float →
+    #              libuhdr base + gain map). The SDR base layer of the
+    #              UHDR JPEG is the *native non-lifted cmap* (via
+    #              HdrCmapArray._sdr_base_p3_u8), not libuhdr's
+    #              auto-tone-map — which used to desaturate bright
+    #              stops (the original reason for switching off PQ-JXL).
+    #
+    # Expected on HDR display: RIGHT tile glows (~600 nits peak).
+    # Expected on SDR display (or HDR display toggled off): LEFT and
+    # RIGHT should look pixel-identical — both are the same SDR cmap.
+    bumps = np.tile(np.linspace(0, 1, 1024, dtype=np.float32), (192, 1))
+    out_sdr_only = figures_dir / 'hdr_cmap_compare_sdr.svg'
+    out_hdr_only = figures_dir / 'hdr_cmap_compare_hdr.svg'
+
+    fig_sdr_only = imshow(bumps, cmap='viridis', hdr=False, figsize=6,
+                          titles='viridis · jxl-p3 (native SDR cmap)')
+    out_sdr_only.write_text(fig_sdr_only._inner.to_string())
+
+    fig_hdr_only = imshow(bumps, cmap='viridis', hdr=True, figsize=6,
+                          titles='viridis · UHDR (HDR-lifted, SDR base = native cmap)')
+    out_hdr_only.write_text(fig_hdr_only._inner.to_string())
+
+    out_html = figures_dir / 'hdr_cmap_compare.html'
+    out_html.write_text(f"""<!doctype html>
+<html><head><meta charset="utf-8">
+<title>HDR vs SDR cmap A/B</title>
+<style>
+  body {{
+    background: #111; color: #ccc; font-family: -apple-system, sans-serif;
+    margin: 20px; line-height: 1.45;
+  }}
+  .row {{ display: flex; gap: 16px; align-items: flex-start; flex-wrap: wrap; }}
+  .col {{ flex: 1 1 480px; min-width: 380px; }}
+  h2 {{ font-size: 14px; color: #888; margin: 6px 0; font-weight: normal; }}
+  p  {{ font-size: 13px; color: #888; max-width: 80ch; }}
+  code {{ color: #ddc; }}
+</style></head>
+<body>
+<h1 style="font-size:16px;color:#aaa">HDR vs SDR cmap A/B (Ultra-HDR + native SDR base)</h1>
+<p>Toggle display HDR (macOS: System Settings → Displays → "High Dynamic
+Range"). On HDR the right tile glows. On SDR the two should be
+pixel-identical — the UHDR's SDR base layer is the same native viridis
+the left tile uses.</p>
+<div class="row">
+  <div class="col"><h2>SDR baseline (jxl-p3, uint8 viridis)</h2>
+    <object data="hdr_cmap_compare_sdr.svg" type="image/svg+xml"
+            style="width:100%"></object>
+  </div>
+  <div class="col"><h2>HDR UHDR (apply_hdr_cmap viridis)</h2>
+    <object data="hdr_cmap_compare_hdr.svg" type="image/svg+xml"
+            style="width:100%"></object>
+  </div>
+</div>
+</body></html>""")
+    print(f"Saved A/B page:  {out_html}")
+    print(f"  SDR JXL:       {out_sdr_only}")
+    print(f"  HDR UHDR:      {out_hdr_only}")
+    print("  Open the HTML in Safari, then toggle Displays → HDR off.")
+    print("  Tiles should now look identical in SDR mode; HDR mode the")
+    print("  right tile gains brightness from the gain map.")
+
+
+if __name__ == '__main__':
+    main()

{ocdkit-0.0.4 → ocdkit-0.0.5}/scripts/bench_vector_contours.py

@@ -1,15 +1,18 @@
 """Benchmark current vector_contours pipeline vs a vectorized prototype.
 
-Loads the ncolor example mask and renders both the current
+Loads a label-mask image and renders both the current
 ocdkit.plot.contour.vector_contours output and a prototype implementation
 side by side, with timings.
 
+Set ``OCDKIT_BENCH_MASK`` to the path of a label-mask PNG before running.
+
 Run:
-    python scripts/bench_vector_contours.py
+    OCDKIT_BENCH_MASK=/path/to/labels.png python scripts/bench_vector_contours.py
 """
 
 from __future__ import annotations
 
+import os
 import time
 from pathlib import Path
 
@@ -245,7 +248,13 @@ def _time_call(fn, repeat=3):
 
 
 def main():
-    mask = skimage.io.imread('/Volumes/DataDrive/ncolor/test_files/example.png')
+    mask_path = os.environ.get('OCDKIT_BENCH_MASK')
+    if not mask_path:
+        raise SystemExit(
+            "Set OCDKIT_BENCH_MASK to the path of a label-mask PNG "
+            "(e.g. export OCDKIT_BENCH_MASK=/path/to/labels.png)."
+        )
+    mask = skimage.io.imread(mask_path)
     print(f"mask shape={mask.shape} n_labels={len(np.unique(mask)) - 1}")
 
     def run_current():
@@ -302,7 +311,7 @@ def main():
     axes[1, 1].set_title("zoomed crop", fontsize=10)
     fig.tight_layout()
 
-    out = Path('/Volumes/DataDrive/ocdkit/scripts/bench_vector_contours.png')
+    out = Path(__file__).resolve().parent / 'bench_vector_contours.png'
     fig.savefig(out, dpi=150, bbox_inches='tight')
     print(f"\nsaved: {out}")
 

ocdkit-0.0.5/scripts/bench_vector_contours_tier2.py

@@ -0,0 +1,108 @@
+"""Bench: marching-squares vector contour pipeline vs legacy.
+
+The library implementation now lives in ``ocdkit.plot.contour``
+(``vector_contours_marching`` / ``cells_to_polygons`` / ``cells_to_webgpu_mesh``)
+-- this file is just a bench runner that compares it against the legacy
+``vector_contours`` and the Tier-1 prototype.
+"""
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import skimage.io
+
+from ocdkit.plot.contour import (
+    vector_contours,
+    vector_contours_marching,
+)
+# Tier 1 prototype kept in scripts/ for comparison only.
+from bench_vector_contours import vector_contours_fast
+
+
+def _time_call(fn, repeat=3):
+    fn()  # warm-up (incl numba compile)
+    ts = []
+    for _ in range(repeat):
+        t0 = time.perf_counter(); fn(); ts.append(time.perf_counter() - t0)
+    return min(ts), ts
+
+
+def main():
+    mask_path = os.environ.get('OCDKIT_BENCH_MASK')
+    if not mask_path:
+        raise SystemExit(
+            "Set OCDKIT_BENCH_MASK to the path of a label-mask PNG "
+            "(e.g. export OCDKIT_BENCH_MASK=/path/to/labels.png)."
+        )
+    mask = skimage.io.imread(mask_path)
+    print(f"mask shape={mask.shape} n_labels={len(np.unique(mask)) - 1}")
+
+    def run_current():
+        fig, ax = plt.subplots(figsize=(5, 5))
+        ax.imshow(mask, cmap='gray', interpolation='nearest')
+        vector_contours(fig, ax, mask, smooth_factor=5, color='r', linewidth=1.0)
+        ax.set_axis_off()
+        plt.close(fig)
+
+    def run_tier1():
+        fig, ax = plt.subplots(figsize=(5, 5))
+        ax.imshow(mask, cmap='gray', interpolation='nearest')
+        vector_contours_fast(fig, ax, mask, smooth_sigma=2.0, color='r', linewidth=1.0)
+        ax.set_axis_off()
+        plt.close(fig)
+
+    def run_tier2():
+        fig, ax = plt.subplots(figsize=(5, 5))
+        ax.imshow(mask, cmap='gray', interpolation='nearest')
+        vector_contours_marching(fig, ax, mask, smooth_sigma=2.0, color='r', linewidth=1.0)
+        ax.set_axis_off()
+        plt.close(fig)
+
+    print("\nBenchmarking (best of 3) ...")
+    cur_best, _ = _time_call(run_current, repeat=3)
+    print(f"  current : {cur_best*1000:6.1f} ms")
+    t1_best, _ = _time_call(run_tier1, repeat=3)
+    print(f"  tier 1  : {t1_best*1000:6.1f} ms  ({cur_best/t1_best:.2f}x)")
+    t2_best, _ = _time_call(run_tier2, repeat=3)
+    print(f"  tier 2  : {t2_best*1000:6.1f} ms  ({cur_best/t2_best:.2f}x)")
+
+    H, W = mask.shape
+    crop_y = slice(H // 3, H // 3 + 80)
+    crop_x = slice(W // 3, W // 3 + 80)
+
+    fig, axes = plt.subplots(2, 3, figsize=(15, 11))
+    for a in axes[0]:
+        a.imshow(mask, cmap='gray', interpolation='nearest')
+        a.set_axis_off()
+    vector_contours(fig, axes[0, 0], mask, smooth_factor=5, color='r', linewidth=1.0)
+    vector_contours_fast(fig, axes[0, 1], mask, smooth_sigma=2.0, color='r', linewidth=1.0)
+    vector_contours_marching(fig, axes[0, 2], mask, smooth_sigma=2.0, color='r', linewidth=1.0)
+    axes[0, 0].set_title(f"Current vector_contours\n{cur_best*1000:.1f} ms", fontsize=11)
+    axes[0, 1].set_title(f"Tier 1 (graph + Gaussian + LineCollection)\n"
+                         f"{t1_best*1000:.1f} ms  ({cur_best/t1_best:.2f}x)", fontsize=11)
+    axes[0, 2].set_title(f"Tier 2 (marching squares numba kernel)\n"
+                         f"{t2_best*1000:.1f} ms  ({cur_best/t2_best:.2f}x)", fontsize=11)
+
+    for a in axes[1]:
+        a.imshow(mask[crop_y, crop_x], cmap='gray', interpolation='nearest',
+                 extent=(crop_x.start, crop_x.stop, crop_y.stop, crop_y.start))
+        a.set_xlim(crop_x.start, crop_x.stop)
+        a.set_ylim(crop_y.stop, crop_y.start)
+        a.set_axis_off()
+        a.set_title("zoomed crop", fontsize=10)
+    vector_contours(fig, axes[1, 0], mask, smooth_factor=5, color='r', linewidth=1.5)
+    vector_contours_fast(fig, axes[1, 1], mask, smooth_sigma=2.0, color='r', linewidth=1.5)
+    vector_contours_marching(fig, axes[1, 2], mask, smooth_sigma=2.0, color='r', linewidth=1.5)
+
+    fig.tight_layout()
+    out = Path(__file__).resolve().parent / 'bench_vector_contours_tier2.png'
+    fig.savefig(out, dpi=150, bbox_inches='tight')
+    print(f"\nsaved: {out}")
+
+
+if __name__ == '__main__':
+    main()

ocdkit-0.0.5/scripts/check_compare_pixels.py

@@ -0,0 +1,77 @@
+"""Direct pixel diff between the two A/B SVGs:
+   - hdr_cmap_compare_sdr.svg → decode the embedded JXL.
+   - hdr_cmap_compare_hdr.svg → decode the UHDR JPEG's SDR base.
+
+If the byte diff is below JPEG-q95 noise (~3-5 max, <1 mean), the two
+tiles contain the same SDR pixels, and any visible difference on screen
+is browser/decoder behavior, not our encoder."""
+import base64
+import re
+import sys
+from pathlib import Path
+
+import numpy as np
+
+REPO = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO / 'src'))
+
+import opencodecs
+import opencodecs.uhdr as uhdr
+
+figs = REPO / 'figures'
+sdr_svg = (figs / 'hdr_cmap_compare_sdr.svg').read_text()
+hdr_svg = (figs / 'hdr_cmap_compare_hdr.svg').read_text()
+
+
+def extract_b64(svg, mime):
+    m = re.search(fr'data:{re.escape(mime)};base64,([A-Za-z0-9+/=]+)', svg)
+    if not m:
+        raise SystemExit(f"no {mime} in svg")
+    return base64.b64decode(m.group(1))
+
+
+# SDR tile: plain JXL with display-p3 color tag.
+sdr_jxl_bytes = extract_b64(sdr_svg, 'image/jxl')
+sdr_tile_u8 = opencodecs.read(sdr_jxl_bytes)
+if sdr_tile_u8.shape[-1] == 4:
+    sdr_tile_u8 = sdr_tile_u8[..., :3]
+print(f"SDR tile JXL → {sdr_tile_u8.shape} {sdr_tile_u8.dtype}")
+
+# HDR tile: UHDR JPEG. Pull the raw SDR base out via libuhdr's api-4
+# decode and decode the inner JPEG with imagecodecs.
+hdr_jpeg = extract_b64(hdr_svg, 'image/jpeg')
+parts = uhdr.decode(hdr_jpeg, want_hdr=False, want_gainmap=False, want_base=True)
+base_jpeg = parts['base_compressed']
+sdr_base_u8 = opencodecs.read(base_jpeg)
+if sdr_base_u8.shape[-1] == 4:
+    sdr_base_u8 = sdr_base_u8[..., :3]
+print(f"UHDR SDR base → {sdr_base_u8.shape} {sdr_base_u8.dtype}")
+
+if sdr_tile_u8.shape != sdr_base_u8.shape:
+    print(f"\nSHAPE MISMATCH — can't diff directly")
+    sys.exit(1)
+
+diff = sdr_tile_u8.astype(np.int16) - sdr_base_u8.astype(np.int16)
+print(f"\nPixel-level diff (SDR-JXL vs UHDR-SDR-base):")
+print(f"  max abs:  {int(np.abs(diff).max())}")
+print(f"  mean abs: {float(np.abs(diff).mean()):.2f}")
+print(f"  p99 abs:  {int(np.percentile(np.abs(diff), 99))}")
+
+# Per-row diff to spot banding (which would alternate across rows in
+# a column-gradient image — i.e. the gradient is column-only, all rows
+# identical).
+mid = sdr_tile_u8.shape[0] // 2
+print(f"\nSample row {mid}, first 10 columns:")
+print(f"  SDR JXL:   {sdr_tile_u8[mid, :10].tolist()}")
+print(f"  UHDR base: {sdr_base_u8[mid, :10].tolist()}")
+
+# Banding signature: count unique colors per row. Banding from a
+# 256-stop LUT would compress 1024 columns into ≤256 unique values.
+unique_jxl = len(np.unique(sdr_tile_u8[mid].view(np.dtype((np.void,
+    sdr_tile_u8[mid].dtype.itemsize * 3)))))
+unique_uhdr = len(np.unique(sdr_base_u8[mid].view(np.dtype((np.void,
+    sdr_base_u8[mid].dtype.itemsize * 3)))))
+print(f"\nUnique colors in mid row "
+      f"({sdr_tile_u8.shape[1]} cols wide):")
+print(f"  SDR JXL:   {unique_jxl}")
+print(f"  UHDR base: {unique_uhdr}")

ocdkit-0.0.5/scripts/check_hdr_cmap.py

@@ -0,0 +1,65 @@
+"""Quick numpy-only sanity check for ocdkit.plot.hdr_cmap.
+
+No matplotlib — imports just the colormap-lift math + cmap package.
+Prints peak Y luminance (in nits) for SDR baseline vs HDR-lifted LUT
+to confirm the lift actually pushes brightness up.
+"""
+import sys
+from pathlib import Path
+
+import numpy as np
+
+REPO = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO / 'src'))
+
+from ocdkit.plot.hdr_cmap import (  # noqa: E402
+    make_hdr_cmap_lut,
+    SDR_WHITE_NITS, HDR_PEAK_NITS_DEFAULT,
+    _XYZ_FROM_SRGB, _P3_FROM_XYZ, _srgb_to_linear,
+)
+from cmap import Colormap  # noqa: E402
+
+# Linear Display-P3 → relative Y (BT.2020-ish weights for P3)
+P3_Y_WEIGHTS = np.array([0.2289745641, 0.6917385218, 0.0792869141])
+
+
+def naive_sdr_lut(name, hdr_peak_nits=HDR_PEAK_NITS_DEFAULT, n=256):
+    """Original SDR cmap converted to linear-P3, normalized to encoder peak.
+    No JzAzBz lift — yardstick for what the lifted LUT improves on."""
+    cm = Colormap(name)
+    rgba = np.asarray(cm(np.linspace(0, 1, n)))
+    lin_srgb = _srgb_to_linear(rgba[:, :3])
+    XYZ_abs = lin_srgb @ _XYZ_FROM_SRGB.T * SDR_WHITE_NITS
+    return np.maximum(XYZ_abs @ _P3_FROM_XYZ.T / hdr_peak_nits, 0)
+
+
+def peak_nits(lut_normed, peak):
+    return float((lut_normed @ P3_Y_WEIGHTS).max() * peak)
+
+
+names = ['viridis', 'magma', 'inferno', 'plasma', 'cividis',
+         'RdBu', 'twilight']
+print(f"{'cmap':12s}  {'SDR peak':>10s}  {'HDR peak':>10s}   lift   "
+      f"max linear-P3")
+for nm in names:
+    sdr = naive_sdr_lut(nm)
+    hdr = make_hdr_cmap_lut(nm)
+    p_sdr = peak_nits(sdr, HDR_PEAK_NITS_DEFAULT)
+    p_hdr = peak_nits(hdr, HDR_PEAK_NITS_DEFAULT)
+    print(
+        f"  {nm:10s}  "
+        f"{p_sdr:7.1f} nits  {p_hdr:7.1f} nits   "
+        f"{p_hdr / max(p_sdr, 1e-3):4.2f}x   "
+        f"SDR={float(sdr.max()):.3f}  HDR={float(hdr.max()):.3f}"
+    )
+
+# Quick visual sanity: how the brightest viridis stop differs.
+sdr_v = naive_sdr_lut('viridis')
+hdr_v = make_hdr_cmap_lut('viridis')
+print("\nviridis brightest stop (last index):")
+print(f"  SDR  lin-P3 RGB = {sdr_v[-1]}  ({sdr_v[-1] @ P3_Y_WEIGHTS * HDR_PEAK_NITS_DEFAULT:.1f} nits)")
+print(f"  HDR  lin-P3 RGB = {hdr_v[-1]}  ({hdr_v[-1] @ P3_Y_WEIGHTS * HDR_PEAK_NITS_DEFAULT:.1f} nits)")
+
+print("\nDarkest stop (purple):")
+print(f"  SDR  {sdr_v[0]}  ({sdr_v[0] @ P3_Y_WEIGHTS * HDR_PEAK_NITS_DEFAULT:.2f} nits)")
+print(f"  HDR  {hdr_v[0]}  ({hdr_v[0] @ P3_Y_WEIGHTS * HDR_PEAK_NITS_DEFAULT:.2f} nits)")