@jax-data-science/sci-image-visualizer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Jackson Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,404 @@
+# @jax-data-science/sci-image-visualizer
+
+[![npm](https://img.shields.io/npm/v/%40jax-data-science%2Fsci-image-visualizer.svg)](https://www.npmjs.com/package/@jax-data-science/sci-image-visualizer)
+[![CI / CD](https://github.com/TheJacksonLaboratory/sci-image-visualizer/actions/workflows/ci-cd.yaml/badge.svg)](https://github.com/TheJacksonLaboratory/sci-image-visualizer/actions/workflows/ci-cd.yaml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+A framework-style **Angular 17** library for **interactive scientific image
+visualization and annotation**. It renders large / multi-channel images through
+pluggable backends — a tiled [OpenSeadragon](https://openseadragon.github.io/)
+viewer, [Plotly](https://plotly.com/javascript/) 2D/3D plots, and a
+[napari-js](https://www.npmjs.com/package/napari-js) **WebGPU** backend — behind a
+single `IVisualizer` contract, and provides a rich set of on-canvas region /
+annotation tools including **AI-assisted segmentation that runs entirely in the
+browser** (WebGPU / WASM via [`onnxruntime-web`](https://github.com/microsoft/onnxruntime)).
+
+Extracted from [jit-ui](https://github.com/TheJacksonLaboratory/jit-ui) (JAX Image
+Tools) — see [jit-ui#80](https://github.com/TheJacksonLaboratory/jit-ui/issues/80) —
+so the same viewer can be reused across the `@jax-data-science` portfolio. Open
+source; contributions welcome.
+
+## Installation
+
+```bash
+npm install @jax-data-science/sci-image-visualizer
+```
+
+Install the Angular / rendering **peer dependencies** your app doesn't already
+have:
+
+```bash
+npm install @angular/animations @angular/router primeng \
+  openseadragon plotly.js-dist-min image-js file-saver buffer onnxruntime-web
+```
+
+### Peer dependencies
+
+| Package | Range | Notes |
+|---|---|---|
+| `@angular/common` · `core` · `forms` · `animations` · `router` | `^17.3.0` | Angular 17 (animations + router are needed by the PrimeNG components) |
+| `rxjs` | `^7.8.0` | |
+| `primeng` | `^17.18.0` | toolbar / dialogs / table / dropdown UI |
+| `image-js` | `^0.35.6` | client-side image processing |
+| `file-saver` | `^2.0.5` | GeoJSON / mask export |
+| `buffer` | `^5.7.1` | |
+| `onnxruntime-web` | `~1.26.0` | browser SAM / cellpose inference (WebGPU/WASM) |
+| `cellpose-js` | `^0.3.0` | automatic cellpose-SAM segmentation |
+
+The rendering backends and helpers — `openseadragon`, `plotly.js-dist-min`,
+`napari-js`, `fast-png`, and `tslib` — are declared as regular **dependencies**
+and installed automatically; you don't add them yourself. See
+[Quick start](#usage-host-integration-brief) below for wiring.
+
+## Live demo & running the example
+
+A serverless, **in-browser** example lives in
+[`examples/browser-image/`](examples/browser-image/): a gallery of sample images
+that render in the viewer with the region + zoom tools, with no backend at all
+(the "Mode B" path — each image is a self-contained `tiled: false` source).
+
+**Live demo:** <https://thejacksonlaboratory.github.io/sci-image-visualizer/> —
+published by CI (`.github/workflows/pages.yaml`) to GitHub Pages on every push to `main`.
+
+### Run on localhost
+
+```bash
+npm install            # repo + example toolchain (Vite + Analog)
+git lfs pull           # fetch the sample-image bytes (they're stored in Git LFS)
+npm run build          # build the library into dist/ (the example consumes it)
+npm run start:example  # dev server → http://localhost:5173
+```
+
+`npm run build:example` produces a static build in `examples/browser-image/dist/`.
+See [`examples/browser-image/README.md`](examples/browser-image/README.md) for the
+full walkthrough (adapters, TIFF handling, the Angular-17 toolchain note).
+
+## Highlights
+
+- **Three rendering backends** — a tiled [OpenSeadragon](https://openseadragon.github.io/)
+  viewer, [Plotly](https://plotly.com/javascript/) plots, and a
+  [napari-js](https://www.npmjs.com/package/napari-js) **WebGPU** backend — behind
+  one `IVisualizer` contract; the host picks per plot type via `RoutingVisualizerService`.
+- **Plot types** — Image (OSD), Plotly (Heatmap, Contour, Scatter 2D, Surface 3D,
+  Scatter 3D, Isosurface), and napari · WebGPU (Image, Scatter 2D, Surface,
+  Scatter 3D, Volume, Isosurface).
+- **Region / annotation tools** — selection, rectangle, polyline, freeform,
+  polygon + vertex editing, move, Bézier↔polygon, magic wand, brush, vertex eraser.
+- **Channels & histogram** — brightness/contrast/gamma, per-channel display,
+  colormaps / LUTs.
+- **Region editor** — a Regions panel to list, select, rename, classify, recolor,
+  import/export (GeoJSON), and delete regions.
+- **Image stacks** — a z-stack can be a single server-tiled file (internal z) or
+  a set of self-contained per-slice image URLs (`IImageInfo.tiled === false`, one
+  URL per slice), e.g. a folder of numbered files assembled by the host. Slices
+  load on demand as you scrub.
+- **Per-slice ROIs + QuPath planes** — GeoJSON import/export carries the QuPath
+  image-plane convention (`geometry.plane.z`), and the host can supply one ROI
+  set per slice (`IImageInfo.roiJsonStrs`) that the viewer swaps on scrub.
+- **Browser-side segmentation** — promptable SAM (box + interactive points) and
+  automatic cellpose-SAM, all client-side (see below).
+
+## Visualization
+
+Open an image and it renders through whichever backend best fits it; the
+`RoutingVisualizerService` switches backends per plot type and keeps the shared
+state (regions, channels, zoom) consistent across them.
+
+### OpenSeadragon — tiled image view
+The default **Image** view is a natively tiled, deeply zoomable raster powered by
+[OpenSeadragon](https://openseadragon.github.io/). It streams pyramid tiles (the
+host supplies them through the `TILE_ACCESS_PORT`, e.g. a `/tiles/info` + `/tile`
+service), so gigapixel slides pan and zoom smoothly without loading the whole
+image. It includes:
+
+- a **navigator minimap** and a physical-units **scale bar**;
+- **click-to-zoom** toward the clicked point, scroll-zoom, and drag-pan;
+- a **raw-pixel vs. smoothing** toggle — images open at nearest-neighbour so
+  zoomed-in pixels stay crisp for inspection; toggle **Smoothen** for bilinear;
+- **WYSIWYG PNG download** of the current view and a **fit-to-view / autoscale**
+  reset.
+
+### Plotly — plots & 3D
+Non-image plot types render with [Plotly](https://plotly.com/javascript/) and
+support "real zooming" — a downscaled overview that re-fetches higher-resolution
+data as you zoom in:
+
+- **Contour** and **Scatter (regions)** 2D plots;
+- **Surface 3D**, **Scatter 3D**, and **Isosurface** for z-stacks, with an
+  **isosurface band** slider and full **3D camera** controls (zoom, pan, orbit,
+  turntable, reset);
+- scalar/3D types expect a grayscale image (the volume types also need a z-stack).
+
+### napari-js — WebGPU
+GPU-accelerated renderings via [napari-js](https://www.npmjs.com/package/napari-js)
+(WebGPU), selectable from the plot-type menu as the "napari · WebGPU" variants of
+Image, Scatter 2D, Surface, Scatter 3D, **Volume**, and **Isosurface**. It
+assembles the volume from the slice endpoints with a runtime **decimate factor**
+(resolution slider, default ½), a surface **wireframe** toggle, a 3D **axes / scale
+gizmo**, an in-view **Z-height drag handle** for the volume, **cancellable** loading,
+and **multichannel volume** compositing (one additive tinted layer per channel).
+Regions and display options stay in sync with the other backends via the shared
+stores.
+
+When a stack is open, a slice slider (Image view) or single-image/stack toggle
+(other views) navigates the z-dimension. A stack may be one server-tiled file
+(internal z) or a set of self-contained per-slice URLs (`IImageInfo.tiled ===
+false`) — the latter (e.g. a host-assembled folder of numbered files) fetches
+`urls[z]` per slice on demand. For a per-slice stack the host can also supply a
+matching ROI GeoJSON per slice (`IImageInfo.roiJsonStrs`), which the viewer
+shows for the displayed slice and swaps as you scrub.
+
+### Intensity profiles *(work in progress)*
+A line-ROI tool draws coloured lines and plots intensity along each one in a live
+floating inset chart that re-samples at the current zoom. It works today but the
+API/UX are still stabilizing (see [In progress / roadmap](#in-progress--roadmap)).
+
+## Regions & annotation
+
+Regions are stored in a shared **region store** and use a GeoJSON-friendly model
+(rectangles, polygons, polylines, Bézier curves) with an optional zero-based
+`z` slice — GeoJSON import/export uses QuPath's `geometry.plane.z` (written only
+for non-default slices, so single-plane images round-trip byte-identically).
+Every tool writes to the same store, so regions persist across backend/plot-type
+switches and are editable from the Regions panel. The on-canvas tools:
+
+- **Selection** — neutral mode; deactivates any drawing tool.
+- **Rectangle**, **Polyline** (open `LineString`), **Freeform** (drag-to-draw
+  closed polygon), and **Polygon** (click vertices, click first to close).
+- **Vertex editing** — add vertex, delete vertex, and **move region**.
+- **Bézier ↔ polygon** — convert a region to a smooth Bézier curve or back.
+- **Magic wand** — grow a region from similar-valued pixels around the click;
+  `Ctrl`/`Cmd` for exact-match flood fill; drag to extend; `Shift` to erase;
+  a sensitivity slider tunes strictness. Growing into another region merges them.
+- **Brush** — paint/erase a region with a circular brush (QuPath-style); a size
+  slider sets the diameter, `Shift` erases, and erasing across a region can split it.
+- **Vertex eraser** — remove vertices within a radius from any region.
+- **Delete** the selected region.
+
+Wand- and brush-drawn regions default to the `legend` class; SAM/cellpose masks
+inherit the color of the rectangle they came from.
+
+## Channels, histogram & colormaps
+
+A floating **Channels & Histogram** dialog controls how intensities are mapped to
+display: **brightness / contrast / gamma**, **per-channel** display for
+multi-channel images, and — for grayscale — **colormap / LUT** selection with a
+**reverse** toggle (default: inverted greys). Changes apply live in both backends.
+
+## Region editor (Regions panel)
+
+The `<region-editor>` component is the Regions tab: a table of all regions
+where you can **select**, **rename**, assign a **classification / class name**,
+set **per-class colors**, toggle labels, **import / export ROIs** as GeoJSON
+(`REGION_IO_PORT`), and **delete**. Selecting a row highlights the region on the
+canvas (and vice-versa), so it pairs with the on-canvas tools above.
+
+## Segmentation tools (SAM & cellpose)
+
+All segmentation runs **client-side** — models are fetched once (a progress
+toast is shown), cached, then executed with `onnxruntime-web` (WebGPU where
+supported, WASM otherwise). Generated regions inherit the color of the rectangle
+they came from.
+
+### Box-prompt SAM — "Segment"
+Draw one or more **rectangles** around objects, then click **Segment**. Each
+rectangle is sent to SAM as a box prompt and replaced by the segmented mask.
+
+### Interactive point prompts
+Click directly on an object to segment it as a **new** region (each click is an
+independent object — clicking another object won't grow the previous one).
+`Shift`/`Alt`-click adds an *exclude* point that refines the current object;
+`Enter` commits, `Esc` undoes.
+
+### Model picker
+A dropdown on the Segment button chooses the SAM model; the choice applies to
+**both** the box and point tools. An info button summarizes the trade-offs.
+
+### Cellpose — automatic
+Draw rectangles, then click **Cellpose** to auto-segment every cell inside each
+rectangle (client-side cellpose-SAM via [`cellpose-js`](https://www.npmjs.com/package/cellpose-js)) —
+one region per detected cell, no per-object clicking. (Cellpose-SAM is *not*
+promptable, so it's the automatic tool rather than a model in the SAM picker.)
+
+## Models
+
+Promptable SAM models are SAM-v1 encoder/decoder ONNX pairs (the encoder runs
+once per image; the decoder runs per prompt). The registry lives in
+`src/lib/toolbar/sam-model-registry.ts`; the host supplies hosted URLs via
+`setSamModelUrls(...)`. Export/quantization tooling lives in the sibling
+`browser-onnx-tools` project.
+
+| Picker id | Domain | Encoder | Runs on | HF model |
+|---|---|---|---|---|
+| `microsam-vit-t-lm` *(default)* | light microscopy | TinyViT, ~14 MB fp16 | WASM¹ | [Ballon999/microsam-vit-t-lm-onnx](https://huggingface.co/Ballon999/microsam-vit-t-lm-onnx) |
+| `microsam-vit-b-lm` | light microscopy | ViT-B, ~172 MB fp16 | WebGPU | [Ballon999/microsam-vit-b-lm-onnx](https://huggingface.co/Ballon999/microsam-vit-b-lm-onnx) |
+| `patho-sam-vit-b` | histopathology (H&E) | ViT-B, ~172 MB fp16 | WebGPU | [Ballon999/patho-sam-vit-b-onnx](https://huggingface.co/Ballon999/patho-sam-vit-b-onnx) |
+| `patho-sam-vit-b-int8` | histopathology (H&E) | ViT-B, ~100 MB int8 | WASM | [Ballon999/patho-sam-vit-b-onnx](https://huggingface.co/Ballon999/patho-sam-vit-b-onnx) (`encoder.int8.onnx`) |
+| cellpose-SAM *(automatic)* | cells (generalist) | SAM ViT + flow head | WebGPU/WASM | [ballon999/cellpose-sam-onnx](https://huggingface.co/ballon999/cellpose-sam-onnx) |
+
+¹ TinyViT's fp16 attention overflows on the onnxruntime-web WebGPU EP (returns an
+empty mask); it is numerically correct and fast on WASM, so its encoder is pinned
+to WASM. int8 models also run on WASM (no WebGPU int8 matmul).
+
+micro-sam and patho-sam are distributed through micro-sam's model registry
+(`vit_*_lm`, `vit_*_histopathology`); SAM 3 is a planned addition (it needs a
+`variant: 'sam3'` decoder path, since SAM 2/3 differ in mask I/O). See
+`docs/sam-segmentation-design.md` for the design.
+
+## In progress / roadmap
+
+Work that is landed-but-unstable or planned (not yet available):
+
+- **Intensity profile tool** *(work in progress — not yet stable)* — coloured line
+  ROIs with a floating inset chart that plots intensity along each line and updates
+  live as the line is dragged. Usable today but the API/UX and multi-line/stack
+  behaviour are still settling.
+- **Example / test server + demos** *(planned)* — a small example server, bundled
+  with the library, that powers a set of runnable **demos** showcasing the
+  image-visualization use cases (tiled OSD viewing, Plotly plots, region tools,
+  and browser-side SAM/cellpose segmentation) against sample images — so the
+  library can be evaluated and developed standalone, outside jit-ui. Tracked in
+  the library-extraction SOW ([docs/JIT_UI_visualization_library_SOW.docx](docs/JIT_UI_visualization_library_SOW.docx)).
+- **SAM 3 model** *(planned)* — a `variant: 'sam3'` decoder path + export tooling
+  (SAM 2/3 use a different mask I/O than the current SAM-v1 path). See
+  [docs/sam-segmentation-design.md](docs/sam-segmentation-design.md).
+- **int8 patho-sam validation** — the `patho-sam-vit-b-int8` option is sanity-checked
+  (IoU ~0.99 vs fp16 on a synthetic prompt) but not yet validated on real H&E
+  slides, where int8 ViT attention can degrade on subtle boundaries.
+
+## Documentation
+
+Design, architecture, and planning docs for the library:
+
+- **[docs/sam-segmentation-design.md](docs/sam-segmentation-design.md)** — design of
+  the browser SAM segmentation: model choice, ONNX export/quantization recipe,
+  encoder/decoder I/O, the engine/session architecture, and the rollout phases.
+- **Architecture diagrams**
+  - [docs/jit-ui-visualization-architecture.mmd](docs/jit-ui-visualization-architecture.mmd)
+    ([PNG](docs/img/jit-ui-visualization-architecture.png) ·
+    [SVG](docs/img/jit-ui-visualization-architecture.svg)) — host ⇄ library ⇄
+    rendering backends, ports, and the jit-service request flow (tiles, preview,
+    region/zoom, Plotly data).
+  - [docs/jit-ui-region-architecture.mmd](docs/jit-ui-region-architecture.mmd)
+    ([PNG](docs/img/jit-ui-region-architecture.png) ·
+    [SVG](docs/img/jit-ui-region-architecture.svg)) — the region interfaces +
+    region tools and how OSD and Plotly each implement the overlay.
+  - Diagram/SOW generators: [docs/gen_architecture_diagram.py](docs/gen_architecture_diagram.py),
+    [docs/gen_jit_ui_visualization_sow.py](docs/gen_jit_ui_visualization_sow.py).
+- **[docs/JIT_UI_visualization_library_SOW.docx](docs/JIT_UI_visualization_library_SOW.docx)** —
+  statement of work for extracting/publishing this library (incl. test-coverage
+  results and the example-server task).
+- **[REFACTORING-PLAN.md](docs/REFACTORING-PLAN.md)** — the plan that shaped the
+  current module/contract/implementation boundaries.
+
+Related (host side, in jit-ui):
+
+- **[USE-VISUALIZATION-LIB-IN-PIPELINE-DIALOG.md](https://github.com/TheJacksonLaboratory/jit-ui/blob/master/apps/jit-ui/src/app/main/components/processing-pipeline/USE-VISUALIZATION-LIB-IN-PIPELINE-DIALOG.md)** —
+  how the processing-pipeline dialog embeds `<visualizer>` and drives it
+  via `RoutingVisualizerService`.
+- **[processing-pipeline/ARCHITECTURE.md](https://github.com/TheJacksonLaboratory/jit-ui/blob/master/apps/jit-ui/src/app/main/models/processing-pipeline/ARCHITECTURE.md)** —
+  the client/server processing-pipeline engines (OpenCV.js, transformers.js,
+  cellpose, client slide-crop, server) that consume this library's region tools.
+
+## Scientific references
+
+**Segment Anything (SAM)** — the promptable segmentation foundation model.
+> Kirillov, A. et al. *Segment Anything.* ICCV 2023. arXiv:[2304.02643](https://arxiv.org/abs/2304.02643).
+> Code: [facebookresearch/segment-anything](https://github.com/facebookresearch/segment-anything).
+
+**micro-sam** — SAM finetuned for microscopy (the `*_lm` models; default tool).
+> Archit, A. et al. *Segment Anything for Microscopy.* Nature Methods (2025); bioRxiv:[2023.08.21.554208](https://doi.org/10.1101/2023.08.21.554208).
+> Code: [computational-cell-analytics/micro-sam](https://github.com/computational-cell-analytics/micro-sam).
+
+**patho-sam** — SAM finetuned for histopathology (the `*_histopathology` models).
+> *Segment Anything for Histopathology.* arXiv:[2502.00408](https://arxiv.org/abs/2502.00408) (computational-cell-analytics).
+> Code: [computational-cell-analytics/patho-sam](https://github.com/computational-cell-analytics/patho-sam).
+
+**Cellpose** — generalist cellular segmentation (flow-field algorithm).
+> Stringer, C. et al. *Cellpose: a generalist algorithm for cellular segmentation.* Nature Methods 18, 100–106 (2021). doi:[10.1038/s41592-020-01018-x](https://doi.org/10.1038/s41592-020-01018-x).
+> Code: [MouseLand/cellpose](https://github.com/MouseLand/cellpose).
+
+**Cellpose-SAM** — Cellpose built on a SAM ViT backbone (the automatic tool).
+> Stringer, C. & Pachitariu, M. *Cellpose-SAM: superhuman generalization for cellular segmentation.* bioRxiv:[2025.04.28.651001](https://doi.org/10.1101/2025.04.28.651001).
+> Model: [mouseland/cellpose-sam](https://huggingface.co/mouseland/cellpose-sam).
+
+**MobileSAM** — the TinyViT encoder behind micro-sam ViT-T.
+> Zhang, C. et al. *Faster Segment Anything: Towards Lightweight SAM for Mobile Applications.* arXiv:[2306.14289](https://arxiv.org/abs/2306.14289) (2023).
+> Code: [ChaoningZhang/MobileSAM](https://github.com/ChaoningZhang/MobileSAM).
+
+**Rendering & runtime libraries**
+
+- **OpenSeadragon** — deep-zoom tiled image viewer.
+  [openseadragon.github.io](https://openseadragon.github.io/) ·
+  [GitHub](https://github.com/openseadragon/openseadragon).
+- **Plotly.js** — interactive 2D/3D plotting.
+  [plotly.com/javascript](https://plotly.com/javascript/) ·
+  [GitHub](https://github.com/plotly/plotly.js).
+- **napari** — multi-dimensional (n-D) scientific image viewer; the WebGPU
+  rendering backend here (`napari-js`) is modeled on it.
+  [napari.org](https://napari.org) · [GitHub](https://github.com/napari/napari) ·
+  doi:[10.5281/zenodo.3555620](https://doi.org/10.5281/zenodo.3555620).
+- **onnxruntime-web** — WebGPU/WASM ONNX inference (the SAM & cellpose runtime).
+  [GitHub](https://github.com/microsoft/onnxruntime).
+
+Please cite the relevant model papers when publishing results produced with these
+tools.
+
+## Usage (host integration, brief)
+
+Import `VisualizationModule`, render `<visualizer>` (and `<region-editor>` for
+the Regions panel), and provide the DI ports (`TILE_ACCESS_PORT`,
+`IMAGE_STATE_PORT`, `REGION_IO_PORT`, `VIZ_CONFIG`, and `CELL_SEGMENTER` for the
+cellpose adapter). Configure hosted SAM model URLs once at startup:
+
+```ts
+import { setSamModelUrls } from '@jax-data-science/sci-image-visualizer';
+
+setSamModelUrls('microsam-vit-t-lm',
+  'https://huggingface.co/Ballon999/microsam-vit-t-lm-onnx/resolve/main/encoder.fp16.onnx',
+  'https://huggingface.co/Ballon999/microsam-vit-t-lm-onnx/resolve/main/decoder.onnx');
+```
+
+`onnxruntime-web` WASM/JSEP sidecars must be served from `/assets/ort/`. See
+jit-ui's `app.module.ts` for a full wiring example.
+
+Each embeddable component uses a plain, unprefixed selector: `visualizer`,
+`region-editor`, `plotting-toolbar`, `channel-histogram`, `hex-color-picker`.
+
+## Development
+
+```bash
+npm install
+npm run build       # ng-packagr → ./dist  (the publishable package)
+npm test            # jest (jest-preset-angular)
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint
+npm run format      # prettier --write
+```
+
+`npm run build` emits a complete, publishable Angular package into `dist/`
+(FESM2022 + ESM2022 bundles, type declarations, assets, README, LICENSE).
+
+## Releasing
+
+Publishing is automated by CI (`.github/workflows/ci-cd.yaml`): pushing a
+`v*.*.*` tag whose version matches `package.json` and is reachable from `main`
+(or a `release/x.y.z` branch) builds, tests, and runs
+`npm publish --access public --provenance` from `dist/`. It requires an
+`NPM_TOKEN` repository secret with publish rights to the `@jax-data-science`
+npm scope.
+
+```bash
+# bump package.json to x.y.z first, commit, then:
+git tag vx.y.z && git push origin vx.y.z
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Please run `npm run lint`, `npm test`, and
+`npm run build` before opening a PR. Design and architecture notes live in
+[`docs/`](docs/).
+
+## License
+
+[MIT](./LICENSE) © The Jackson Laboratory.

package/esm2022/index.mjs

@@ -0,0 +1,52 @@
+/**
+ * Public API of the jax-image-visualization library. External consumers import
+ * ONLY from here (`@jax-data-science/sci-image-visualizer`); everything else under `lib/` is
+ * internal. The surface is contracts + tokens + neutral models + the Angular
+ * module, plus the routing service the host's composition root binds the tokens
+ * to (`useExisting`).
+ */
+// ── Contracts & DI tokens ────────────────────────────────────────────────
+export * from './lib/contracts/visualizer.contract';
+export * from './lib/contracts/region-editor-api.contract';
+export * from './lib/contracts/ports/image-state.port';
+export * from './lib/contracts/ports/tile-access.port';
+export * from './lib/contracts/ports/region-io.port';
+export * from './lib/contracts/ports/preferences.port';
+export * from './lib/contracts/channel-histogram-api.contract';
+export * from './lib/contracts/viz-config';
+export * from './lib/contracts/image.contract';
+export * from './lib/contracts/plot-type';
+export * from './lib/contracts/toolbar-config';
+export * from './lib/contracts/capabilities.contract';
+export * from './lib/contracts/region-overlay.contract';
+export * from './lib/contracts/display-types';
+export * from './lib/contracts/sam.contract';
+export * from './lib/contracts/cell-segmenter.contract';
+export { CellposeSegmenterService } from './lib/toolbar/segmentation/cellpose-segmenter.service';
+// ── Generic client-side image utilities (shared with the host's pipeline) ──
+export { ProcessingImage } from './lib/processing/processing-image';
+export { cropImage } from './lib/processing/image-crop';
+export { ImageConverterService } from './lib/processing/image-converter.service';
+// ── SAM model registry (host configures hosted ONNX URLs once available) ──
+export { SAM_MODELS, DEFAULT_SAM_MODEL_ID, getSamModel, isSamModelReady, setSamModelUrls, setDefaultSamModel, getDefaultSamModelId, } from './lib/toolbar/segmentation/sam-model-registry';
+// ── onnxruntime-web WASM location (host overrides once, at app init) ───────
+export { setOrtWasmBase, getOrtWasmBase } from './lib/toolbar/segmentation/ort-runtime-config';
+// ── Neutral data models ──────────────────────────────────────────────────
+export * from './lib/models/region';
+export * from './lib/models/class-preset';
+export { ShapeSelection } from './lib/models/shape';
+// ── Angular module + composition-root service ────────────────────────────
+export { VisualizationModule } from './lib/visualization.module';
+export { RoutingVisualizerService } from './lib/routing-visualizer.service';
+// Provider factory for an isolated, component-scoped viewer instance (e.g. a
+// modal that must not share the main viewer's region/image state).
+export { provideVisualization } from './lib/provide-visualization';
+// ── Public components (exported by VisualizationModule) ───────────────────
+// ng-packagr requires module-exported components to be reachable from the
+// entry point so consumers get their types; these are the embeddable elements
+// (`<visualizer>`, `<region-editor>`, `<hex-color-picker>`).
+export { VisualizerComponent } from './lib/visualizer.component';
+export { RegionEditorComponent } from './lib/region-editor/region-editor.component';
+export { HexColorPickerComponent } from './lib/hex-color-picker/hex-color-picker.component';
+export { ChannelHistogramComponent } from './lib/channel-histogram/channel-histogram.component';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7OztHQU1HO0FBRUgsNEVBQTRFO0FBQzVFLGNBQWMscUNBQXFDLENBQUM7QUFDcEQsY0FBYyw0Q0FBNEMsQ0FBQztBQUMzRCxjQUFjLHdDQUF3QyxDQUFDO0FBQ3ZELGNBQWMsd0NBQXdDLENBQUM7QUFDdkQsY0FBYyxzQ0FBc0MsQ0FBQztBQUNyRCxjQUFjLHdDQUF3QyxDQUFDO0FBQ3ZELGNBQWMsZ0RBQWdELENBQUM7QUFDL0QsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLGdDQUFnQyxDQUFDO0FBQy9DLGNBQWMsMkJBQTJCLENBQUM7QUFDMUMsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLHVDQUF1QyxDQUFDO0FBQ3RELGNBQWMseUNBQXlDLENBQUM7QUFDeEQsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLDhCQUE4QixDQUFDO0FBQzdDLGNBQWMseUNBQXlDLENBQUM7QUFDeEQsT0FBTyxFQUFFLHdCQUF3QixFQUFFLE1BQU0sdURBQXVELENBQUM7QUFFakcsOEVBQThFO0FBQzlFLE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSxtQ0FBbUMsQ0FBQztBQUNwRSxPQUFPLEVBQUUsU0FBUyxFQUFvQixNQUFNLDZCQUE2QixDQUFDO0FBQzFFLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxNQUFNLDBDQUEwQyxDQUFDO0FBRWpGLDZFQUE2RTtBQUM3RSxPQUFPLEVBQ0wsVUFBVSxFQUFFLG9CQUFvQixFQUFFLFdBQVcsRUFBRSxlQUFlLEVBQUUsZUFBZSxFQUMvRSxrQkFBa0IsRUFBRSxvQkFBb0IsR0FDekMsTUFBTSwrQ0FBK0MsQ0FBQztBQUV2RCw4RUFBOEU7QUFDOUUsT0FBTyxFQUFFLGNBQWMsRUFBRSxjQUFjLEVBQUUsTUFBTSwrQ0FBK0MsQ0FBQztBQUUvRiw0RUFBNEU7QUFDNUUsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLDJCQUEyQixDQUFDO0FBQzFDLE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUVwRCw0RUFBNEU7QUFDNUUsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFDakUsT0FBTyxFQUFFLHdCQUF3QixFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFDNUUsNkVBQTZFO0FBQzdFLG1FQUFtRTtBQUNuRSxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUVuRSw2RUFBNkU7QUFDN0UsMEVBQTBFO0FBQzFFLDhFQUE4RTtBQUM5RSw2REFBNkQ7QUFDN0QsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFDakUsT0FBTyxFQUFFLHFCQUFxQixFQUFFLE1BQU0sNkNBQTZDLENBQUM7QUFDcEYsT0FBTyxFQUFFLHVCQUF1QixFQUFFLE1BQU0sbURBQW1ELENBQUM7QUFDNUYsT0FBTyxFQUFFLHlCQUF5QixFQUFFLE1BQU0scURBQXFELENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFB1YmxpYyBBUEkgb2YgdGhlIGpheC1pbWFnZS12aXN1YWxpemF0aW9uIGxpYnJhcnkuIEV4dGVybmFsIGNvbnN1bWVycyBpbXBvcnRcbiAqIE9OTFkgZnJvbSBoZXJlIChgQGpheC1kYXRhLXNjaWVuY2Uvc2NpLWltYWdlLXZpc3VhbGl6ZXJgKTsgZXZlcnl0aGluZyBlbHNlIHVuZGVyIGBsaWIvYCBpc1xuICogaW50ZXJuYWwuIFRoZSBzdXJmYWNlIGlzIGNvbnRyYWN0cyArIHRva2VucyArIG5ldXRyYWwgbW9kZWxzICsgdGhlIEFuZ3VsYXJcbiAqIG1vZHVsZSwgcGx1cyB0aGUgcm91dGluZyBzZXJ2aWNlIHRoZSBob3N0J3MgY29tcG9zaXRpb24gcm9vdCBiaW5kcyB0aGUgdG9rZW5zXG4gKiB0byAoYHVzZUV4aXN0aW5nYCkuXG4gKi9cblxuLy8g4pSA4pSAIENvbnRyYWN0cyAmIERJIHRva2VucyDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIBcbmV4cG9ydCAqIGZyb20gJy4vbGliL2NvbnRyYWN0cy92aXN1YWxpemVyLmNvbnRyYWN0JztcbmV4cG9ydCAqIGZyb20gJy4vbGliL2NvbnRyYWN0cy9yZWdpb24tZWRpdG9yLWFwaS5jb250cmFjdCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvcG9ydHMvaW1hZ2Utc3RhdGUucG9ydCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvcG9ydHMvdGlsZS1hY2Nlc3MucG9ydCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvcG9ydHMvcmVnaW9uLWlvLnBvcnQnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvY29udHJhY3RzL3BvcnRzL3ByZWZlcmVuY2VzLnBvcnQnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvY29udHJhY3RzL2NoYW5uZWwtaGlzdG9ncmFtLWFwaS5jb250cmFjdCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvdml6LWNvbmZpZyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvaW1hZ2UuY29udHJhY3QnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvY29udHJhY3RzL3Bsb3QtdHlwZSc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvdG9vbGJhci1jb25maWcnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvY29udHJhY3RzL2NhcGFiaWxpdGllcy5jb250cmFjdCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvcmVnaW9uLW92ZXJsYXkuY29udHJhY3QnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvY29udHJhY3RzL2Rpc3BsYXktdHlwZXMnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvY29udHJhY3RzL3NhbS5jb250cmFjdCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9jb250cmFjdHMvY2VsbC1zZWdtZW50ZXIuY29udHJhY3QnO1xuZXhwb3J0IHsgQ2VsbHBvc2VTZWdtZW50ZXJTZXJ2aWNlIH0gZnJvbSAnLi9saWIvdG9vbGJhci9zZWdtZW50YXRpb24vY2VsbHBvc2Utc2VnbWVudGVyLnNlcnZpY2UnO1xuXG4vLyDilIDilIAgR2VuZXJpYyBjbGllbnQtc2lkZSBpbWFnZSB1dGlsaXRpZXMgKHNoYXJlZCB3aXRoIHRoZSBob3N0J3MgcGlwZWxpbmUpIOKUgOKUgFxuZXhwb3J0IHsgUHJvY2Vzc2luZ0ltYWdlIH0gZnJvbSAnLi9saWIvcHJvY2Vzc2luZy9wcm9jZXNzaW5nLWltYWdlJztcbmV4cG9ydCB7IGNyb3BJbWFnZSwgQ3JvcEltYWdlT3B0aW9ucyB9IGZyb20gJy4vbGliL3Byb2Nlc3NpbmcvaW1hZ2UtY3JvcCc7XG5leHBvcnQgeyBJbWFnZUNvbnZlcnRlclNlcnZpY2UgfSBmcm9tICcuL2xpYi9wcm9jZXNzaW5nL2ltYWdlLWNvbnZlcnRlci5zZXJ2aWNlJztcblxuLy8g4pSA4pSAIFNBTSBtb2RlbCByZWdpc3RyeSAoaG9zdCBjb25maWd1cmVzIGhvc3RlZCBPTk5YIFVSTHMgb25jZSBhdmFpbGFibGUpIOKUgOKUgFxuZXhwb3J0IHtcbiAgU0FNX01PREVMUywgREVGQVVMVF9TQU1fTU9ERUxfSUQsIGdldFNhbU1vZGVsLCBpc1NhbU1vZGVsUmVhZHksIHNldFNhbU1vZGVsVXJscyxcbiAgc2V0RGVmYXVsdFNhbU1vZGVsLCBnZXREZWZhdWx0U2FtTW9kZWxJZCxcbn0gZnJvbSAnLi9saWIvdG9vbGJhci9zZWdtZW50YXRpb24vc2FtLW1vZGVsLXJlZ2lzdHJ5JztcblxuLy8g4pSA4pSAIG9ubnhydW50aW1lLXdlYiBXQVNNIGxvY2F0aW9uIChob3N0IG92ZXJyaWRlcyBvbmNlLCBhdCBhcHAgaW5pdCkg4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG5leHBvcnQgeyBzZXRPcnRXYXNtQmFzZSwgZ2V0T3J0V2FzbUJhc2UgfSBmcm9tICcuL2xpYi90b29sYmFyL3NlZ21lbnRhdGlvbi9vcnQtcnVudGltZS1jb25maWcnO1xuXG4vLyDilIDilIAgTmV1dHJhbCBkYXRhIG1vZGVscyDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIBcbmV4cG9ydCAqIGZyb20gJy4vbGliL21vZGVscy9yZWdpb24nO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvbW9kZWxzL2NsYXNzLXByZXNldCc7XG5leHBvcnQgeyBTaGFwZVNlbGVjdGlvbiB9IGZyb20gJy4vbGliL21vZGVscy9zaGFwZSc7XG5cbi8vIOKUgOKUgCBBbmd1bGFyIG1vZHVsZSArIGNvbXBvc2l0aW9uLXJvb3Qgc2VydmljZSDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIBcbmV4cG9ydCB7IFZpc3VhbGl6YXRpb25Nb2R1bGUgfSBmcm9tICcuL2xpYi92aXN1YWxpemF0aW9uLm1vZHVsZSc7XG5leHBvcnQgeyBSb3V0aW5nVmlzdWFsaXplclNlcnZpY2UgfSBmcm9tICcuL2xpYi9yb3V0aW5nLXZpc3VhbGl6ZXIuc2VydmljZSc7XG4vLyBQcm92aWRlciBmYWN0b3J5IGZvciBhbiBpc29sYXRlZCwgY29tcG9uZW50LXNjb3BlZCB2aWV3ZXIgaW5zdGFuY2UgKGUuZy4gYVxuLy8gbW9kYWwgdGhhdCBtdXN0IG5vdCBzaGFyZSB0aGUgbWFpbiB2aWV3ZXIncyByZWdpb24vaW1hZ2Ugc3RhdGUpLlxuZXhwb3J0IHsgcHJvdmlkZVZpc3VhbGl6YXRpb24gfSBmcm9tICcuL2xpYi9wcm92aWRlLXZpc3VhbGl6YXRpb24nO1xuXG4vLyDilIDilIAgUHVibGljIGNvbXBvbmVudHMgKGV4cG9ydGVkIGJ5IFZpc3VhbGl6YXRpb25Nb2R1bGUpIOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgFxuLy8gbmctcGFja2FnciByZXF1aXJlcyBtb2R1bGUtZXhwb3J0ZWQgY29tcG9uZW50cyB0byBiZSByZWFjaGFibGUgZnJvbSB0aGVcbi8vIGVudHJ5IHBvaW50IHNvIGNvbnN1bWVycyBnZXQgdGhlaXIgdHlwZXM7IHRoZXNlIGFyZSB0aGUgZW1iZWRkYWJsZSBlbGVtZW50c1xuLy8gKGA8dmlzdWFsaXplcj5gLCBgPHJlZ2lvbi1lZGl0b3I+YCwgYDxoZXgtY29sb3ItcGlja2VyPmApLlxuZXhwb3J0IHsgVmlzdWFsaXplckNvbXBvbmVudCB9IGZyb20gJy4vbGliL3Zpc3VhbGl6ZXIuY29tcG9uZW50JztcbmV4cG9ydCB7IFJlZ2lvbkVkaXRvckNvbXBvbmVudCB9IGZyb20gJy4vbGliL3JlZ2lvbi1lZGl0b3IvcmVnaW9uLWVkaXRvci5jb21wb25lbnQnO1xuZXhwb3J0IHsgSGV4Q29sb3JQaWNrZXJDb21wb25lbnQgfSBmcm9tICcuL2xpYi9oZXgtY29sb3ItcGlja2VyL2hleC1jb2xvci1waWNrZXIuY29tcG9uZW50JztcbmV4cG9ydCB7IENoYW5uZWxIaXN0b2dyYW1Db21wb25lbnQgfSBmcm9tICcuL2xpYi9jaGFubmVsLWhpc3RvZ3JhbS9jaGFubmVsLWhpc3RvZ3JhbS5jb21wb25lbnQnO1xuIl19

package/esm2022/jax-data-science-sci-image-visualizer.mjs

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+export * from './index';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiamF4LWRhdGEtc2NpZW5jZS1zY2ktaW1hZ2UtdmlzdWFsaXplci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9qYXgtZGF0YS1zY2llbmNlLXNjaS1pbWFnZS12aXN1YWxpemVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBRUgsY0FBYyxTQUFTLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIEdlbmVyYXRlZCBidW5kbGUgaW5kZXguIERvIG5vdCBlZGl0LlxuICovXG5cbmV4cG9ydCAqIGZyb20gJy4vaW5kZXgnO1xuIl19