@jax-data-science/sci-image-visualizer 0.8.3 → 0.10.0

package/lib/contracts/section-view.contract.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The sections shown beside a split volume view: the planes x = const and y = const through the
+ * stack, each as an image cut from the volume with the regions' outlines cut by the same plane.
+ *
+ * Section coordinates `(u, v)` (see `geometry/section`): through x, u is the slice (slice k spans
+ * [k, k + 1)) and v the image y; through y, u is the image x and v the slice.
+ */
+export type SectionAxis = 'x' | 'y';
+/** A class's outlines in a section, as interleaved `u, v`. */
+export interface SectionRegions {
+    label: string;
+    /** `#rrggbb`. */
+    color: string;
+    /** Closed outlines, holes included (even-odd). */
+    rings: Float64Array[];
+    /** Open lines (a layer boundary across the slices); one point where it crosses one slice only. */
+    lines: Float64Array[];
+}
+export interface SectionView {
+    axis: SectionAxis;
+    /** Where the plane is: image x (through x) or y (through y), px. */
+    at: number;
+    /** The section's image, RGBA row by row, spanning [0, size[0]] × [0, size[1]]. */
+    image: {
+        width: number;
+        height: number;
+        data: Uint8ClampedArray;
+    };
+    /** Section units across (u) and down (v). */
+    size: [number, number];
+    /** The volume's world units per section unit across and down: draws it in its proportions. */
+    scale: [number, number];
+    regions: SectionRegions[];
+    /** The other two planes, across (a u) and down (a v); null where there is none. */
+    crosshair: {
+        u: number | null;
+        v: number | null;
+    };
+}
+/** Both sections; null until the split volume view has a volume to cut. */
+export interface SectionViews {
+    x: SectionView | null;
+    y: SectionView | null;
+}

package/lib/contracts/semantic-segmenter.contract.d.ts

@@ -25,6 +25,10 @@ export interface SemanticRegion {
     /** Area in pixels, holes already subtracted. */
     area: number;
 }
