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

package/lib/store/visualizer-store.service.d.ts

@@ -0,0 +1,123 @@
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { ClassPreset, PresetSet } from '../models/class-preset';
+import { PreferencesPort } from '../contracts/ports/preferences.port';
+import { IImageMetadata } from '../contracts/image.contract';
+import { IChannelState } from '../contracts/channel-histogram-api.contract';
+import * as i0 from "@angular/core";
+/**
+ * Backend-neutral store for the **visualization session** — the state that
+ * describes *how* the current image is being viewed, independent of which
+ * rendering backend (Plotly or OpenSeadragon) is on screen:
+ *
+ *  - the active colormap / LUT and its reverse-scale toggle,
+ *  - the current image's physical metadata (µm/pixel etc.),
+ *  - the classification label → colour map,
+ *  - which on-canvas tool is currently active.
+ *
+ * Both backends read and write this single instance, so they stay in lock-step
+ * regardless of which one is rendering. Previously this state lived inside
+ * `PlotlyService`, which forced the OpenSeadragon backend to depend on the
+ * Plotly service purely to read the shared colormap; this store removes that
+ * coupling — neither backend owns the session state.
+ *
+ * NOTE: region *geometry* (the drawn shapes / per-image region cache) still
+ * lives in `PlotlyService` for now; extracting it into a sibling region store
+ * is a separate follow-up.
+ */
+export declare class VisualizerStore {
+    private readonly http;
+    private readonly prefsPort;
+    private readonly colormap$;
+    private readonly reverseScale$;
+    private readonly imageMeta$;
+    private readonly channelStates$;
+    private defaultChannelStates;
+    private readonly grayscale$;
+    private readonly invert$;
+    private presetSet;
+    private readonly presetSet$;
+    private readonly savePresets$;
+    private presetsLoaded;
+    private readonly activeTool$;
+    constructor(http?: HttpClient | null, prefsPort?: PreferencesPort | null);
+    /**
+     * Resolve the colormap tree's LUT keys (e.g. "GREYS_LUT") to their colour
+     * arrays from a served JSON asset. The ~630 KB of LUT data lives outside the
+     * bundle (as `/assets/plotting/colormap-luts.json`) so it never enters the TS
+     * / webpack module graph — that data-in-source was the main driver of the
+     * build's >2 GB heap. Named Plotly scales (e.g. "Viridis") aren't keys in the
+     * JSON, so they're left untouched. The default LUT ("Greys Inv" → the Plotly
+     * "Greys" scale) needs no JSON, so the first render works before this resolves.
+     */
+    private loadColormapLuts;
+    private initPresetPersistence;
+    private normalizePresetSet;
+    /** Queue a debounced save. No-ops until the initial load resolves (and when no port is bound). */
+    private queuePresetSave;
+    /** Persist the current preset set immediately, bypassing the incremental-edit
+     *  debounce. Used for explicit bulk actions (Apply / Import / Reset). */
+    private savePresetsNow;
+    /** The available colormap options (tree for the LUT dropdown). */
+    getColormapOptions(): any;
+    getColormap(): Observable<any>;
+    /** Synchronous current value — for render paths that read it while building
+     *  a frame (e.g. Plotly's colorscale) rather than subscribing. */
+    currentColormap(): any;
+    setColormap(colormap: any): void;
+    getReverseScale(): Observable<boolean>;
+    currentReverseScale(): boolean;
+    setReverseScale(reverse: boolean): void;
+    getImageMeta(): Observable<IImageMetadata[]>;
+    /**
+     * Patch the physical pixel size (µm/pixel) onto the current image meta and
+     * re-emit, without touching the derived channels. The OSD tile descriptor
+     * (from the server's Bio-Formats `/tiles/info`) is authoritative for scaled
+     * images — `imageInfo.imageMeta` often carries no mpp — so the renderer feeds
+     * it here once the descriptor loads, letting area/scale consumers (the Region
+     * Editor) show µm²/mm² instead of px². No-op when neither axis is positive.
+     */
+    setPhysicalPixelSize(mppX?: number, mppY?: number): void;
+    setImageMeta(imageMeta: IImageMetadata[]): void;
+    /** Channels for an image:
+     *   - RGB (rgbChannels ≥ 3) → Red/Green/Blue;
+     *   - multichannel fluorescence (channelCount > 1) → one channel per band,
+     *     named/tinted from the server `channelInfo` when present, else a palette;
+     *   - otherwise a single grayscale "Intensity" channel. */
+    private deriveChannels;
+    getChannelStates(): Observable<IChannelState[]>;
+    currentChannelStates(): IChannelState[];
+    /** Patch one channel by index (immutable update). */
+    setChannelState(index: number, partial: Partial<IChannelState>): void;
+    /** Replace all channel states (used by auto/reset). */
+    setChannelStates(states: IChannelState[]): void;
+    /** Reset one channel's display window, gamma AND colour to the values derived
+     *  for the current image (full 0..255 range, gamma 1, the channel's default
+     *  tint). Falls back to neutral defaults if no baseline was captured. */
+    resetChannelState(index: number): void;
+    getGrayscale(): Observable<boolean>;
+    currentGrayscale(): boolean;
+    setGrayscale(on: boolean): void;
+    getInvert(): Observable<boolean>;
+    currentInvert(): boolean;
+    setInvert(on: boolean): void;
+    /** Name→colour view of the current preset set (compat for backend renderers
+     *  that still read a Map). */
+    getClassificationColors(): Map<string, string>;
+    /** Upsert a single class colour (used by the editor's per-class colour picker). */
+    setClassificationColor(label: string, color: string): void;
+    getPresetSet(): PresetSet;
+    getPresetSet$(): Observable<PresetSet>;
+    setPresetSet(set: PresetSet): void;
+    /** Add or update a class (keyed by exact stored `name`). */
+    upsertClass(preset: ClassPreset): void;
+    removeClass(name: string): void;
+    resetPresets(): void;
+    /** Force a (debounced) write-back of the current preset set. */
+    persistPresets(): void;
+    getActiveTool$(): Observable<string | null>;
+    getActiveTool(): string | null;
+    setActiveTool(tool: string | null): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<VisualizerStore, [{ optional: true; }, { optional: true; }]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<VisualizerStore>;
+}

