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

package/fesm2022/onnx-sam.worker.js

@@ -0,0 +1,202 @@
+// src/lib/toolbar/segmentation/onnx-sam.worker.ts
+import * as ort2 from "onnxruntime-web";
+
+// src/lib/toolbar/segmentation/sam-onnx-core.ts
+import * as ort from "onnxruntime-web";
+var PIXEL_MEAN = [123.675, 116.28, 103.53];
+var PIXEL_STD = [58.395, 57.12, 57.375];
+var MODEL_CACHE = "sam-onnx";
+async function fetchModel(url, onProgress) {
+  const cache = typeof caches !== "undefined" ? await caches.open(MODEL_CACHE).catch(() => null) : null;
+  const hit = cache ? await cache.match(url) : null;
+  if (hit) {
+    onProgress?.(1);
+    return await hit.arrayBuffer();
+  }
+  const resp = await fetch(url);
+  if (!resp.ok)
+    throw new Error(`fetch ${url} failed: HTTP ${resp.status}`);
+  const total = Number(resp.headers.get("content-length")) || 0;
+  if (!resp.body || !total) {
+    const buf = await resp.arrayBuffer();
+    onProgress?.(1);
+    if (cache)
+      await cache.put(url, new Response(buf)).catch(() => void 0);
+    return buf;
+  }
+  const reader = resp.body.getReader();
+  const chunks = [];
+  let received = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    chunks.push(value);
+    received += value.length;
+    onProgress?.(received / total);
+  }
+  const out = new Uint8Array(received);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  if (cache) {
+    await cache.put(url, new Response(out.slice(), { headers: { "content-length": String(received) } })).catch(() => void 0);
+  }
+  onProgress?.(1);
+  return out.buffer;
+}
+function preprocess(data, width, height, size, scale) {
+  const newW = Math.round(width * scale);
+  const newH = Math.round(height * scale);
+  const chw = new Float32Array(3 * size * size);
+  for (let y = 0; y < newH; y++) {
+    const sy = Math.min(height - 1, y / scale);
+    const y0 = Math.floor(sy);
+    const fy = sy - y0;
+    const y1 = Math.min(height - 1, y0 + 1);
+    for (let x = 0; x < newW; x++) {
+      const sx = Math.min(width - 1, x / scale);
+      const x0 = Math.floor(sx);
+      const fx = sx - x0;
+      const x1 = Math.min(width - 1, x0 + 1);
+      for (let c = 0; c < 3; c++) {
+        const p00 = data[(y0 * width + x0) * 4 + c];
+        const p01 = data[(y0 * width + x1) * 4 + c];
+        const p10 = data[(y1 * width + x0) * 4 + c];
+        const p11 = data[(y1 * width + x1) * 4 + c];
+        const top = p00 + (p01 - p00) * fx;
+        const bot = p10 + (p11 - p10) * fx;
+        const v = top + (bot - top) * fy;
+        chw[c * size * size + y * size + x] = (v - PIXEL_MEAN[c]) / PIXEL_STD[c];
+      }
+    }
+  }
+  return chw;
+}
+function buildDecoderPrompt(prompt, scale) {
+  const coords = [];
+  const labels = [];
+  for (const p of prompt.points ?? []) {
+    coords.push(p.x * scale, p.y * scale);
+    labels.push(p.label);
+  }
+  if (prompt.box) {
+    const b = prompt.box;
+    coords.push(b.x0 * scale, b.y0 * scale);
+    labels.push(2);
+    coords.push(b.x1 * scale, b.y1 * scale);
+    labels.push(3);
+  } else if (labels.length > 0) {
+    coords.push(0, 0);
+    labels.push(-1);
+  }
+  return {
+    pointCoords: Float32Array.from(coords),
+    pointLabels: Float32Array.from(labels),
+    numPoints: labels.length
+  };
+}
+function binarizeMask(logits, threshold = 0) {
+  const out = new Uint8Array(logits.length);
+  for (let i = 0; i < logits.length; i++)
+    out[i] = logits[i] > threshold ? 1 : 0;
+  return out;
+}
+function bestMaskIndex(iou) {
+  let best = 0;
+  for (let i = 1; i < iou.length; i++)
+    if (iou[i] > iou[best])
+      best = i;
+  return best;
+}
+async function runEncoder(encoder2, data, width, height, inputSize2) {
+  const scale = inputSize2 / Math.max(width, height);
+  const input = preprocess(data, width, height, inputSize2, scale);
+  const out = await encoder2.run({
+    [encoder2.inputNames[0]]: new ort.Tensor("float32", input, [1, 3, inputSize2, inputSize2])
+  });
+  const emb = out[encoder2.outputNames[0]];
+  return {
+    data: emb.data,
+    dims: emb.dims,
+    scale,
+    imageWidth: width,
+    imageHeight: height
+  };
+}
+async function runDecoder(decoder2, e, prompt) {
+  const { pointCoords, pointLabels, numPoints } = buildDecoderPrompt(prompt, e.scale);
+  const out = await decoder2.run({
+    image_embeddings: new ort.Tensor("float32", e.data, e.dims),
+    point_coords: new ort.Tensor("float32", pointCoords, [1, numPoints, 2]),
+    point_labels: new ort.Tensor("float32", pointLabels, [1, numPoints]),
+    mask_input: new ort.Tensor("float32", new Float32Array(256 * 256), [1, 1, 256, 256]),
+    has_mask_input: new ort.Tensor("float32", Float32Array.from([0]), [1]),
+    orig_im_size: new ort.Tensor("float32", Float32Array.from([e.imageHeight, e.imageWidth]), [2])
+  });
+  const masks = out["masks"] ?? out[decoder2.outputNames[0]];
+  const iou = out["iou_predictions"]?.data ?? Float32Array.from([1]);
+  const [, m, h, w] = masks.dims;
+  const idx = bestMaskIndex(iou.slice(0, m));
+  const logits = masks.data.subarray(idx * h * w, (idx + 1) * h * w);
+  return { mask: binarizeMask(logits), width: w, height: h, iou: iou[idx] ?? 1 };
+}
+
+// src/lib/toolbar/segmentation/onnx-sam.worker.ts
+var encoder = null;
+var decoder = null;
+var inputSize = 1024;
+var nextToken = 1;
+var embeddings = /* @__PURE__ */ new Map();
+function post(msg, transfer = []) {
+  self.postMessage(msg, transfer);
+}
+async function onLoad(msg) {
+  ort2.env.wasm.wasmPaths = msg.wasmPaths;
+  inputSize = msg.inputSize || 1024;
+  const hasGpu = typeof navigator !== "undefined" && "gpu" in navigator;
+  const eps = msg.encoderProviders && msg.encoderProviders.length ? msg.encoderProviders : hasGpu ? ["webgpu", "wasm"] : ["wasm"];
+  const encBuf = await fetchModel(msg.encoderUrl, (f) => post({ id: msg.id, type: "progress", fraction: f }));
+  const decBuf = await fetchModel(msg.decoderUrl);
+  encoder = await ort2.InferenceSession.create(encBuf, { executionProviders: eps });
+  decoder = await ort2.InferenceSession.create(decBuf, { executionProviders: ["wasm"] });
+  post({ id: msg.id, type: "loaded" });
+}
+async function onEmbed(msg) {
+  if (!encoder)
+    throw new Error("SAM encoder not loaded.");
+  const data = new Uint8ClampedArray(msg.buffer);
+  const e = await runEncoder(encoder, data, msg.width, msg.height, inputSize);
+  const token = nextToken++;
+  embeddings.set(token, e);
+  if (embeddings.size > 3)
+    embeddings.delete(embeddings.keys().next().value);
+  post({ id: msg.id, type: "embedded", token, scale: e.scale, imageWidth: e.imageWidth, imageHeight: e.imageHeight, dims: e.dims });
+}
+async function onDecode(msg) {
+  if (!decoder)
+    throw new Error("SAM decoder not loaded.");
+  const e = embeddings.get(msg.token);
+  if (!e)
+    throw new Error("SAM embedding expired; re-encode the image.");
+  const r = await runDecoder(decoder, e, msg.prompt);
+  post(
+    { id: msg.id, type: "decoded", width: r.width, height: r.height, iou: r.iou, buffer: r.mask.buffer },
+    [r.mask.buffer]
+  );
+}
+self.onmessage = async (ev) => {
+  const msg = ev.data;
+  try {
+    if (msg.type === "load")
+      await onLoad(msg);
+    else if (msg.type === "embed")
+      await onEmbed(msg);
+    else if (msg.type === "decode")
+      await onDecode(msg);
+  } catch (err) {
+    post({ id: msg.id, type: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+};

package/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Public API of the jax-image-visualization library. External consumers import
+ * ONLY from here (`@jax-data-science/sci-image-visualizer`); everything else under `lib/` is
+ * internal. The surface is contracts + tokens + neutral models + the Angular
+ * module, plus the routing service the host's composition root binds the tokens
+ * to (`useExisting`).
+ */
+export * from './lib/contracts/visualizer.contract';
+export * from './lib/contracts/region-editor-api.contract';
+export * from './lib/contracts/ports/image-state.port';
+export * from './lib/contracts/ports/tile-access.port';
+export * from './lib/contracts/ports/region-io.port';
+export * from './lib/contracts/ports/preferences.port';
+export * from './lib/contracts/channel-histogram-api.contract';
+export * from './lib/contracts/viz-config';
+export * from './lib/contracts/image.contract';
+export * from './lib/contracts/plot-type';
+export * from './lib/contracts/toolbar-config';
+export * from './lib/contracts/capabilities.contract';
+export * from './lib/contracts/region-overlay.contract';
+export * from './lib/contracts/display-types';
+export * from './lib/contracts/sam.contract';
+export * from './lib/contracts/cell-segmenter.contract';
+export { CellposeSegmenterService } from './lib/toolbar/segmentation/cellpose-segmenter.service';
+export { ProcessingImage } from './lib/processing/processing-image';
+export { cropImage, CropImageOptions } from './lib/processing/image-crop';
+export { ImageConverterService } from './lib/processing/image-converter.service';
+export { SAM_MODELS, DEFAULT_SAM_MODEL_ID, getSamModel, isSamModelReady, setSamModelUrls, setDefaultSamModel, getDefaultSamModelId, } from './lib/toolbar/segmentation/sam-model-registry';
+export { setOrtWasmBase, getOrtWasmBase } from './lib/toolbar/segmentation/ort-runtime-config';
+export * from './lib/models/region';
+export * from './lib/models/class-preset';
+export { ShapeSelection } from './lib/models/shape';
+export { VisualizationModule } from './lib/visualization.module';
+export { RoutingVisualizerService } from './lib/routing-visualizer.service';
+export { provideVisualization } from './lib/provide-visualization';
+export { VisualizerComponent } from './lib/visualizer.component';
+export { RegionEditorComponent } from './lib/region-editor/region-editor.component';
+export { HexColorPickerComponent } from './lib/hex-color-picker/hex-color-picker.component';
+export { ChannelHistogramComponent } from './lib/channel-histogram/channel-histogram.component';

package/lib/channel-histogram/channel-histogram.component.d.ts

@@ -0,0 +1,112 @@
+import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
+import { TreeNode } from 'primeng/api';
+import { IChannelHistogramApi, IChannelState, IHistogram } from '../contracts/channel-histogram-api.contract';
+import * as i0 from "@angular/core";
+/**
+ * Channels & Histogram pane: a non-modal, resizable, draggable dialog for
+ * brightness/contrast (per-channel display window), gamma, channel
+ * visibility/colour, the intensity histogram, and the colormap/reverse/invert
+ * controls (moved here from the toolbar). Every edit flows through
+ * {@link CHANNEL_HISTOGRAM_API} into the shared store, and both rendering
+ * backends recolor the displayed image live. The pane depends only on the
+ * contract, never the concrete visualizer.
+ */
+export declare class ChannelHistogramComponent implements OnInit, OnDestroy {
+    private api;
+    /** Dialog visibility, two-way bound so the host (toolbar button) can open it. */
+    visible: boolean;
+    visibleChange: EventEmitter<boolean>;
+    readonly histogramDiv = "channel-histogram-plot";
+    readonly lutColors: readonly {
+        name: string;
+        color: string;
+    }[];
+    channels: IChannelState[];
+    selected: IChannelState | null;
+    invert: boolean;
+    logScale: boolean;
+    /** Bounded retries while the (async) histogram sampling resolves. */
+    private histRetries;
+    /** The selected channel's current histogram. Native bit depth (with
+     *  observed/range fields) for >8-bit images, else the 8-bit client histogram.
+     *  Drives the plot, the native window labels, and the export-button gate. */
+    hist: IHistogram | null;
+    private histSub?;
+    /** Which window control is being adjusted right now — drives a small
+     *  non-blocking activity spinner next to that slider, since the image recolor
+     *  isn't instant on large stacks. Cleared a short moment after movement stops
+     *  (the recolor isn't directly observable, so this is a trailing heuristic). */
+    activeAdjust: 'min' | 'max' | 'gamma' | null;
+    private adjustTimer?;
+    colormapOptions: any;
+    selectedColormap: any;
+    private subs;
+    /** Keeps the Plotly histogram sized to the (resizable) dialog body. */
+    private resizeObserver?;
+    constructor(api: IChannelHistogramApi);
+    /** Per-channel pseudo-colour only applies when there's more than one channel
+     *  (RGB / fluorescence). A single grayscale channel uses the colormap instead. */
+    get multichannel(): boolean;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    onVisibleChange(v: boolean): void;
+    /** p-dialog (onShow): the plot div now exists, so draw the histogram and keep
+     *  it sized to the dialog (which is resizable) via a ResizeObserver. */
+    onShow(): void;
+    private teardownResize;
+    selectChannel(ch: IChannelState): void;
+    onMinChange(value: any): void;
+    onMaxChange(value: any): void;
+    onGammaChange(value: any): void;
+    /** Flag a control as actively adjusting so its spinner shows; auto-clears a
+     *  short moment after the last change (kept alive while the user keeps
+     *  dragging, since each change resets the timer). */
+    private markBusy;
+    onVisibleToggle(ch: IChannelState, value: boolean): void;
+    onColorChange(ch: IChannelState, color: string): void;
+    onColormap(node: TreeNode): void;
+    onInvert(value: boolean): void;
+    toggleLog(value: boolean): void;
+    /** Quick-assign a preset LUT colour to a channel (Fiji palette). */
+    setPreset(ch: IChannelState, color: string): void;
+    /** Export the displayed composite as a publication-ready PNG (8-bit figure). */
+    exportComposite(): void;
+    /** Export the underlying data as a true-16-bit multi-band TIFF (server-side). */
+    exportData(): void;
+    /** True when the current channel histogram is native >8-bit (16-bit etc.):
+     *  gates the native slider labelling and the 16-bit TIFF export button. */
+    get is16bit(): boolean;
+    /** The native value range the 8-bit display window maps onto — the observed
+     *  pixel extremes for a native histogram, else plain 0..255 (so 8-bit images
+     *  pass through unchanged). The 8-bit tile is server-stretched across this
+     *  range, so it's the best client-side native↔display mapping. */
+    private obsRange;
+    /** 8-bit display value (0..255) → native units. */
+    private toNative;
+    /** Native units → clamped 8-bit display value (0..255). */
+    private toDisp;
+    /** Selected channel window endpoints in native units (for the sliders). */
+    get minNative(): number;
+    get maxNative(): number;
+    /** Native slider bounds + step (256 display steps across the native range). */
+    get sliderMin(): number;
+    get sliderMax(): number;
+    get sliderStep(): number;
+    auto(): void;
+    reset(): void;
+    /** Saturation-based auto-window over a (native or 8-bit) histogram: pick
+     *  [min,max] so ~`saturation` of pixels clip at each end, dropping a dominant
+     *  first/last bin (background/padding). Returns native bin values. */
+    private autoWindow;
+    /** Fetch the selected channel's histogram (native for 16-bit, else 8-bit) and
+     *  (re)draw it. Async — the native path hits the server; the 8-bit path may be
+     *  null until tile sampling resolves, so we retry a few times. */
+    private loadHistogram;
+    private renderHistogram;
+    /** Move only the min/max marker lines (cheap) without recomputing counts. */
+    private updateMarkers;
+    private markerShapes;
+    private histogramLayout;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ChannelHistogramComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ChannelHistogramComponent, "channel-histogram", never, { "visible": { "alias": "visible"; "required": false; }; }, { "visibleChange": "visibleChange"; }, never, never, false, never>;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Optional features a viewer backend may or may not support. Consumers query
+ * `IImageViewer.capabilities` and degrade gracefully (hide a toolbar item,
+ * skip a render path) rather than calling a method that no-ops.
+ *
+ * The Plotly backend supports the scientific/data features; the OpenSeadragon
+ * backend supports `ImageDisplay` (large zoomable image) but not the
+ * scalar-data features. The eventual router picks a backend per plot type.
+ */
+export declare enum ViewerFeature {
+    /** Display a raster/tiled image (HEATMAP/RGB image, OSD's strength). */
+    ImageDisplay = "imageDisplay",
+    /** 3D scene rendering (SURFACE, SCATTER3D, ISOSURFACE). */
+    Surface3D = "surface3d",
+    /** Live colormap/LUT applied to a raw scalar matrix. */
+    ScalarColormap = "scalarColormap",
+    /** Read back the displayed pixel matrix (getDisplayedPixelData). */
+    PixelReadback = "pixelReadback",
+    /** Server re-fetch of a higher-res crop on zoom (vs native tiling). */
+    HighDefZoom = "highDefZoom",
+    /** Per-z-plane slider over an image stack. */
+    StackSlider = "stackSlider",
+    /** Live isosurface intensity bounds (isomin/isomax) — see IIsosurfaceControls. */
+    Isosurface = "isosurface"
+}
+export interface ViewerCapabilities {
+    has(feature: ViewerFeature): boolean;
+}
+/** Build a `ViewerCapabilities` from a fixed feature set. */
+export declare function capabilitiesOf(features: Iterable<ViewerFeature>): ViewerCapabilities;

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

@@ -0,0 +1,40 @@
+import { InjectionToken } from '@angular/core';
+/**
+ * Result of an automatic cell segmenter: a per-pixel instance label map for the
+ * input image (0 = background, 1..count = instances), row-major.
+ */
+export interface CellSegmentation {
+    labels: Uint32Array;
+    width: number;
+    height: number;
+    count: number;
+}
+/**
+ * Port for an automatic (prompt-free) cell segmenter — e.g. cellpose-SAM. The
+ * library calls this on a client slide-crop of a drawn box. By default the
+ * {@link CELL_SEGMENTER} token resolves to the library's own cellpose-js-backed
+ * {@link CellposeSegmenterService} (so the toolbar Cellpose tool works out of the
+ * box), but a host can override the token to supply a different implementation
+ * (e.g. a server-side segmenter) (jit-ui#90).
+ */
+/** Progress/status callbacks for a segmentation run (all optional). */
+export interface CellSegmentProgress {
+    /** Model-download progress, 0..1 (first run only). */
+    onProgress?: (fraction: number) => void;
+    /** Human-readable phase, e.g. 'Running inference (tile 3/8)…'. */
+    onStatus?: (status: string) => void;
+}
+export interface ICellSegmenter {
+    /** Segment all cells in an RGBA image into an instance label map. */
+    segmentCells(image: {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    }, progress?: CellSegmentProgress): Promise<CellSegmentation>;
+}
+/**
+ * DI token for the automatic cell segmenter. Defaults to the in-library
+ * {@link CellposeSegmenterService} (cellpose-js, lazy-loaded); override it in the
+ * host to swap implementations.
+ */
+export declare const CELL_SEGMENTER: InjectionToken<ICellSegmenter>;

package/lib/contracts/channel-histogram-api.contract.d.ts

@@ -0,0 +1,98 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { IImageMetadata } from './image.contract';
+import { ColormapNode } from './display-types';
+/**
+ * Display state for one image channel in the Channels & Histogram pane.
+ * `min`/`max` are the display window (contrast/brightness) in raw 0..255 space;
+ * `gamma` shapes the transfer curve; `color` is the channel's display tint
+ * (used when compositing multiple channels); `visible` toggles it on/off.
+ */
+export interface IChannelState {
+    index: number;
+    name: string;
+    /** Display tint as `#rrggbb`. */
+    color: string;
+    min: number;
+    max: number;
+    gamma: number;
+    visible: boolean;
+}
+/** The standard LUT pseudo-colours (mirrors Fiji's Merge Channels palette) for
+ *  quick per-channel assignment. */
+export declare const LUT_COLORS: ReadonlyArray<{
+    name: string;
+    color: string;
+}>;
+/** A binned intensity histogram for one channel.
+ *
+ * The 8-bit client path (RGB / 8-bit grayscale, sampled from displayed tiles)
+ * leaves the native fields undefined and `bins` span 0..255. The native path
+ * (>8-bit images, from the server `/histogram` endpoint) fills `bitDepth`,
+ * `rangeMin`/`rangeMax` (the pixel-type span the bins cover) and
+ * `observedMin`/`observedMax` (the actual extremes seen), so the dialog can
+ * label the window/axis in native units. */
+export interface IHistogram {
+    /** Left edge of each bin (0..255 for the 8-bit path, native units otherwise). */
+    bins: number[];
+    /** Pixel count per bin, length = bin count. */
+    counts: number[];
+    /** Largest bin count, for y-axis scaling. */
+    max: number;
+    /** Native bit depth (8, 16, …) — present only on the native server path. */
+    bitDepth?: number;
+    /** Pixel-type range the bins span (e.g. 0..65535), native path only. */
+    rangeMin?: number;
+    rangeMax?: number;
+    /** Actual min/max pixel observed (auto-contrast seed), native path only. */
+    observedMin?: number;
+    observedMax?: number;
+}
+/**
+ * Public, implementation-agnostic surface the Channels & Histogram pane (an
+ * external consumer of the visualization package) depends on. It exposes the
+ * per-channel display window/gamma/visibility, an intensity histogram computed
+ * from the currently-displayed pixels, and the LUT/colormap controls that used
+ * to live in the toolbar. The pane injects this via {@link CHANNEL_HISTOGRAM_API}
+ * (bound to the concrete `RoutingVisualizerService` with `useExisting`) so it
+ * never reaches the implementation. Every setter live-updates whichever backend
+ * (Plotly or OpenSeadragon) is on screen.
+ */
+export interface IChannelHistogramApi {
+    /** The channels of the current image (1 for grayscale, 3 for RGB). */
+    getChannels$(): Observable<IChannelState[]>;
+    /** Patch one channel's state (window/gamma/visibility/color); live-updates. */
+    setChannelState(index: number, partial: Partial<IChannelState>): void;
+    /** Auto-window the given channels by saturating `saturation` (0..1) of pixels
+     *  at each end of their histogram. */
+    autoContrast(indices: number[], saturation: number): void;
+    /** Reset the given channels to their derived defaults: full display range
+     *  (0..255), gamma 1, and the channel's default tint colour. */
+    resetContrast(indices: number[]): void;
+    /** Binned histogram for a channel from the displayed pixels, or null when no
+     *  image/pixels are available. Synchronous 8-bit path (used by auto-contrast). */
+    getHistogram(channelIndex: number, bins: number): IHistogram | null;
+    /** Histogram for a channel as an async stream: emits the **native** bit-depth
+     *  histogram (from the server) for >8-bit images, else the 8-bit client
+     *  histogram. The dialog uses this so 16-bit stacks get a true distribution. */
+    getHistogram$(channelIndex: number, bins: number): Observable<IHistogram | null>;
+    getColormap(): Observable<ColormapNode | null>;
+    setColormap(colormap: ColormapNode): void;
+    getColormapOptions(): ColormapNode[];
+    getReverseScale(): Observable<boolean>;
+    setReverseScale(reverse: boolean): void;
+    getGrayscale$(): Observable<boolean>;
+    setGrayscale(on: boolean): void;
+    getInvert$(): Observable<boolean>;
+    setInvert(on: boolean): void;
+    getImageMeta(): Observable<IImageMetadata[]>;
+    /** Export the displayed image — composited with the current per-channel
+     *  pseudo-colours / window / colormap — as a publication-ready PNG download. */
+    exportComposite(): void;
+    /** Export the underlying image data — all (or the visible) channels at native
+     *  bit depth — as a data-preserving multi-band TIFF download. Server-side, so
+     *  it keeps true 16-bit values (the PNG composite is an 8-bit figure). Only
+     *  meaningful for >8-bit images; a no-op on backends that can't provide it. */
+    exportData(): void;
+}
+export declare const CHANNEL_HISTOGRAM_API: InjectionToken<IChannelHistogramApi>;

package/lib/contracts/colormap-lut.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Colormap → RGB lookup-table builder.
+ *
+ * Lets a non-Plotly backend (OpenSeadragon) recolor grayscale pixels with the
+ * exact same colormaps the Plotly heatmap uses. The input is a colormap value
+ * straight from `COLORMAP_OPTIONS` (see plot.utilities) — the same value handed
+ * to Plotly's `colorscale` — so the two surfaces stay in lock-step.
+ *
+ * A colormap value is either:
+ *   - an array of `[stop, color]` pairs (the matplotlib `*_LUT` constants), or
+ *   - a Plotly built-in scale *name* string (e.g. 'Viridis', 'Reds').
+ * `color` may be `'rgb(r, g, b)'` or `'#rrggbb'`/`'#rgb'`.
+ */
+export type Rgb = [number, number, number];
+/**
+ * Build a 256-entry RGB lookup table from a `COLORMAP_OPTIONS` value, indexed by
+ * grayscale value 0–255. Returns null if the value can't be resolved to a scale.
+ * @param value  array of `[stop, color]` pairs, or a Plotly built-in name string
+ * @param reverse  mirror the scale (matches Plotly's `reversescale`)
+ */
+export declare function buildColormapLut(value: unknown, reverse?: boolean): Rgb[] | null;

package/lib/contracts/coordinate-transform.contract.d.ts

@@ -0,0 +1,43 @@
+import { Region } from '../models/region';
+/**
+ * The viewport math the on-canvas tools (wand, vertex eraser) need, abstracted
+ * away from any specific backend. Plotly implements it over its axis objects
+ * (`_fullLayout.xaxis/yaxis`), OpenSeadragon over its viewport API. This is what
+ * lets the tools run on either backend.
+ *
+ * "Data coordinates" are the backend's shape coordinate space: Plotly data
+ * coords for Plotly, image-pixel coords for OpenSeadragon. The tools convert
+ * data -> image-matrix using the per-image ratio they already get from the host
+ * (`getCachedImageData().ratios` / `getCachedImageRatio()`), so that division
+ * stays in the tool and the transform stays purely screen<->data.
+ */
+export interface ICoordinateTransform {
+    /** Client (mouse event) pixel -> data coordinates. */
+    clientToData(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    /** A length in data coordinates -> length in screen pixels. */
+    dataLengthToScreen(dataLength: number): number;
+    /** True once the viewport is laid out and conversions are valid. */
+    isReady(): boolean;
+}
+/** What a backend supplies so the tools can attach + convert coordinates. */
+export interface IViewportHost {
+    /** The element the tool's canvas overlay attaches to (fills the plot area). */
+    getOverlayContainer(): HTMLElement | null;
+    /** Live coordinate transform for the current viewport state. */
+    getCoordinateTransform(): ICoordinateTransform;
+}
+/**
+ * Region read/write access for the on-canvas tools, in the backend-neutral
+ * {@link Region} model — so the wand and vertex eraser operate on regions, not
+ * a backend's own shape representation. Both backends implement this by
+ * delegating to the shared RegionStore.
+ */
+export interface IRegionDataHost {
+    /** Current regions (neutral model). */
+    getRegions(): Region[];
+    /** Commit the (possibly mutated) region set; the backend renders + emits. */
+    setRegions(regions: Region[]): void;
+}

package/lib/contracts/display-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Publication-critical types that were `any` on the public contracts
+ * (refactoring plan, Step 6). Deliberately permissive — every field optional —
+ * so existing hosts (which pass PrimeNG `TreeNode`s and plain option objects)
+ * keep compiling unchanged while consumers finally get named shapes.
+ */
+/** A colormap value as Plotly understands it: a built-in scale name (e.g.
+ *  'Viridis') or an inline array of `[stop, color]` pairs. */
+export type ColormapValue = string | Array<[number, string]>;
+/** One node of the colormap selector tree (structurally compatible with the
+ *  PrimeNG `TreeNode`s the host passes): group nodes carry `children`, leaf
+ *  nodes carry the scale in `data.value` (+ a preview image in `data.src`). */
+export interface ColormapNode {
+    label?: string;
+    data?: {
+        value?: ColormapValue;
+        src?: string;
+    };
+    children?: ColormapNode[];
+}
+/** Magic-wand pixel-comparison space. */
+export type WandType = 'GRAY' | 'RGB' | 'LAB_DISTANCE';
+/** Options for the magic-wand tool (QuPath-style). */
+export interface IWandOptions {
+    type?: WandType;
+    /** Gaussian sigma applied to the patch before thresholding. */
+    sigma?: number;
+    /** Higher = stricter (smaller selection) for GRAY/RGB; higher = looser for
+     *  LAB_DISTANCE — matches QuPath. */
+    sensitivity?: number;
+    /** Square patch size in pixels (must be odd). */
+    patchSize?: number;
+    /** When true, skip blur/threshold and flood-fill at exact-match
+     *  (Cmd/Ctrl-click in QuPath). */
+    simpleMode?: boolean;
+}
+/** Options for the brush region tool (QuPath-style). */
+export interface IBrushOptions {
+    /** Brush diameter in matrix (image) pixels. */
+    size?: number;
+}