+/**
+ * The result of one {@link ISemanticSegmenter} run: the class layers found, in the pixel
+ * frame of the `width × height` image that was segmented.
+ */
 export interface SemanticSegmentation {
     regions: SemanticRegion[];
     /** Total pixels assigned to each class, indexed by class id. */
@@ -43,6 +47,7 @@ export interface SemanticSegmentation {
      */
     unassignedFraction: number;
 }
+/** Options for one {@link ISemanticSegmenter} run. */
 export interface SemanticSegmentOptions {
     /** Which registered model to run. Defaults to the registry's default. */
     modelId?: string;
@@ -90,6 +95,7 @@ export interface SemanticSegmentProgress {
     /** Human-readable phase, e.g. 'Segmenting patch 3/8…'. */
     onStatus?: (status: string) => void;
 }
+/** A segmenter that assigns every pixel a class and returns the class regions. */
 export interface ISemanticSegmenter {
     /** Assign every pixel a class and return the resulting regions. */
     segmentSemantic(image: {

package/lib/contracts/spatial-dataset.contract.d.ts

@@ -99,6 +99,7 @@ export interface ContinuousColumnMeta extends SpatialColumnMetaBase {
     min?: number;
     max?: number;
 }
+/** Descriptor of one per-observation column, discriminated by `kind`. */
 export type SpatialColumnMeta = CategoricalColumnMeta | ContinuousColumnMeta;
 /**
  * Code meaning "this observation has no category" (unassigned / filtered out /
@@ -120,8 +121,11 @@ export interface ContinuousColumn {
     /** Length = {@link SpatialObservations.count}. */
     values: Float32Array;
 }
+/** A loaded column with its values, discriminated by `meta.kind`. */
 export type SpatialColumn = CategoricalColumn | ContinuousColumn;
+/** Narrow a loaded column to a categorical one. */
 export declare function isCategoricalColumn(c: SpatialColumn): c is CategoricalColumn;
+/** Narrow a loaded column to a continuous one. */
 export declare function isContinuousColumn(c: SpatialColumn): c is ContinuousColumn;
 /**
  * The feature (gene) matrix, described but never delivered whole. Vectors come
@@ -182,11 +186,6 @@ export interface SpatialImageRef {
     mppX?: number;
     mppY?: number;
 }
-/**
- * A spatial-omics dataset: everything cheap enough to hold resident. Column and
- * feature *values*, and polygon *geometry*, are fetched through
- * {@link SpatialDataPort} as they are displayed.
- */
 /**
  * A precomputed low-dimensional embedding over the SAME observations — UMAP, t-SNE, PCA.
  *
@@ -370,7 +369,6 @@ export interface SpatialTranscriptTile {
     /** Index into the `genes` list the tile was requested with. */
     gene: Uint16Array;
 }
-/** Transcript totals for an estimate of how many markers a selection would draw. */
 /** The per-gene levels: each level's bin and tile size, on the all-gene pyramid's grid. */
 export interface SpatialTranscriptGeneBinsMeta {
     origin: [number, number];
@@ -399,6 +397,7 @@ export interface SpatialMarkerGenes {
         }[];
     }[];
 }
+/** Transcript totals for an estimate of how many markers a selection would draw. */
 export interface SpatialTranscriptCounts {
     /** Total transcripts per requested gene, over the whole dataset. */
     counts: Record<string, number>;
@@ -413,6 +412,11 @@ export interface SpatialDensityRaster {
     genes: string[];
     values: Float32Array;
 }
+/**
+ * A spatial-omics dataset: everything cheap enough to hold resident. Column and
+ * feature *values*, and polygon *geometry*, are fetched through
+ * {@link SpatialDataPort} as they are displayed.
+ */
 export interface SpatialDataset {
     /** Stable id — the key the port's lazy accessors are scoped to. */
     id: string;
@@ -473,6 +477,15 @@ export interface SpatialVolumeMeta {
     /** World size of one voxel per axis, in the observations' units. */
     voxelSize: [number, number, number];
 }
+/**
+ * A selection over a dataset's N observations: `mask[i] === 1` when observation `i` is
+ * selected, and `count` the number selected. Pure data, so it lives with the dataset
+ * contract; the selection logic that builds one is in `spatial/spatial-selection.ts`.
+ */
+export interface SpatialSelectionMask {
+    mask: Uint8Array;
+    count: number;
+}
 /** Look a column's descriptor up by name. */
 export declare function findColumnMeta(dataset: SpatialDataset, name: string): SpatialColumnMeta | undefined;
 export {};

package/lib/contracts/toolbar-tool.contract.d.ts

@@ -88,6 +88,7 @@ export interface SelectParamSpec {
     }[];
     tooltip?: string;
 }
+/** One parameter a dialog tool asks for, discriminated by `type`. */
 export type ToolParamSpec = NumberParamSpec | BooleanParamSpec | SelectParamSpec;
 /** One selectable checkpoint. */
 export interface ToolModelOption {

package/lib/contracts/visualizer.contract.d.ts

@@ -1,15 +1,15 @@
 import { InjectionToken } from '@angular/core';
+import type { SectionAxis, SectionViews } from './section-view.contract';
 import { Observable } from 'rxjs';
 import { Image } from 'image-js';
 import { IImageInfo, IImageMetadata } from './image.contract';
-import { Region } from '../models/region';
+import { Polygon, Region } from '../models/region';
 import { PlotType, PlotTypeDescriptor } from './plot-type';
 import { ViewerCapabilities } from './capabilities.contract';
 import { IRegionOverlay } from './region-overlay.contract';
 import { IHistogram } from './channel-histogram-api.contract';
-import { ColormapNode, IWandOptions, IBrushOptions, SpatialViewState, SpatialColorBy } from './display-types';
-import { CategoricalColumnMeta, SpatialDataset, SpatialEmbedding, SpatialMarkerGenes, SpatialTranscriptCounts } from './spatial-dataset.contract';
-import { SpatialSelectionMask } from '../spatial/spatial-selection';
+import { CanvasToolOptions, ColormapNode, IWandOptions, IBrushOptions, SpatialViewState, SpatialColorBy } from './display-types';
+import { CategoricalColumnMeta, SpatialDataset, SpatialEmbedding, SpatialMarkerGenes, SpatialSelectionMask, SpatialTranscriptCounts } from './spatial-dataset.contract';
 import type { PlotModeViewport } from './plot-type-contribution.contract';
 /**
  * Backend-neutral visualization contract. Plotly is one implementation;
@@ -19,10 +19,6 @@ import type { PlotModeViewport } from './plot-type-contribution.contract';
  *
  * Split into role interfaces so a consumer can depend only on the slice it
  * uses, then composed into `IVisualizer`.
- *
- * Types are intentionally permissive (`any` where the current Plotly service
- * is untyped) so `PlotlyService` satisfies the contract without a typing
- * rewrite — tightening is a follow-up, not part of standing the interface up.
  */
 /** Pixel readback shape returned by `getDisplayedPixelData`. */
 export interface PixelData {
@@ -45,37 +41,51 @@ export interface IntensityProfile {
     /** Colour of the line ROI — the inset trace is drawn in the same colour. */
     color?: string;
 }
+/**
+ * What `IDataRenderer.load()` resolves to. Backend-specific beyond `filename`,
+ * which names the image the handle was loaded for: the host compares it with the
+ * image it asked for, to drop a handle a newer request has overtaken. Pass the
+ * handle on to `plot()` unchanged.
+ */
+export interface LoadedImage {
+    readonly filename: string | undefined;
+}
 /**
  * The render/viewport role: load data, render it (image or plot), and handle
  * zoom, stack navigation, and pixel readback.
  */
 export interface IDataRenderer {
-    load(imageInfo: IImageInfo, zIndex: number): Promise<any>;
-    /** `imageLoaded` is the backend-specific handle returned by `load()` —
-     *  treat it as opaque and pass it straight through. */
+    /** Fetch what {@link plot} needs for this image/slice. `signal` aborts when the
+     *  host no longer wants the result (a newer image, Cancel, teardown); a backend
+     *  may stop its network work then. Optional, and ignored by backends that do
+     *  not support it yet. */
+    load(imageInfo: IImageInfo, zIndex: number, signal?: AbortSignal): Promise<LoadedImage>;
+    /** `imageLoaded` is the {@link LoadedImage} handle returned by `load()` (or null
+     *  for a draw with no image) — pass it straight through. Resolves false when the
+     *  backend could not draw (no plot target, no WebGPU, …). */
     plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
     /** @deprecated Plotly-specific re-render; the OSD backend no-ops it. The host
      *  re-drives `plot()` from its image stream instead. */
     reloadAndPlot(): void;
     reset(): void;
     relayout(trueImageSize?: number[]): void;
-    /** @deprecated Plotly-specific (axis reset); the OSD backend no-ops it. Gate
-     *  on {@link ViewerCapabilities} before calling. */
+    /**
+     * Fit the whole image (or scene) into the view — every backend does: Plotly
+     * autoranges its axes, OpenSeadragon goes home, napari-js fits its camera. The
+     * backend then emits on {@link getAutoscaleEvent}.
+     */
+    fitToView(): void;
+    /** Reset the view to the image extent. Same intent as {@link fitToView}; kept for
+     *  callers of the original name. */
     resetAxes(): void;
-    /** @deprecated Plotly-specific (autoscale); the OSD backend no-ops it. Gate
-     *  on {@link ViewerCapabilities} before calling. */
+    /** @deprecated Use {@link fitToView} — the same operation under its backend-neutral name. */
     autoscale(): void;
     zoomIn(): void;
     zoomOut(): void;
     setDragMode(mode: string | false): void;
-    /** Show/hide the overview navigator (the minimap). OpenSeadragon only — Plotly
-     *  no-ops it (it has no navigator). Applied when the viewer is (re)created, and
-     *  toggled live when one is already mounted. */
+    /** @deprecated Use `getOsdViewOptions().setNavigatorVisible()` on `IVisualizer`. */
     setNavigatorVisible(visible: boolean): void;
-    /** Image smoothing (bilinear interpolation). `false` = nearest-neighbour, so
-     *  zooming past 1:1 shows crisp pixel blocks (pixel-level inspection).
-     *  OpenSeadragon only — Plotly no-ops it. Applied at viewer creation and live
-     *  (with a redraw) when one is mounted. */
+    /** @deprecated Use `getOsdViewOptions().setImageSmoothingEnabled()` on `IVisualizer`. */
     setImageSmoothingEnabled(enabled: boolean): void;
     setShowStack(showstack: boolean): void;
     setZIndex(zIndex: number): void;
@@ -113,17 +123,17 @@ export interface IDataRenderer {
     } | null;
     downloadImage(): void;
     setPlotType(plotType: PlotType): void;
-    /** Set the napari 3D decimate factor (1 = full … 8 = ⅛). Optional — only the napari-js WebGPU
-     *  backend honors it; changing it re-loads the current 3D plot at the coarser/finer sampling. */
+    /** @deprecated Use `getVolumeResolution()?.set()` on `IVisualizer`. */
     setResolutionScale?(scale: number): void;
-    /** The current napari 3D decimate factor (to initialize the Resolution control). Optional. */
+    /** @deprecated Use `getVolumeResolution()?.get()` on `IVisualizer` (this returns 1 without one). */
     getResolutionScale?(): number;
-    /** @deprecated Use `getSurface3dControls()` — 3D scene controls only exist on
-     *  a backend that renders 3D plot types; this method silently no-ops on OSD. */
+    /** @deprecated Use `getSurface3dControls()?.setSurfaceDragMode()` — 3D scene controls
+     *  only exist on a backend that renders 3D plot types; this silently no-ops on OSD. */
     setSurfaceDragMode(mode: string): void;
     /** @deprecated Use `getSurface3dControls()` — see {@link setSurfaceDragMode}. */
     resetSurfaceCamera(): void;
-    getAutoscaleEvent(): Observable<any>;
+    /** Emits whenever the backend fits the view ({@link fitToView}). */
+    getAutoscaleEvent(): Observable<unknown>;
     /** Plot types this backend advertises (drives the UI selector). */
     getPlotTypeDescriptors(): PlotTypeDescriptor[];
     /** Intensity along the line ROIs; emits the full set as any line is added,
@@ -139,8 +149,10 @@ export interface IRegionStore {
     setRegions(regions: Region[], showRegionLabel?: boolean, isRegionSaveOn?: boolean, fillColor?: string, append?: boolean): void;
     /** Framework-neutral accessor — the canonical way to read current regions. */
     getRegions(): Region[];
-    getRegionPolygons(): any[];
-    getRegionUpdateEvent(): Observable<any[]>;
+    /** The current regions as polygons (rectangles expanded), for server requests. */
+    getRegionPolygons(): Polygon[];
+    /** Emits the region set whenever it changes. */
+    getRegionUpdateEvent(): Observable<Region[]>;
     setSelectedShapeIndices(indices: number[]): void;
     getSelectedShapeIndices$(): Observable<number[]>;
     /** Select a specific region (by identity), highlighting it on whichever
@@ -153,9 +165,6 @@ export interface IRegionStore {
     getFillColor(): string;
     getClassificationColors(): Map<string, string>;
     setClassificationColor(label: string, color: string): void;
-    plotPreviousShapes(): void;
-    setPreviousShapes(shapes: any[]): void;
-    getPreviousShapes(): any[];
     /** Undo the most recent region action (jit-ui#85). Restores the region set to
      *  the state before that action; up to a small fixed depth (10) is retained,
      *  so it can be invoked up to 10 times in a row. No-op when nothing is left to
@@ -203,16 +212,29 @@ export interface IRegionStore {
      *  Keyed by zero-based slice index; regions tagged with their z. */
     getStackSaveSlices(): Map<number, Region[]>;
 }
-/** On-canvas tool modes (wand, brush, vertex eraser, zoom-to-box). */
+/** On-canvas tool modes (wand, brush, vertex eraser, zoom-to-box, SAM point). */
 export interface IToolController {
+    /**
+     * Arm one on-canvas tool (`CanvasToolId`) with its options — the wand's
+     * {@link IWandOptions}, the brush's {@link IBrushOptions} (`size` is the
+     * matrix-pixel diameter of the painted disc), the eraser's `{ radius }` —
+     * and disarm the one that was armed. `null`, or any id that is not a canvas
+     * tool (a region draw mode such as `'drawrect'`, `'pan'`), disarms only.
+     * Arming the armed tool again applies the options and keeps its work in
+     * progress.
+     */
+    setActiveTool(id: string | null, options?: CanvasToolOptions): void;
+    /** @deprecated Use `setActiveTool('wand', options)` / `setActiveTool(null)`. */
     setWandMode(active: boolean, options?: IWandOptions): void;
     setWandOptions(options: IWandOptions): void;
     clearActiveWandRegion(): void;
-    /** Brush region tool. `size` (matrix-pixel diameter) sizes the painted disc. */
+    /** @deprecated Use `setActiveTool('brush', options)` / `setActiveTool(null)`. */
     setBrushMode(active: boolean, options?: IBrushOptions): void;
     setBrushOptions(options: IBrushOptions): void;
+    /** @deprecated Use `setActiveTool('eraseVertex', { radius })` / `setActiveTool(null)`. */
     setVertexEraserMode(active: boolean): void;
     setVertexEraserRadius(radius: number): void;
+    /** @deprecated Use `setActiveTool('zoomToBox')` / `setActiveTool(null)`. */
     setZoomToBoxMode(active: boolean): void;
     /** Box-prompted SAM segmentation: segment every rectangle region into masks.
      *  Returns the number of mask regions added. (jit-ui#90) */
@@ -222,7 +244,8 @@ export interface IToolController {
     segmentRectanglesCellpose(): Promise<number>;
     /** Choose the registered SAM model the segment tools use (jit-ui#90 P1). */
     setSamModel(id: string): void;
-    /** Toggle the interactive SAM point-prompt tool (click = +point, Shift = -). */
+    /** Toggle the interactive SAM point-prompt tool (click = +point, Shift = -).
+     *  @deprecated Use `setActiveTool('samPoint')` / `setActiveTool(null)`. */
     setSamPointMode(active: boolean): void;
     /** Finalise / discard the in-progress SAM point object. */
     commitSamPoints(): void;
@@ -398,28 +421,19 @@ export interface IDisplayOptions {
     setColormap(colormap: ColormapNode): void;
     getColormapOptions(): ColormapNode[];
     getReverseScale(): Observable<boolean>;
-    setReverseScale(reverscale: any): void;
-    setImageMeta(imageMeta: IImageMetadata[]): void;
+    setReverseScale(reverse: boolean): void;
+    /** Publish the current image's metadata. `imageKey` (its file name) lets the
+     *  channel state survive a re-plot of the same image but not a switch to another. */
+    setImageMeta(imageMeta: IImageMetadata[], imageKey?: string): void;
     getImageMeta(): Observable<IImageMetadata[]>;
 }
 /**
- * Intensity-profile sampling (PlotType.LINE). The sampling *source* lives in the
- * Plotly backend (it owns pixel readback); OpenSeadragon contributes only the
- * viewport-change signal that drives re-sampling at the current zoom. Each
- * backend implements the part it owns and no-ops the rest — mirroring the
- * deprecated no-op pattern on {@link IDataRenderer} — so the contract is uniform
- * and a consumer can depend on `IVisualizer` alone (no concrete-type reach-in).
+ * The part of intensity sampling a rendering backend owns: where its view settled.
+ * What `IViewerBackend.getIntensitySampling()` returns.
  */
-export interface IIntensitySampling {
-    /** Populate the intensity-sampling cache for the current image/slice so the
-     *  line-ROI profiles have pixel data. Real on Plotly; no-op on OSD. */
-    ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
-    /** Re-sample the profiles from a fresh crop of the given image-pixel ROI at
-     *  display resolution. Real on Plotly; no-op on OSD. */
-    refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
+export interface IIntensityViewportSource {
     /** Visible-region changes (image-pixel coords), emitted when the view settles,
-     *  so the inset can re-sample at the current zoom. Real on OSD; empty on Plotly
-     *  (its high-def zoom updates the sampling cache inline instead). */
+     *  so the inset can re-sample at the current zoom. */
     getViewportChange$(): Observable<{
         x: number;
         y: number;
@@ -427,12 +441,65 @@ export interface IIntensitySampling {
         height: number;
     }>;
 }
-/** Composite contract a visualization backend implements. */
+/**
+ * Intensity-profile sampling (the line ROIs' inset), from `IVisualizer.getIntensitySampling()`.
+ * The sampling itself is backend-neutral (the library's IntensityProfileService
+ * samples whatever image is on screen); the viewport-change signal comes from the
+ * backend that draws the image (OpenSeadragon and napari-js report it; Plotly
+ * re-samples its high-def zoom crops inline instead).
+ */
+export interface IIntensitySampling extends IIntensityViewportSource {
+    /** Load the current image/slice's pixels so the line-ROI profiles have data
+     *  (a backend with no frames of its own: OpenSeadragon, napari-js). */
+    ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
+    /** Re-sample the profiles from a fresh crop of the given image-pixel ROI at
+     *  display resolution. */
+    refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
+}
+/**
+ * The 2D view options of a tiled image viewer: the overview navigator and image
+ * smoothing. OpenSeadragon's, mirrored by napari-js's 2D views; Plotly has neither.
+ * Capability-gated: `IViewerBackend.getOsdViewOptions()` is null on a backend
+ * without them.
+ */
+export interface IOsdViewOptions {
+    /** Show/hide the overview navigator (the minimap). Applied when the viewer is
+     *  (re)created, and toggled live when one is already mounted. */
+    setNavigatorVisible(visible: boolean): void;
+    /** Image smoothing (bilinear interpolation). `false` = nearest-neighbour, so
+     *  zooming past 1:1 shows crisp pixel blocks (pixel-level inspection). Applied
+     *  at viewer creation and live (with a redraw) when one is mounted. */
+    setImageSmoothingEnabled(enabled: boolean): void;
+}
+/**
+ * The 3D decimate factor of a volume renderer (napari-js WebGPU): 1 = full
+ * resolution … 8 = ⅛ per axis. Capability-gated: null on a backend without one.
+ */
+export interface IVolumeResolution {
+    /** The current factor (to initialize the Resolution control). */
+    get(): number;
+    /** Set the factor (rounded, at least 1). Takes effect on the next (re)load —
+     *  the host re-plots after calling it, since it changes the fetched data. */
+    set(scale: number): void;
+}
+/**
+ * The host-facing composite contract, implemented by the router (`VISUALIZER`). A
+ * rendering backend implements {@link IViewerBackend} instead.
+ */
 export interface IVisualizer extends IDataRenderer, IRegionStore, IToolController, IDisplayOptions, IIntensitySampling {
     readonly capabilities: ViewerCapabilities;
     /** This backend's region renderer. May be null until a plot is mounted
      *  (OpenSeadragon). Drives region draw/select modes uniformly. */
     getRegionOverlay(): IRegionOverlay | null;
+    /** Split a volume view: the displayed slice, with every region tool, in the div `div` beside
+     *  the 3D view; null closes it. Resolves whether the slice shows. Optional: the router's. */
+    setSliceEditor?(div: string | null): Promise<boolean>;
+    /** The slice editor's sections through x and y (nulls while it is closed). Optional: the router's. */
+    getSectionViews$?(): Observable<SectionViews>;
+    /** Move the slice editor's section plane through `axis` to `at` (image px). */
+    setSectionPlane?(axis: SectionAxis, at: number): void;
+    /** The slice picked by dragging the z plane in the volume (the host shows it). */
+    getSliceDrag$?(): Observable<number>;
     /** Isosurface controls when this backend advertises `ViewerFeature.Isosurface`,
      *  else null — so consumers gate on the returned object, not a no-op method. */
     getIsosurfaceControls(): IIsosurfaceControls | null;
@@ -443,6 +510,26 @@ export interface IVisualizer extends IDataRenderer, IRegionStore, IToolControlle
      *  the capability-gated replacement for the deprecated top-level
      *  `setSurfaceDragMode`/`resetSurfaceCamera`. */
     getSurface3dControls(): ISurface3dControls | null;
+    /** The navigator / image-smoothing options. Never null on the router: a setting
+     *  applies to every backend that has them (OpenSeadragon, napari-js), so it can
+     *  be set before the first render and survives a backend switch. */
+    getOsdViewOptions(): IOsdViewOptions;
+    /** The 3D decimate factor of the backend on screen, or null when it has none
+     *  (only napari-js renders volumes). */
+    getVolumeResolution(): IVolumeResolution | null;
+    /** Intensity-profile sampling, whichever backend is on screen. */
+    getIntensitySampling(): IIntensitySampling;
+    /** @deprecated Use `getIntensitySampling().ensureIntensitySampling()`. */
+    ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
+    /** @deprecated Use `getIntensitySampling().refreshIntensitySamplingForRoi()`. */
+    refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
+    /** @deprecated Use `getIntensitySampling().getViewportChange$()`. */
+    getViewportChange$(): Observable<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
     /** Spatial-omics controls when a `SPATIAL_DATA_PORT` is bound, else null.
      *  Optional: only the routing service implements it, since the state is shared
      *  rather than owned by any one backend. */
@@ -464,8 +551,98 @@ export interface IVisualizer extends IDataRenderer, IRegionStore, IToolControlle
     /** Export the underlying image data as a data-preserving multi-band TIFF
      *  (native bit depth). No-op on backends that can't provide it. */
     exportData(): void;
+    /**
+     * The view is going away (the `<visualizer>` is destroyed): drop what is bound to
+     * it — the on-screen viewer, its render loop and view subscriptions — so nothing
+     * outlives the view. Service-lifetime state (stores, the backends' own store
+     * subscriptions) is untouched, so a later view on the same chain renders normally.
+     */
+    detach(): void;
+    /** @deprecated Use {@link detach}, which this delegates to. */
     unsubscribe(): void;
 }
+/**
+ * What a rendering backend implements (Plotly, OpenSeadragon, napari-js): rendering,
+ * the viewport, pixel readback, export, loading state and its on-canvas tools, plus
+ * capability-gated getters for what only some backends have.
+ *
+ * It is the backend-facing half of {@link IVisualizer}. Region and display state are
+ * not here: they live in the shared `RegionStore` / `VisualizerStore`, which the router
+ * serves to hosts directly; a backend draws them by subscribing to the stores' events.
+ * Hosts keep depending on `IVisualizer` (the router's composite), never on a backend.
+ */
+export interface IViewerBackend extends IToolController {
+    readonly capabilities: ViewerCapabilities;
+    load(imageInfo: IImageInfo, zIndex: number, signal?: AbortSignal): Promise<LoadedImage>;
+    plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
+    reset(): void;
+    relayout(trueImageSize?: number[]): void;
+    /** The view is going away: release what is bound to it. */
+    detach(): void;
+    /** Stop streaming frames (volume assembly / surface preload). Optional: only
+     *  backends that stream a z-stack do work here. */
+    cancelLoading?(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setDragMode(mode: string | false): void;
+    fitToView(): void;
+    /** @see IDataRenderer.resetAxes */
+    resetAxes(): void;
+    setZIndex(zIndex: number): void;
+    setShowStack(showstack: boolean): void;
+    /** Emits whenever the backend fits the view. */
+    getAutoscaleEvent(): Observable<unknown>;
+    isStackLoading(): Observable<boolean>;
+    getStackLoadingProgress(): Observable<number>;
+    getTrueImageSize(): {
+        width: number;
+        height: number;
+    } | null;
+    getCurrentImage(): Promise<Image | null>;
+    getDisplayedPixelData(): PixelData | null;
+    getDisplayedSourceRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    getHistogram(channelIndex: number, bins: number): IHistogram | null;
+    getHistogram$(channelIndex: number, bins: number): Observable<IHistogram | null>;
+    downloadImage(): void;
+    exportComposite(): void;
+    exportData(): void;
+    getRegionOverlay(): IRegionOverlay | null;
+    getIsosurfaceControls(): IIsosurfaceControls | null;
+    getSurface3dControls(): ISurface3dControls | null;
+    getIntensityControls(): IIntensityControls | null;
+    getPlotModeViewport?(): PlotModeViewport | null;
+    /** Navigator / image smoothing, or null when the backend has neither (Plotly). */
+    getOsdViewOptions(): IOsdViewOptions | null;
+    /** The 3D decimate factor, or null when the backend renders no volumes. */
+    getVolumeResolution(): IVolumeResolution | null;
+    /** Where the view settled, for the intensity inset's re-sampling; null when the
+     *  backend re-samples on its own (Plotly's high-def zoom). The sampling itself is
+     *  the router's (IntensityProfileService). */
+    getIntensitySampling(): IIntensityViewportSource | null;
+}
+/**
+ * What a mounted `<visualizer>` hands its host through
+ * `ImageStatePort.setDiagram()` — a small, typed surface rather than the component
+ * itself, whose every public member would otherwise be de-facto API. Cleared
+ * (`setDiagram(null)`) when the visualizer is destroyed. Hosts that can inject
+ * {@link VISUALIZER} / `REGION_EDITOR_API` directly need not use it at all.
+ */
+export interface VisualizerHandle {
+    /** The visualizer chain this `<visualizer>` renders through. */
+    readonly visualizer: IVisualizer;
+    /** @deprecated Use {@link visualizer}. Kept for hosts that read the component's
+     *  former `plotService` field off the registered object. */
+    readonly plotService: IVisualizer;
+    /** Whether any region (annotation or intensity line) exists on the current image. */
+    hasRegions(): boolean;
+    /** The current regions as polygons, for a server request (crop / processing). */
+    getRegionPolygons(): Polygon[];
+}
 /**
  * DI token for the active visualization backend. Bind it (`useExisting`) to the
  * `RoutingVisualizerService`, which selects Plotly vs OpenSeadragon per plot

package/lib/contracts/viz-config.d.ts

@@ -21,5 +21,14 @@ export interface VizConfig {
      * are unaffected.
      */
     useNapariRenderer?: boolean;
+    /**
+     * An image's ROI GeoJSON (`roiJsonStr`, or a slice's `roiJsonStrs[z]`) at least this many
+     * characters long loads as a tiled region source rather than as regions: drawn from the tiles
+     * in view at the zoom's level of detail (OpenSeadragon and napari; Plotly does not draw it),
+     * each feature joining the regions when it is selected or edited. Default 1 000 000; 0 makes
+     * every ROI file a source, `Infinity` none.
+     */
+    regionSourceMinChars?: number;
 }
+/** DI token for the host's {@link VizConfig}. Required by the router. */
 export declare const VIZ_CONFIG: InjectionToken<VizConfig>;

package/lib/geometry/contour.d.ts

@@ -0,0 +1,24 @@
+import { Polygon } from '../models/region';
+/**
+ * Trace EVERY 4-connected blob in `mask` (sized w*h) whose area is at least
+ * `minSize` pixels, returning one Polygon per blob translated via
+ * (originX, originY), ordered largest-first (ties in raster order). A blob's
+ * interior rings enclosing at least `minHoleSize` pixels become its
+ * {@link Polygon.holes}. An erase that cuts a region in two therefore yields
+ * both pieces, and a donut keeps its hole.
+ *
+ * The mask is labelled once and each blob traced inside its own bounding box
+ * (RT-16), so the cost is O(w·h + Σ bbox areas).
+ */
+export declare function maskToPolygons(mask: Uint8Array, w: number, h: number, originX: number, originY: number, minSize?: number, minHoleSize?: number): Polygon[];
+/**
+ * Trace each instance in an integer label map (0 = background) into polygons —
+ * used to turn a cellpose-style segmentation into region outlines. Pieces with
+ * area below `minSize` are skipped (and holes below it dropped); a label made of
+ * several blobs yields one polygon per blob. Ordered by label, then largest
+ * piece first. Coords are translated via originX/originY (not clamped).
+ *
+ * One labelling pass finds every label's pieces; each is traced inside its own
+ * bounding box (RT-16), instead of rescanning the whole map per label.
+ */
+export declare function labelsToPolygons(labels: Uint32Array, w: number, h: number, originX: number, originY: number, minSize?: number): Polygon[];

package/lib/geometry/loft.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The sheet through open polylines traced on a stack of slices (a retinal layer boundary on each
+ * B-scan, say): each line joined to its counterpart on the next slice that has lines by a strip of
+ * triangles. Slices without lines in between are bridged straight across.
+ *
+ * Pure: usable from workers.
+ */
+import type { Mesh } from 'napari-js/geometry';
+/** A class's open polylines on one slice: interleaved `x, y` image pixels. */
+export interface SliceLines {
+    z: number;
+    lines: readonly ArrayLike<number>[];
+}
+/**
+ * The sheet through `slices`' lines, in image pixels (x, y) and slice indices (z: slice k's line at
+ * z = k). Every line is resampled at the same number of points, evenly along its length (about one
+ * per `step` px of the longest), so a line shared by the strips above and below it is one row of
+ * vertices. Lines are matched between neighbouring slices closest first, each at most once, and only
+ * when their boxes overlap; a line without a match ends the sheet there. Empty without two slices
+ * with lines.
+ */
+export declare function loftLines(slices: readonly SliceLines[], step?: number): Mesh;

package/lib/geometry/polylabel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where to put a label inside a polygon: its pole of inaccessibility, the inside point farthest
+ * from every edge (Garcia-Castellanos & Lombardo's grid search, as in Mapbox's polylabel). Unlike
+ * the centroid it is always inside, also for a U-shaped or ring-shaped region.
+ *
+ * Pure: usable from workers.
+ */
+/** A polygon as interleaved `x, y` rings: the exterior first, then its holes. */
+export type FlatRings = readonly ArrayLike<number>[];
+/** The pole of inaccessibility `[x, y]` and its distance to the nearest edge. */
+export interface LabelPoint {
+    x: number;
+    y: number;
+    /** Distance from the point to the nearest edge: how much room a label has around it. */
+    distance: number;
+}
+/**
+ * The pole of inaccessibility of `rings`, to within `precision` (default: 1/100 of the shorter
+ * side of the exterior's box, at least 0.5). Null for an exterior with fewer than three vertices.
+ */
+export declare function polylabel(rings: FlatRings, precision?: number): LabelPoint | null;
+/** Distance from (x, y) to the nearest edge of `rings`, positive inside (even-odd), negative outside. */
+export declare function signedDistance(x: number, y: number, rings: FlatRings): number;