package/lib/toolbar/brush/brush-tool.service.d.ts

@@ -0,0 +1,143 @@
+import { WandService } from '../wand/wand.service';
+import { WandToolHost } from '../wand/wand-tool.service';
+import * as i0 from "@angular/core";
+/** Brush parameters. `size` is the brush *diameter* in matrix (image) pixels. */
+export interface BrushOptions {
+    size?: number;
+}
+/**
+ * The brush host is identical to the wand's — both need the cached-image
+ * coordinate frame, the overlay container, the coordinate transform, and
+ * read/write access to the shared region list. The brush ignores the wand's
+ * pixel values (it paints a geometric disc rather than flood-filling by colour),
+ * so reusing {@link WandToolHost} lets each backend bind the same host object.
+ */
+export type BrushToolHost = WandToolHost;
+/**
+ * QuPath-style brush tool. Painting a stroke unions a disc of the configured
+ * size into the active region as the cursor drags; holding <kbd>Shift</kbd>
+ * subtracts instead (eraser brush), matching the wand's modifier. The stroke is
+ * accumulated as a bbox-relative mask (exactly like {@link WandToolService}) so
+ * the brush inherits the wand's adopt-existing-region and merge-on-touch
+ * behaviour, then the union boundary is traced back into a polygon Region.
+ *
+ * No pixel sampling and no cursor indicator: the painted stroke itself shows the
+ * brush size. The overlay canvas only captures the pointer.
+ *
+ * Lifecycle mirrors the wand: a backend binds its host once, then toggles the
+ * tool with `setMode(true | false, options)`.
+ *
+ * Holes / donuts (jit-ui#85): brushing a ring that encloses an unpainted area
+ * keeps the enclosed hole — {@link WandService.maskToPolygons} traces interior
+ * rings into {@link Polygon.holes}, which adopt/merge preserve (the re-rasterize
+ * punches the holes back out). The OpenSeadragon overlay renders them with
+ * even-odd fill and GeoJSON round-trips them as extra Polygon rings. The Plotly
+ * (Heatmap) backend currently renders the filled exterior only.
+ */
+export declare class BrushToolService {
+    private wandService;
+    private host;
+    private overlay;
+    private active;
+    /**
+     * Accumulated brush region (bbox-relative mask). Persists across mouseup so a
+     * subsequent stroke extends the *same* region until the user switches tool —
+     * matching QuPath, and the wand.
+     */
+    private stroke;
+    /** Id of the region this stroke is editing (null = a fresh region). For an
+     *  erase that splits the region, this tracks the largest resulting piece. */
+    private strokeRegionId;
+    /** Readback ratio/origin signature the active stroke is tied to; a change (zoom/pan) invalidates
+     *  it so it isn't re-committed at a different scale (jit-ui#102). */
+    private strokeRatioSig;
+    /** Ids of the extra regions produced when an erase stroke splits a region
+     *  into disconnected pieces — reused across drag ticks so the split pieces
+     *  keep stable identities instead of being recreated each tick. */
+    private strokeExtraIds;
+    /** Previous cursor position (matrix coords) within the current drag, so fast
+     *  drags paint a continuous stroke rather than disconnected dabs. */
+    private lastMatrix;
+    private dragging;
+    private size;
+    private readonly boundMouseDown;
+    private readonly boundMouseMove;
+    private readonly boundMouseUp;
+    constructor(wandService: WandService);
+    /** Wire the tool to its host. Must be called once before `setMode(true)`. */
+    bindHost(host: BrushToolHost): void;
+    /** Toggle the brush on/off. */
+    setMode(active: boolean, options?: BrushOptions): void;
+    /** Live-update the brush size (matrix-pixel diameter). */
+    setSize(size: number): void;
+    /** Drop the active brush region so the next stroke starts a new one. */
+    clearActiveRegion(): void;
+    private createOverlay;
+    private destroyOverlay;
+    private onMouseDown;
+    private onMouseMove;
+    private onMouseUp;
+    private resetStroke;
+    /**
+     * Paint (or erase) a disc — or a swept line of discs since the previous
+     * tick — into the active region's accumulator mask, re-trace the boundary,
+     * and commit the updated Region. Shift = erase.
+     */
+    private applyAtClient;
+    /**
+     * OR (add) or AND-NOT (erase) a filled disc of `radius` matrix-pixels centred
+     * at (cx, cy) into the accumulator, growing its bbox to fit when adding.
+     */
+    private stampDisc;
+    /**
+     * Ensure the accumulator's bbox covers [px0,py0,px1,py1) (clamped to the
+     * image), allocating/copying a larger mask when it must grow. Returns false if
+     * the requested box is empty after clamping.
+     */
+    private ensureStrokeCovers;
+    /** True if (matrixX, matrixY) lies inside the current stroke accumulator. */
+    private pointInStroke;
+    /**
+     * Remove the region(s) referenced by the stroke and reset it — used when an
+     * erase stroke deletes every pixel.
+     */
+    private dropActiveShape;
+    /** A region's closed-polygon vertices (image/data coords), or null when it
+     *  isn't a fillable closed polygon (rectangles, open polylines). */
+    private regionVerts;
+    /** Whether a region can be faithfully rasterized at this zoom (rx/ry = data units per matrix px).
+     *  Editing rasterizes + re-traces the region, so one whose matrix-space bbox exceeds the
+     *  rasterizer cap would come back rescaled/corrupted (e.g. a whole-slide annotation while zoomed
+     *  out) — skip adopt/merge for those and only edit them near native zoom (jit-ui#102). */
+    private fitsForEdit;
+    /** Convert a region's hole rings from image/data coords into matrix coords so
+     *  they line up with the stroke accumulator (jit-ui#85). */
+    private holesToMatrix;
+    /**
+     * If (matrixX, matrixY) falls inside an existing region, rasterize it into the
+     * stroke accumulator so subsequent brush input extends it rather than starting
+     * a new region.
+     */
+    private tryAdoptShapeAt;
+    /**
+     * Fold every region whose rasterized mask overlaps the stroke mask into the
+     * stroke and remove it from the list, so brushing across regions merges them.
+     */
+    private mergeOverlappingShapes;
+    /**
+     * Commit the stroke's connected pieces as regions — the largest keeps the
+     * stroke's region identity, additional pieces (from an erase that split the
+     * region) become their own regions tracked in `strokeExtraIds` so they keep
+     * stable identities across drag ticks. The store mints ids on commit, which
+     * we read back so subsequent ticks replace the same regions.
+     */
+    private commitComponents;
+    /**
+     * Build a Region for one component and insert it into `regions`: replace the
+     * region with `id` in place if it exists, otherwise append a new one. Returns
+     * the Region instance (its id is minted later by the store when new).
+     */
+    private upsertComponent;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BrushToolService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BrushToolService>;
+}

