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

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

@@ -2,14 +2,13 @@ import { InjectionToken } from '@angular/core';
 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 +18,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 +40,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 +122,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 +148,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 +164,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 +211,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 +243,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 +420,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,7 +440,51 @@ 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
@@ -443,6 +500,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 +541,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

@@ -22,4 +22,5 @@ export interface VizConfig {
      */
     useNapariRenderer?: boolean;
 }
+/** 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/raster.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure binary-mask helpers: polygon rasterization (napari-js's `rasterizePolygon`)
+ * and bbox-relative mask set operations. No DOM, no Angular — the mask-export
+ * worker imports this.
+ */
+/** A bbox-relative binary mask (1 = filled, 0 = empty) whose pixel (0,0) sits
+ *  at (bx, by) in the frame it was rasterized in. */
+export interface BBoxMask {
+    bx: number;
+    by: number;
+    bw: number;
+    bh: number;
+    mask: Uint8Array;
+}
+/**
+ * The largest bbox (in pixels) {@link rasterizePolygon} allocates before it
+ * falls back to clipping at the window. Also the cap the wand/brush use to
+ * decide whether a region can be edited at the current zoom.
+ */
+export declare const MAX_RASTER_PIXELS: number;
+/**
+ * Rasterize a closed polygon (minus its holes) into a bbox-relative mask, e.g.
+ * as the starting point for a wand/brush stroke accumulator.
+ *
+ * Pixel (px, py) covers `[px, px + 1) × [py, py + 1)` and is set when its centre
+ * is inside — the rule under which the pixel-edge outlines `geometry/contour`
+ * traces come back as exactly the pixels they were traced from.
+ *
+ * Returns the bbox origin plus the filled mask, or null if the polygon is
+ * degenerate (covers no pixel centre). The polygon's full extent is kept even
+ * where it is negative or exceeds `imageWidth`×`imageHeight` (jit-ui#102); only
+ * a bbox larger than {@link MAX_RASTER_PIXELS} is clipped to that window (rare:
+ * a region enormous at the current zoom; accepts the clip).
+ */
+export declare function rasterizePolygon(xpoints: number[], ypoints: number[], imageWidth: number, imageHeight: number, holes?: number[][][]): BBoxMask | null;
+/** Returns true if the two bbox-relative masks share at least one set pixel. */
+export declare function masksOverlap(a: BBoxMask, b: BBoxMask): boolean;
+/**
+ * Allocate a fresh accumulator covering both masks and OR them in. The
+ * resulting mask's bbox is the smallest rectangle containing both inputs.
+ */
+export declare function unionMasks(a: BBoxMask, b: BBoxMask): BBoxMask;

package/lib/geometry/ring.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure ring (closed polyline) helpers: bounds, containment, vertex dropping and
+ * simplification. No DOM, no Angular, no `this` — usable from workers.
+ *
+ * A ring is a pair of parallel `xs`/`ys` arrays without a repeated closing
+ * vertex; hole rings use the `[[x, y], …]` convention of {@link Polygon.holes}.
+ */
+/** Axis-aligned bounds of a ring. Infinite (min > max) for an empty ring. */
+export interface RingBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/** The axis-aligned bounds of a ring's vertices. */
+export declare function ringBounds(xs: ArrayLike<number>, ys: ArrayLike<number>): RingBounds;
+/**
+ * Standard ray-cast (even-odd) point-in-ring test. (px, py) and the ring
+ * vertices must be in the same coordinate system. Rings with fewer than three
+ * vertices contain nothing.
+ */
+export declare function pointInRing(px: number, py: number, xs: ArrayLike<number>, ys: ArrayLike<number>): boolean;
+/**
+ * Point-in-region test that honours interior rings (holes): inside the
+ * exterior AND outside every hole. Coordinates must share the polygon's frame.
+ * With no holes this is exactly {@link pointInRing}.
+ */
+export declare function pointInPolygonWithHoles(px: number, py: number, xs: ArrayLike<number>, ys: ArrayLike<number>, holes?: number[][][]): boolean;
+/** {@link pointInRing} over a `[[x, y], …]` ring (the hole convention), without splitting it. */
+export declare function pointInPairRing(px: number, py: number, ring: ReadonlyArray<ArrayLike<number>>): boolean;
+/**
+ * Drop every vertex whose Euclidean distance to (cx, cy) is less than
+ * `radius`. Returns trimmed parallel arrays plus how many vertices were
+ * removed (so the caller can detect a no-op tick and skip the relayout).
+ */
+export declare function dropVerticesWithinRadius(xpoints: number[], ypoints: number[], cx: number, cy: number, radius: number): {
+    xpoints: number[];
+    ypoints: number[];
+    removed: number;
+};
+/**
+ * Erase the part of a ring that lies within `radius` of (cx, cy): every vertex
+ * inside the disc goes (as {@link dropVerticesWithinRadius}), and the outline is
+ * rejoined where it crosses the disc's edge rather than at the next vertex left
+ * standing. On a densely sampled outline the two agree; on a sparse one (a
+ * traced box is four corners) dropping a corner would otherwise cut straight to
+ * the neighbouring corners. A `closed` ring wraps; an open one (a polyline) has
+ * no edge from its last vertex back to its first. Returns the trimmed parallel
+ * arrays plus how many of the ring's own vertices were removed (0: unchanged).
+ */
+export declare function eraseRingWithinRadius(xpoints: number[], ypoints: number[], cx: number, cy: number, radius: number, closed?: boolean): {
+    xpoints: number[];
+    ypoints: number[];
+    removed: number;
+};
+/**
+ * Simplify a closed ring with the Douglas–Peucker algorithm (jit-ui#85):
+ * drop every vertex that lies within `epsilon` pixels (the "altitude
+ * threshold") of the line between its kept neighbours. Anchored at vertex 0
+ * (the ring is closed by appending it). Rings of ≤ 3 vertices, or a
+ * non-positive epsilon, are returned unchanged. Output keeps the closed-ring
+ * convention (no repeated closing point).
+ */
+export declare function simplifyRing(xs: number[], ys: number[], epsilon: number): {
+    xs: number[];
+    ys: number[];
+};