ocdkit 0.0.3__tar.gz → 0.0.5__tar.gz

{ocdkit-0.0.3 → 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.3/src/ocdkit.egg-info → ocdkit-0.0.5}/PKG-INFO

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: ocdkit
-Version: 0.0.3
+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
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy
+Requires-Dist: numpy>=2.0
 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.5/badges/coverage.svg

@@ -0,0 +1 @@
+<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.5/badges/tests.svg

@@ -0,0 +1 @@
+<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.5/docs/plot-backend-roadmap.md

@@ -0,0 +1,95 @@
+# Plot backend roadmap
+
+**Status:** Design discussion / pending decision.
+**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 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 |
+| 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.
+
+The driver question: replace matplotlib with what?
+
+## Library survey (2026-05-07)
+
+Shallow-cloned each candidate, counted Python LOC excluding tests, sphinx, sample data, and auto-generated validators:
+
+| Library | Repo | Relevant Py LOC | Native code | Notes |
+|---|---|---|---|---|
+| matplotlib | — | 186 K | C extensions | What we're replacing |
+| bokeh | 120 MB | 64 K | 150 K TypeScript | UI lives in TS frontend; Py is scene graph + serialization |
+| 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 already uses |
+
+## Tradeoff summary
+
+**Bokeh** — toolbar/logo *can* be removed (`figure(toolbar_location=None)`, `fig.toolbar.logo = None`), but the interaction model lives in a separate TypeScript frontend. To customize hover/zoom UX we'd be writing or forking TypeScript, not Python. The 150 K-LOC TS frontend is essentially the part we'd want to control, and it's the part we can't easily touch.
+
+**Plotly** — same shape. Most LOC is auto-generated validators; the actual rendering and interaction is in the JS bundle. `displayModeBar=False` removes the toolbar but customizing hover beyond what their config exposes means reaching into JS.
+
+**Datoviz** — Vulkan engine is fast and well-architected, but adds a 137 MB binary dependency and a different graphics stack from our existing wgpu-py code. Two graphics backends to maintain instead of one.
+
+**Vispy** — pure Python and has scene + visuals modules that overlap heavily with what we want. But it's OpenGL via PyOpenGL, not WebGPU. We'd be running a second graphics stack alongside our wgpu-py code.
+
+**pygfx** — uses *exactly* the `wgpu-py` we already depend on. Its `gfx.Lines`, `gfx.Mesh`, `gfx.Text`, `gfx.OrthographicCamera` primitives compose directly with our `DensityLineRenderer`. The most architecturally compatible third-party option.
+
+**Roll our own** — given that we already have ~10 K LOC of plotting infrastructure, including a working WGPU line/scatter rasterizer, the increment to "complete 2D plotting library covering our actual needs" is roughly 3–5 K LOC. The scope is well-defined: axes, ticks, labels, legend, image display, hover, export.
+
+## Recommendation
+
+**Two-step.**
+
+### Step 1: pygfx prototype (1 day)
+
+Spike a `plot_spectra_pygfx` that uses `pygfx.Lines` + `pygfx.Text` + an `OrthographicCamera` to reproduce the current spectra layout. This is cheap because pygfx and our existing WGPU code share the same `wgpu-py` device — they can literally run in the same process without backend conflict.
+
+What to evaluate:
+- Visual quality vs. our current WGPU-rendered density lines (especially anti-aliasing)
+- Text rendering quality (pygfx uses FreeType-rendered SDFs)
+- Hover/picking — does pygfx's built-in picking suffice for our tooltip needs?
+- Export — pygfx renders to a wgpu canvas; PNG export is straightforward, PDF/SVG would need our own rasterize-and-vectorize path
+
+If pygfx covers ≥80% of our needs at ≥80% of the visual quality, **adopt pygfx**. We get hover, zoom, pan, picking essentially for free, plus the `pygfx` ecosystem (geometries, materials, post-processing).
+
+### Step 2 (only if pygfx is insufficient): roll our own
+
+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 |
+| `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 the downstream plot package (~1 K LOC saved) and removal of matplotlib runtime dep.
+
+### Why not pygfx + own axes?
+
+A hybrid path is also viable: use pygfx for the rasterization layer (lines/text/transform/camera) and write our own axis/tick/legend/hover layer on top. That'd be the best of both — pygfx handles the rendering substrate, we own the plotting semantics. Estimated ~1.5 K LOC of new code on top of pygfx.
+
+## Open questions
+
+1. **Hover semantics** — does the classification-debugger tooltip pattern generalize cleanly, or do different plots need different hover content models?
+2. **Export fidelity** — do we need true vector PDF, or is high-DPI PNG enough? Vector requires re-rasterizing axes/text on the CPU side, which is non-trivial.
+3. **Notebook + standalone parity** — pygfx renders to a wgpu canvas that displays inline in Jupyter via `wgpu_jupyter`. Does that path work in VS Code's Jupyter extension and in standalone scripts (`savefig`-equivalent)?
+4. **Remoting** — if we ever want a server-side render pipeline (for cloud GUIs), pygfx's WGPU backend can render headlessly; matplotlib `Agg` does the same. Bokeh/plotly's JS-frontend assumption is harder to remote.
+
+## Concrete next action
+
+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.3 → ocdkit-0.0.5}/pyproject.toml

@@ -10,11 +10,19 @@ readme = "README.md"
 license = {text = "BSD-3-Clause"}
 requires-python = ">=3.11"
 dependencies = [
-    "numpy",
+    # numpy >= 2.0 — np.unique was reworked / sped up in the 2.0 cycle
+    # and matches fastremap.unique on label arrays. Helpers like
+    # array.ops.unique_nonzero / is_sequential rely on that parity to
+    # avoid hard-importing fastremap.
+    "numpy>=2.0",
     "scipy",
     "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",
@@ -28,6 +36,7 @@ dependencies = [
     "tqdm",
     "platformdirs",
     "cryptography",
+    "lxml",
 ]
 
 [project.optional-dependencies]
@@ -78,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.5/scripts/bench_contour_alignment.py

@@ -0,0 +1,81 @@
+"""Synthetic single-cell test for contour alignment.
+
+Plots a small mask with grid lines at integer pixel boundaries so we can
+see exactly where each pipeline puts its outline relative to:
+  - the pixels of the cell  (filled gray squares spanning [j-.5, j+.5] x [i-.5, i+.5])
+  - the cell boundary       (gridline at half-integer y and x at the cell edge)
+
+The three pipelines are:
+  - current (B-spline through pixel centers)
+  - tier 1  (Gaussian-smoothed pixel-center walk)
+  - tier 2  (marching squares; geometric cell boundary)
+
+Also tests the new `offset` knob in tier 2.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from bench_vector_contours import vector_contours_fast
+from ocdkit.plot.contour import vector_contours, vector_contours_marching
+
+
+def make_mask():
+    m = np.zeros((20, 20), dtype=np.int32)
+    m[5:11, 5:11] = 1   # 6x6 square cell
+    m[14:17, 13:18] = 2  # 3x5 rectangle cell
+    return m
+
+
+def add_grid(ax, shape):
+    H, W = shape
+    for x in np.arange(-0.5, W, 1):
+        ax.axvline(x, color='cyan', linewidth=0.3, alpha=0.35, zorder=0)
+    for y in np.arange(-0.5, H, 1):
+        ax.axhline(y, color='cyan', linewidth=0.3, alpha=0.35, zorder=0)
+
+
+def main():
+    mask = make_mask()
+
+    fig, axes = plt.subplots(2, 2, figsize=(12, 12))
+
+    titles = [
+        "Current vector_contours (splprep) — note up-left bias",
+        "Tier 1 (gaussian on pixel-center walk)",
+        "Tier 2 default offset=0 (geometric cell boundary)",
+        "Tier 2 offset=0.5 (through pixel centers, no bias)",
+    ]
+    for ax, title in zip(axes.flat, titles):
+        ax.imshow(mask, cmap='gray_r', interpolation='nearest', vmin=0, vmax=2)
+        add_grid(ax, mask.shape)
+        ax.set_title(title, fontsize=10)
+        ax.set_xticks(range(mask.shape[1]))
+        ax.set_yticks(range(mask.shape[0]))
+        ax.tick_params(labelsize=6)
+
+    vector_contours(fig, axes[0, 0], mask, smooth_factor=5,
+                    color='red', linewidth=1.5)
+    vector_contours_fast(fig, axes[0, 1], mask, smooth_sigma=1.0,
+                         color='red', linewidth=1.5)
+    vector_contours_marching(fig, axes[1, 0], mask, smooth_sigma=1.0,
+                             color='red', linewidth=1.5)
+    # Tier 2 with offset (still need to add the knob — we'll do that next)
+    vector_contours_marching(fig, axes[1, 1], mask, smooth_sigma=1.0,
+                             color='red', linewidth=1.5)
+
+    fig.tight_layout()
+    out = Path(__file__).resolve().parent / 'bench_contour_alignment.png'
+    fig.savefig(out, dpi=150, bbox_inches='tight')
+    print(f"saved: {out}")
+
+
+if __name__ == '__main__':
+    main()

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()