package/lib/toolbar/crop/slide-crop.d.ts

@@ -0,0 +1,30 @@
+import { CachedImageData } from '../wand/wand-tool.service';
+/** A client-side crop of the loaded image — the browser equivalent of the JIT
+ *  server slide-crop, taken from the pixels already in the viewer. */
+export interface CroppedImage {
+    /** RGBA pixels of the crop, row-major. */
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+    /** Crop origin in image (matrix) coords — lets masks map back to the frame. */
+    matrixX0: number;
+    matrixY0: number;
+}
+/** A box in image *data* coordinates (as stored on a Rectangle region). */
+export interface DataBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/**
+ * Browser "slide crop": extract the box region (data coords) from a cached image
+ * frame as an RGBA image, clamped to the image bounds. Grayscale frames are
+ * replicated across R/G/B; RGB tuples are copied through. Returns null when the
+ * box is empty/outside the image.
+ *
+ * The output feeds an automatic segmenter (e.g. cellpose-SAM): run it on the
+ * crop, then offset the resulting masks by (matrixX0, matrixY0) to place them
+ * back on the full frame.
+ */
+export declare function cropImageRegion(cached: CachedImageData, frameIndex: number, box: DataBox): CroppedImage | null;

package/lib/toolbar/segmentation/cell-segment-tool.service.d.ts

@@ -0,0 +1,32 @@
+import { BehaviorSubject } from 'rxjs';
+import { WandService } from '../wand/wand.service';
+import { WandToolHost } from '../wand/wand-tool.service';
+import { ICellSegmenter } from '../../contracts/cell-segmenter.contract';
+import * as i0 from "@angular/core";
+/**
+ * Automatic cell segmentation inside drawn boxes (jit-ui#90). For each rectangle
+ * it client slide-crops the box from the loaded image, runs an automatic
+ * segmenter (cellpose-SAM, supplied by the host via {@link ICellSegmenter}) on
+ * the crop, and turns every cell instance into a region — offset back onto the
+ * frame. The prompt rectangle is replaced by its cell regions.
+ *
+ * This is the complement to the promptable SAM tool: cellpose-SAM can't take a
+ * box prompt, so the box just bounds the crop it segments automatically.
+ */
+export declare class CellSegmentToolService {
+    private wandService;
+    private host;
+    readonly status$: BehaviorSubject<string>;
+    readonly busy$: BehaviorSubject<boolean>;
+    readonly progress$: BehaviorSubject<number>;
+    constructor(wandService: WandService);
+    bindHost(host: WandToolHost): void;
+    /**
+     * Crop + cellpose-segment every rectangle; append the cell regions and drop
+     * the prompt rectangles that produced cells. Returns the number of regions added.
+     */
+    segmentBoxes(segmenter: ICellSegmenter): Promise<number>;
+    private makeRegion;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CellSegmentToolService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CellSegmentToolService>;
+}

package/lib/toolbar/segmentation/cellpose-segmenter.service.d.ts

@@ -0,0 +1,39 @@
+import type { ICellSegmenter, CellSegmentation, CellSegmentProgress } from '../../contracts/cell-segmenter.contract';
+import type { Cellpose } from 'cellpose-js';
+import * as i0 from "@angular/core";
+/**
+ * Default in-library {@link ICellSegmenter} backed by cellpose-js (WebGPU/WASM
+ * ONNX) — so the toolbar's automatic **Cellpose** tool works out of the box in
+ * any app, with no host wiring (jit-ui#90). `cellpose-js` is a peer dependency
+ * and is **lazy-imported** on first use, so apps that never run Cellpose pay
+ * nothing for it. A host can still override the {@link CELL_SEGMENTER} token to
+ * supply a different implementation.
+ *
+ * Owns a single shared {@link Cellpose} instance (one model load, one WebGPU
+ * session, one worker). {@link getModel} exposes that instance so a host's
+ * processing pipeline can reuse it instead of loading the ~588 MB model twice.
+ */
+export declare class CellposeSegmenterService implements ICellSegmenter {
+    private instance;
+    private loading;
+    private modelUrl;
+    /** Point the segmenter at a different hosted CPSAM ONNX (before first use). */
+    setModelUrl(url: string): void;
+    segmentCells(image: {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    }, progress?: CellSegmentProgress): Promise<CellSegmentation>;
+    /**
+     * The shared Cellpose instance, lazily created on first use and reused
+     * thereafter (deduped across concurrent callers). Exposed so a host pipeline
+     * engine can run richer `segment()` options on the same instance. `onProgress`
+     * reports raw downloaded/total bytes (`total` is null when unknown); `onStatus`
+     * reports worker-init phase strings.
+     */
+    getModel(onProgress?: (loaded: number, total: number | null) => void, onStatus?: (status: string) => void): Promise<Cellpose>;
+    /** Whether the shared model is already loaded (warm). */
+    isLoaded(): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CellposeSegmenterService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CellposeSegmenterService>;
+}

package/lib/toolbar/segmentation/onnx-sam-session.d.ts

@@ -0,0 +1,25 @@
+import { ISamSession, SamEmbedding, SamMaskResult, SamModelDef, SamPrompt } from '../../contracts/sam.contract';
+export declare class OnnxSamSession implements ISamSession {
+    private mode;
+    private loaded;
+    private model;
+    private inputSize;
+    private worker;
+    private seq;
+    private readonly pending;
+    private encoder;
+    private decoder;
+    private nextToken;
+    private readonly embeddings;
+    loadModel(model: SamModelDef, onProgress?: (fraction: number) => void): Promise<void>;
+    isLoaded(): boolean;
+    embed(image: {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    }): Promise<SamEmbedding>;
+    decode(embedding: SamEmbedding, prompt: SamPrompt): Promise<SamMaskResult>;
+    dispose(): void;
+    private ensureWorker;
+    private call;
+}

package/lib/toolbar/segmentation/ort-runtime-config.d.ts

@@ -0,0 +1,4 @@
+/** Override where onnxruntime-web loads its WASM sidecars from. See module docs. */
+export declare function setOrtWasmBase(base: string): void;
+/** The configured onnxruntime-web WASM base (default `'/assets/ort/'`). */
+export declare function getOrtWasmBase(): string;

package/lib/toolbar/segmentation/sam-model-registry.d.ts

@@ -0,0 +1,36 @@
+import { SamModelDef } from '../../contracts/sam.contract';
+/**
+ * Registry of promptable SAM models for the browser segment tool.
+ *
+ * micro-sam (microscopy-finetuned, promptable) and patho-sam (histopathology-
+ * finetuned) are entries; SAM3 slots in here once its quantized ONNX export and
+ * a `variant: 'sam3'` decoder path are published. The
+ * automatic cellpose-SAM model is intentionally NOT here — it's not promptable
+ * and lives in the processing-pipeline's cellpose engine as the automatic tool.
+ *
+ * `encoderUrl` / `decoderUrl` point at the public HF-hosted ONNX pairs by
+ * default, so the segment tools work out of the box in any host (mirroring the
+ * cellpose default). A host can repoint them at its own hosting (e.g. a GCS
+ * bucket) at runtime via {@link setSamModelUrls}; an empty URL disables a model
+ * (the session throws a clear "not configured" error). Export/quantization
+ * tooling: the sibling `browser-onnx-tools` project; see docs/sam-segmentation-design.md.
+ */
+export declare const SAM_MODELS: SamModelDef[];
+/** Initial default model id (overridden at runtime once the host configures a
+ *  hosted model via {@link setSamModelUrls}). */
+export declare const DEFAULT_SAM_MODEL_ID: string;
+/** Look up a model by id; falls back to the active default when id is
+ *  unknown/absent. */
+export declare function getSamModel(id?: string): SamModelDef;
+/** The active default model id (what the tools/picker use when unset). */
+export declare function getDefaultSamModelId(): string;
+/** Set the active default model id (must be a registered model). */
+export declare function setDefaultSamModel(id: string): void;
+/** True when a model has both ONNX URLs configured (i.e. it can actually run). */
+export declare function isSamModelReady(model: SamModelDef): boolean;
+/**
+ * Point a registered model at its hosted ONNX pair (HF / GCS). Called by the
+ * host's composition root once hosting is decided, keeping deployment URLs out
+ * of the library.
+ */
+export declare function setSamModelUrls(id: string, encoderUrl: string, decoderUrl: string): void;

package/lib/toolbar/segmentation/sam-onnx-core.d.ts

@@ -0,0 +1,48 @@
+import * as ort from 'onnxruntime-web';
+import type { SamPrompt } from '../../contracts/sam.contract';
+/**
+ * Shared, DOM-free SAM inference primitives used by BOTH inference backends:
+ * the in-process session (`OnnxSamSession`, main thread) and the dedicated
+ * Web Worker (`onnx-sam.worker`). Keeping these here avoids duplicating the
+ * preprocessing / decoder-prompt math and keeps the worker DOM-free (it can't
+ * import sam-prompt.ts, which pulls in DOM types).
+ */
+export declare const PIXEL_MEAN: number[];
+export declare const PIXEL_STD: number[];
+/** Encoder output for one image, reused across prompts. */
+export interface CoreEmbedding {
+    data: Float32Array;
+    dims: number[];
+    scale: number;
+    imageWidth: number;
+    imageHeight: number;
+}
+/** Decoder output: a binary mask at original-image resolution. */
+export interface CoreMask {
+    mask: Uint8Array;
+    width: number;
+    height: number;
+    iou: number;
+}
+/** Fetch a model as an ArrayBuffer, streaming progress and caching in the Cache
+ *  API (so it isn't re-downloaded). Cache hit → progress jumps to 1. Works on
+ *  the main thread and in a worker (both have `fetch` + `caches`). */
+export declare function fetchModel(url: string, onProgress?: (f: number) => void): Promise<ArrayBuffer>;
+/** Resize (long side → size, bilinear), pad to size×size, SAM-normalize → CHW float32. */
+export declare function preprocess(data: Uint8ClampedArray, width: number, height: number, size: number, scale: number): Float32Array;
+/** Assemble decoder `point_coords`/`point_labels` from a prompt, in encoder
+ *  (resized) space. Box = two points labelled 2/3; points use 1/0; a points-only
+ *  prompt pads the absent box slot with `[0,0]` labelled -1. */
+export declare function buildDecoderPrompt(prompt: SamPrompt, scale: number): {
+    pointCoords: Float32Array;
+    pointLabels: Float32Array;
+    numPoints: number;
+};
+/** Binarize mask logits (`> threshold`) into a 0/1 mask. */
+export declare function binarizeMask(logits: Float32Array, threshold?: number): Uint8Array;
+/** Index of the highest-scoring mask in a multimask decoder output. */
+export declare function bestMaskIndex(iou: Float32Array | number[]): number;
+/** Run the encoder on an RGBA image → a reusable embedding. */
+export declare function runEncoder(encoder: ort.InferenceSession, data: Uint8ClampedArray, width: number, height: number, inputSize: number): Promise<CoreEmbedding>;
+/** Run the decoder for one prompt against a cached embedding → a binary mask. */
+export declare function runDecoder(decoder: ort.InferenceSession, e: CoreEmbedding, prompt: SamPrompt): Promise<CoreMask>;

package/lib/toolbar/segmentation/sam-point-tool.service.d.ts

@@ -0,0 +1,59 @@
+import { BehaviorSubject } from 'rxjs';
+import { WandService } from '../wand/wand.service';
+import { WandToolHost } from '../wand/wand-tool.service';
+import { ISamSession } from '../../contracts/sam.contract';
+import * as i0 from "@angular/core";
+/** Interactive SAM point-prompt tool (jit-ui#90, P1).
+ *
+ * Each plain (positive) click segments the clicked object as its OWN new region
+ * — clicking a second fiber doesn't extend the first into it. Shift/Alt-click
+ * adds a negative (exclude) point that refines the CURRENT object, re-running
+ * the decoder against the (cached) image embedding and updating its live region.
+ * `commit()` (Enter) finalises early; `clear()` (Esc) discards the current
+ * prompt + its preview region. Mirrors the wand/brush on-canvas tool pattern and
+ * reuses WandService.maskToPolygons + the shared region store.
+ *
+ * Inference is behind {@link ISamSession} (lazy onnxruntime-web in production,
+ * a fake in tests).
+ */
+export declare class SamPointToolService {
+    private wandService;
+    private host;
+    private overlay;
+    private session;
+    /** In-flight session load — dedupes a warm-up preload against the first click. */
+    private sessionLoad;
+    private model;
+    private embedding;
+    private embeddingKey;
+    /** Accumulated point prompts, in image (matrix) coords. */
+    private points;
+    /** Id of the in-progress (preview) region being refined, if committed to store. */
+    private regionId;
+    readonly status$: BehaviorSubject<string>;
+    readonly busy$: BehaviorSubject<boolean>;
+    /** Encoder-download progress (0..1) on the first click; -1 when not downloading. */
+    readonly progress$: BehaviorSubject<number>;
+    private readonly boundMouseDown;
+    constructor(wandService: WandService);
+    bindHost(host: WandToolHost): void;
+    setModel(id: string): void;
+    /** Test seam: inject a fake/alternate session. */
+    useSession(session: ISamSession): void;
+    setMode(active: boolean): void;
+    /** Eagerly load the model in the background (fire-and-forget). Safe to call
+     *  repeatedly — it dedupes against an in-flight load and an existing session. */
+    preload(): void;
+    /** Finalise the current object: keep its region, start fresh next click. */
+    commit(): void;
+    /** Discard the in-progress prompt + its preview region. */
+    clear(): void;
+    private createOverlay;
+    private destroyOverlay;
+    private onMouseDown;
+    /** Replace (or insert) the in-progress preview region in the shared store. */
+    private upsertPreview;
+    private ensureSession;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SamPointToolService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SamPointToolService>;
+}

package/lib/toolbar/segmentation/sam-prompt.d.ts

@@ -0,0 +1,34 @@
+import { CachedImageData } from '../wand/wand-tool.service';
+import { SamPrompt } from '../../contracts/sam.contract';
+/**
+ * Pure helpers for SAM inference — no DOM, no ORT, no `this` — so they're unit
+ * testable. The session uses these to assemble decoder inputs and to convert
+ * the cached image frame into the RGBA buffer the encoder preprocesses.
+ */
+/**
+ * Build an RGBA buffer (the encoder's input image) from a cached image frame.
+ * Grayscale frames are replicated across R/G/B; RGB tuples are copied through.
+ * Out-of-range/missing pixels become opaque black.
+ */
+export declare function frameToRgba(cached: CachedImageData, frameIndex: number): Uint8ClampedArray;
+/**
+ * Assemble the SAM decoder's `point_coords` / `point_labels` from a prompt.
+ *
+ * Coordinates are scaled into the encoder's resized space (`scale =
+ * inputSize / max(imageW, imageH)`). A box is encoded as two points labelled
+ * `2` (top-left) and `3` (bottom-right); positive/negative points use `1`/`0`.
+ * When there are points but no box, a padding point `[0,0]` labelled `-1` is
+ * appended (the decoder expects the box slots padded when absent).
+ */
+export declare function buildDecoderPrompt(prompt: SamPrompt, scale: number): {
+    pointCoords: Float32Array;
+    pointLabels: Float32Array;
+    numPoints: number;
+};
+/**
+ * Binarize SAM mask logits (`> threshold`, default 0 per SAM's mask_threshold)
+ * into a 0/1 mask the contour tracer (WandService.maskToPolygons) consumes.
+ */
+export declare function binarizeMask(logits: Float32Array | number[], threshold?: number): Uint8Array;
+/** Index of the highest-scoring mask in a multimask decoder output. */
+export declare function bestMaskIndex(iouPredictions: Float32Array | number[]): number;

package/lib/toolbar/segmentation/sam-tool.service.d.ts

@@ -0,0 +1,50 @@
+import { BehaviorSubject } from 'rxjs';
+import { WandService } from '../wand/wand.service';
+import { WandToolHost } from '../wand/wand-tool.service';
+import { ISamSession } from '../../contracts/sam.contract';
+import * as i0 from "@angular/core";
+/** The SAM tool binds to the same host the wand/brush use, so each backend
+ *  reuses its existing pixel readback + coordinate transform + region store. */
+export type SamToolHost = WandToolHost;
+/**
+ * Box-prompted SAM segmentation tool (jit-ui#90, P0). On `segmentBoxes()` it
+ * reads every rectangle region, runs the (cached) encoder once for the image,
+ * then runs the decoder per box, traces each mask to a polygon (reusing
+ * WandService.maskToPolygons) and commits them as regions.
+ *
+ * Inference is abstracted behind {@link ISamSession}: production uses the
+ * onnxruntime-web session (lazy-imported so ORT never loads in unit tests);
+ * tests inject a fake via {@link useSession}.
+ */
+export declare class SamToolService {
+    private wandService;
+    private host;
+    private session;
+    private model;
+    /** Cached encoder embedding + the key (image identity) it was computed for. */
+    private embedding;
+    private embeddingKey;
+    /** Status text + busy flag for a spinner / toast in the host. */
+    readonly status$: BehaviorSubject<string>;
+    readonly busy$: BehaviorSubject<boolean>;
+    /** Encoder-download progress: -1 = not downloading, 0..1 = downloading. */
+    readonly progress$: BehaviorSubject<number>;
+    constructor(wandService: WandService);
+    /** Bind to the active backend's host (called by the backend, like the wand). */
+    bindHost(host: SamToolHost): void;
+    /** Choose the registered model to use; invalidates any cached embedding. */
+    setModel(id: string): void;
+    /** Drop the cached embedding (e.g. after the image/slice changes). */
+    invalidateEmbedding(): void;
+    /** Test seam: inject a fake/alternate inference session. */
+    useSession(session: ISamSession): void;
+    /**
+     * Segment every rectangle region with a box prompt and append the resulting
+     * masks as new polygon regions. Returns how many regions were added.
+     */
+    segmentBoxes(): Promise<number>;
+    private makeRegion;
+    private ensureSession;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SamToolService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SamToolService>;
+}