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

package/lib/toolbar/tool-kit/canvas-tool.d.ts

@@ -0,0 +1,86 @@
+import { IViewportHost, IRegionDataHost } from '../../contracts/coordinate-transform.contract';
+import type { CanvasToolId } from '../../contracts/display-types';
+import type { CachedFrame } from './frame-pixels';
+/**
+ * The pixel readback a backend (Plotly, OpenSeadragon or napari-js) hands the
+ * canvas tools for sampling. Returned by {@link CanvasToolHost.getCachedImageData}.
+ */
+export interface CachedImageData {
+    /**
+     * One frame per stack slice (length 1 for non-stack images): a nested `[y][x]`
+     * matrix (Plotly) or a packed RGBA readback (OpenSeadragon, napari-js). Read
+     * them through `framePixels()` (`tool-kit/frame-pixels`).
+     */
+    frames: CachedFrame[];
+    /** Image-pixel width of each frame matrix. */
+    width: number;
+    /** Image-pixel height of each frame matrix. */
+    height: number;
+    /**
+     * Data coords per matrix pixel: `[x, y]`. OSD and napari report distinct
+     * ratios for a non-square viewport; a single entry applies to both axes
+     * (see `MatrixFrame`).
+     */
+    ratios: number[];
+    /** Whether each nested frame is a 2-D scalar matrix (true) or 3-channel RGB
+     *  (false). Packed frames always read as RGB. */
+    isGrayscale: boolean;
+    /**
+     * Data-coords of matrix pixel (0,0)'s top-left corner. Lets the matrix be a
+     * *crop* of the data space rather than starting at the origin — e.g. the OSD
+     * backend samples the currently rendered viewport, so when zoomed in the matrix
+     * covers only the visible sub-region at screen resolution. Defaults to 0.
+     * matrix = (data - origin) / ratio, and matrix pixel (i, j) covers
+     * `[i, i + 1) × [j, j + 1)` on every backend: a click floors to its pixel, and
+     * traced outlines run along pixel edges.
+     */
+    originX?: number;
+    originY?: number;
+}
+/**
+ * Everything a canvas tool needs from the backend it runs on — one interface
+ * for every tool (it replaces the wand's, the vertex eraser's and the
+ * zoom-to-box's own host types). Keeping it explicit keeps the dependency
+ * one-way: the tools never import a backend.
+ */
+export interface CanvasToolHost extends IViewportHost, IRegionDataHost {
+    /** Pixel data for sampling, and the data↔matrix frame. null when no image is loaded yet. */
+    getCachedImageData(): CachedImageData | null;
+    /** Index of the currently visible frame in a stack (0 for non-stack). */
+    getActiveFrameIndex(): number;
+    /** Current image's filename — stamped onto new shapes for filtering. */
+    getFileName(): string | undefined;
+    /** Default stroke colour for new shapes. */
+    getShapeColor(): string;
+    /**
+     * Zoom-to-box: an overlay-pixel point (relative to the overlay container's
+     * top-left) in the backend's data coordinates.
+     */
+    pixelToData?(px: number, py: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Zoom-to-box: apply the selected rectangle, ordered `[xMin, xMax, yMax, yMin]`.
+     * Plotly re-fetches or relayouts its axes; OpenSeadragon and napari-js fit the
+     * view to the image rectangle.
+     */
+    applyZoomToBox?(dataBox: number[]): void;
+}
+/**
+ * An on-canvas tool (wand, brush, vertex eraser, zoom-to-box, SAM point). One
+ * instance per backend, owned by that backend's `CanvasToolManager`, so no
+ * in-progress state (a stroke, SAM points) is shared between backends.
+ */
+export interface ICanvasTool<O = unknown> {
+    readonly id: CanvasToolId;
+    /** Arm the tool on `host` (lay its overlay over the plot). Arming the armed
+     *  tool again only applies `options`; it keeps the work in progress. */
+    activate(host: CanvasToolHost, options?: O): void;
+    /** Remove the overlay and drop the work in progress. */
+    deactivate(): void;
+    /** Live option updates (also while disarmed: they apply to the next arming). */
+    setOptions?(options: O): void;
+    /** Drop the work in progress but stay armed (undo/redo, image switch). */
+    reset?(): void;
+}

package/lib/toolbar/tool-kit/frame-pixels.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The pixel frames a backend hands the canvas tools (`CachedImageData.frames`),
+ * and the one accessor every tool reads them through (wand patch extraction,
+ * SAM encoder input, Cellpose crop).
+ *
+ * A frame is either
+ * - **nested** — `[y][x]` rows of grayscale values or `[r, g, b]` tuples, which
+ *   is what the Plotly backend caches (its frames double as the heatmap data and
+ *   may hold raw, non-8-bit intensities), or
+ * - **packed** — a row-major RGBA `Uint8ClampedArray`, which is what a canvas or
+ *   GPU readback already is. OpenSeadragon and napari-js hand theirs over as-is
+ *   instead of building one JS array per pixel (RT-17, OSD-PLOTLY-12,
+ *   NAPARI-SVC-23).
+ */
+/** A row-major RGBA readback (alpha is ignored). */
+export interface PackedFrame {
+    readonly data: Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly channels: 4;
+}
+/** `[y][x]` grayscale values, or `[y][x]` `[r, g, b]` tuples. */
+export type NestedFrame = number[][] | number[][][];
+/** One frame of `CachedImageData.frames`. */
+export type CachedFrame = NestedFrame | PackedFrame;
+/** Whether `frame` is the packed RGBA form. */
+export declare function isPackedFrame(frame: unknown): frame is PackedFrame;
+/** Wrap a row-major RGBA readback as a frame, without copying it. */
+export declare function packedFrame(data: Uint8ClampedArray, width: number, height: number): PackedFrame;
+/** Reads one frame's pixels whatever its form. */
+export interface FramePixels {
+    /**
+     * Pixel (x, y) as RGB in `out[0..2]` (a grayscale value is replicated, and
+     * kept unclamped). False — `out` untouched — outside the frame or for a
+     * missing pixel. A packed frame always reads as RGB.
+     */
+    rgb(x: number, y: number, out: number[]): boolean;
+    /**
+     * `w` pixels of row `y` from column `x0`, as opaque RGBA into `dst` from
+     * offset `o`. Missing pixels become opaque black.
+     */
+    rgbaRow(y: number, x0: number, w: number, dst: Uint8ClampedArray, o: number): void;
+}
+/** The accessor for `frame`; `isGrayscale` describes a nested frame's cells. */
+export declare function framePixels(frame: CachedFrame | undefined, isGrayscale: boolean): FramePixels;

package/lib/toolbar/tool-kit/mask-stroke-editor.d.ts

@@ -0,0 +1,125 @@
+import { BBoxMask } from '../../geometry/raster';
+import { IRegionDataHost } from '../../contracts/coordinate-transform.contract';
+import { Polygon, Region } from '../../models/region';
+import { MatrixFrame } from './matrix-frame';
+import type { CachedImageData, CanvasToolHost } from './canvas-tool';
+/** The readback size the stroke is painted against (the rasterizer's clip window). */
+export interface StrokeImage {
+    width: number;
+    height: number;
+}
+/** Where a wand or brush pointer tick lands (see {@link MaskStrokeEditor.beginTick}). */
+export interface StrokeTick {
+    /** The host's readback. */
+    cached: CachedImageData;
+    /** The current regions, mutated by the tick and committed once. */
+    regions: Region[];
+    /** The readback's data↔matrix frame. */
+    frame: MatrixFrame;
+    /** The matrix point under the pointer, inside the readback. */
+    mx: number;
+    my: number;
+}
+/** How a commit turns traced pieces into regions. */
+export interface StrokeCommitOptions {
+    /** The tick erased (Shift): a stroke erased to nothing removes its regions. */
+    erase: boolean;
+    /** A brand-new region for a piece no existing region owns. */
+    newRegion(bounds: Polygon): Region;
+    /** Fields applied on top of an edited region (e.g. a painted class colour). */
+    editPatch?: Partial<Region>;
+    /** Class label given to an edited region that has none, so tool output is never unlabeled. */
+    defaultLabel: string;
+}
+/**
+ * The bbox-relative mask accumulator shared by the wand and the brush: adopt a
+ * region under the cursor, grow the mask, fold touching regions in, then trace
+ * every connected piece (with holes) and commit them.
+ *
+ * The accumulator survives mouseup so the next stroke extends the same region
+ * (QuPath behaviour). It is dropped when the view changes (its matrix coords
+ * are tied to the readback frame, jit-ui#102) and when its regions changed
+ * outside the tool (undo, Region Editor, segmentation, eraser — RT-2).
+ *
+ * Commits never mutate a store instance and never drop metadata: an edited
+ * region is a copy of the original with new bounds (RT-5). An erase that cuts a
+ * region in two keeps both pieces and a donut keeps its holes (RT-3).
+ */
+export declare class MaskStrokeEditor {
+    /** The accumulated mask, in matrix coords of {@link frameSig}'s frame. */
+    stroke: BBoxMask | null;
+    /** Id of the region the stroke edits (null = a fresh region); for a split,
+     *  the largest piece. */
+    regionId: number | null;
+    /** Ids of the extra pieces an erase split off, reused across ticks so they
+     *  keep stable identities. */
+    private extraIds;
+    /** The bounds objects the stroke last committed or adopted, one per region it
+     *  owns. Once any of them is no longer held by a region, the stroke is stale. */
+    private lastCommitted;
+    /** The region the stroke adopted (or first merged in): its metadata carries
+     *  over to the committed pieces even after a merge removed it from the list. */
+    private template;
+    private frameSig;
+    /** Drop the stroke and everything tied to it. */
+    reset(): void;
+    /**
+     * Start a wand or brush tick at pointer `e`: read the host's readback and
+     * regions, drop a stale stroke ({@link invalidateIfStale}) or one from another
+     * view ({@link syncFrame}), and map the pointer into the readback's matrix.
+     * Null when there is no readback or ready transform, or the pointer is off it.
+     */
+    beginTick(host: CanvasToolHost, e: {
+        clientX: number;
+        clientY: number;
+    }): StrokeTick | null;
+    /** Drop a stroke whose regions were undone, deleted or replaced outside the
+     *  tool: re-committing it would bring the old shapes back (RT-2). */
+    invalidateIfStale(regions: Region[]): void;
+    /** Drop a stroke built at a different view (zoom/pan): re-committing it would
+     *  rescale the region by the zoom factor (jit-ui#102). */
+    syncFrame(frame: MatrixFrame): void;
+    /** True if matrix point (mx, my) is painted in the stroke. */
+    contains(mx: number, my: number): boolean;
+    /**
+     * Make the stroke's bbox cover [x0,x1)×[y0,y1) (matrix px), creating an empty
+     * stroke or growing (and copying) the existing one. False for an empty box.
+     */
+    ensureCovers(x0: number, y0: number, x1: number, y1: number): boolean;
+    /**
+     * If matrix point (mx, my) lies inside a region `accept`s (topmost first, not
+     * in a hole), rasterize it into the stroke so this stroke extends it.
+     */
+    adoptAt(regions: Region[], mx: number, my: number, frame: MatrixFrame, image: StrokeImage, accept?: (r: Region) => boolean): boolean;
+    /**
+     * Fold every region `accept`s whose raster overlaps the stroke into it and
+     * remove it from `regions` (merge-on-touch). Repeats until nothing changes so
+     * chained merges resolve. With no region yet, the first merged region's
+     * identity and metadata are adopted.
+     */
+    mergeTouching(regions: Region[], frame: MatrixFrame, image: StrokeImage, accept?: (r: Region) => boolean): void;
+    /**
+     * Trace every connected piece of the stroke (holes included) and commit them:
+     * the largest keeps the stroke's region, further pieces (from an erase that
+     * split it) become their own regions with stable ids across ticks. An erase
+     * that leaves nothing removes the stroke's regions.
+     */
+    commit(regions: Region[], frame: MatrixFrame, host: IRegionDataHost, opts: StrokeCommitOptions): void;
+    /** Remove the stroke's region(s) and reset — an erase deleted every pixel. */
+    dropActive(regions: Region[], host: IRegionDataHost): void;
+    /** The region with `id` in `regions`, or the adopted/merged template when a
+     *  merge already removed it from the list. */
+    private owner;
+    /** Replace `existing` in place (or append it if a merge removed it). */
+    private upsert;
+    /** The fields an edit sets on `existing`: the tool's patch, plus a default label. */
+    private patchFor;
+    private insert;
+    /**
+     * A region's closed ring and holes in matrix coords, or null when it can't be
+     * edited as a mask: not a closed polygon (rectangles, polylines,
+     * multi-polygons), or too large to rasterize faithfully at this zoom — editing
+     * would clip or down-quantize it and bring it back rescaled (jit-ui#102).
+     */
+    private editableRing;
+}

package/lib/toolbar/tool-kit/matrix-frame.d.ts

@@ -0,0 +1,40 @@
+import type { CachedImageData } from './canvas-tool';
+/**
+ * The mapping between a backend's data coordinates and the pixel matrix of a
+ * cached readback (`CachedImageData`): `matrix = (data - origin) / ratio` per
+ * axis. OSD and napari publish distinct `[ratioX, ratioY]`, so rows must use
+ * the Y ratio; a single ratio is used for both axes when only one is supplied.
+ */
+export declare class MatrixFrame {
+    /** Data units per matrix column. */
+    readonly rx: number;
+    /** Data units per matrix row. */
+    readonly ry: number;
+    /** Data X of matrix column 0. */
+    readonly ox: number;
+    /** Data Y of matrix row 0. */
+    readonly oy: number;
+    private constructor();
+    /** The frame of a readback. Missing/zero ratios fall back to 1, missing origins to 0. */
+    static from(cached: Pick<CachedImageData, 'ratios' | 'originX' | 'originY'>): MatrixFrame;
+    /** Identity of the frame: a stroke built in matrix coords is only valid while this is unchanged. */
+    get sig(): string;
+    toMatrixX(x: number): number;
+    toMatrixY(y: number): number;
+    toDataX(mx: number): number;
+    toDataY(my: number): number;
+    /** A ring (parallel arrays) from data to matrix coords. */
+    ringToMatrix(xs: number[], ys: number[]): {
+        xs: number[];
+        ys: number[];
+    };
+    /** A ring (parallel arrays) from matrix to data coords. */
+    ringToData(xs: number[], ys: number[]): {
+        xs: number[];
+        ys: number[];
+    };
+    /** Hole rings (`[[x, y], …]`) from data to matrix coords. */
+    holesToMatrix(holes: number[][][] | undefined): number[][][] | undefined;
+    /** Hole rings (`[[x, y], …]`) from matrix to data coords. */
+    holesToData(holes: number[][][] | undefined): number[][][] | undefined;
+}

package/lib/toolbar/tool-kit/tool-overlay.d.ts

@@ -0,0 +1,60 @@
+/** Pointer callbacks of an on-canvas tool. */
+export interface ToolOverlayHandlers {
+    /** Primary-button press (other buttons are ignored). The pointer is captured,
+     *  so the drag keeps reporting moves and its release outside the canvas. */
+    down?(e: PointerEvent): void;
+    /** Every move, pressed or hovering. */
+    move?(e: PointerEvent): void;
+    /** Release, cancel, or leaving the canvas without a capture. */
+    up?(e: PointerEvent): void;
+    /** The canvas backing store was resized (its contents were cleared). */
+    resize?(): void;
+}
+/**
+ * The transparent canvas an on-canvas tool (wand, brush, vertex eraser,
+ * zoom-to-box, SAM point) lays over the plot to take the pointer:
+ *
+ * - absolute, 100 % of the container, above the renderer (z-index 100);
+ * - pointer events (mouse, pen, touch) with pointer capture, so a drag that
+ *   leaves the canvas keeps going instead of ending at the edge;
+ * - only the primary button starts a gesture;
+ * - a backing store sized to the container × devicePixelRatio and kept in step
+ *   by a ResizeObserver, so drawing stays sharp and aligned after a panel or
+ *   window resize (RT-31). {@link context} draws in CSS pixels.
+ */
+export declare class ToolOverlayCanvas {
+    private canvas;
+    private handlers;
+    private resizeObserver?;
+    private readonly listeners;
+    /** The overlay canvas while attached. */
+    get element(): HTMLCanvasElement | null;
+    get attached(): boolean;
+    /** Width / height in CSS pixels. */
+    get cssWidth(): number;
+    get cssHeight(): number;
+    /** Lay the canvas over `container` (no-op when already attached). */
+    attach(container: HTMLElement, handlers: ToolOverlayHandlers, cursor?: string): HTMLCanvasElement;
+    /** Remove the canvas and its listeners (no-op when detached). */
+    detach(): void;
+    /** The 2D context, scaled so drawing coordinates are CSS pixels. */
+    context(): CanvasRenderingContext2D | null;
+    /** Clear the whole canvas. */
+    clear(): void;
+    /** An event's position relative to the canvas, in CSS pixels. */
+    toLocal(e: {
+        clientX: number;
+        clientY: number;
+    }): {
+        x: number;
+        y: number;
+    };
+    private onDown;
+    private onUp;
+    /** Leaving ends a drag only when nothing captured the pointer (a captured
+     *  drag continues outside the canvas until release). */
+    private onLeave;
+    /** Size the backing store to the container × DPR. True when it changed. */
+    private fit;
+    private dpr;
+}

package/lib/toolbar/tool-kit/undo-gesture.d.ts

@@ -0,0 +1,17 @@
+/** The part of RegionStore a tool needs to make one drag one undo step. */
+export interface UndoGestureTarget {
+    beginGesture(): void;
+    endGesture(): void;
+}
+/**
+ * Brackets one pointer drag as a single undo step on the region store (RT-12):
+ * `begin()` on pointer-down, `end()` on pointer-up/leave or deactivation.
+ * Idempotent, so every exit path can call `end()`. A no-op without a target.
+ */
+export declare class UndoGesture {
+    private readonly target;
+    private open;
+    constructor(target: UndoGestureTarget | null | undefined);
+    begin(): void;
+    end(): void;
+}

package/lib/toolbar/tool-slider/tool-slider.component.d.ts

@@ -0,0 +1,33 @@
+import { EventEmitter } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * A labelled toolbar slider: label, p-slider, value readout. Used for the
+ * brush size, wand sensitivity, vertex-eraser radius and the isosurface band
+ * (`range`). Presentational: the host owns the value.
+ */
+export declare class ToolSliderComponent {
+    /** The label before the slider. */
+    label: string;
+    /** A number, or `[low, high]` with {@link range}. */
+    value: number | number[];
+    /** Lower bound of the slider. */
+    min: number;
+    /** Upper bound of the slider. */
+    max: number;
+    /** Slider step. */
+    step: number;
+    /** A two-handle range slider: {@link value} is `[low, high]`. */
+    range: boolean;
+    /** Tooltip (HTML). */
+    tooltip: string;
+    /** The readout after the slider. */
+    valueText: string;
+    /** Slider moved: its value (or values with {@link range}); PrimeNG may report none. */
+    valueChange: EventEmitter<number | number[] | undefined>;
+    protected onChange(event: {
+        value?: number;
+        values?: number[];
+    }): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ToolSliderComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ToolSliderComponent, "toolbar-tool-slider", never, { "label": { "alias": "label"; "required": false; }; "value": { "alias": "value"; "required": false; }; "min": { "alias": "min"; "required": false; }; "max": { "alias": "max"; "required": false; }; "step": { "alias": "step"; "required": false; }; "range": { "alias": "range"; "required": false; }; "tooltip": { "alias": "tooltip"; "required": false; }; "valueText": { "alias": "valueText"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+}

package/lib/toolbar/toolbar-help-dialog/toolbar-help-dialog.component.d.ts

@@ -0,0 +1,24 @@
+import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
+import { ToolbarDialogToolContribution, ToolbarToolContribution } from '../../contracts/toolbar-tool.contract';
+import * as i0 from "@angular/core";
+/**
+ * The plotting toolbar's help dialog: static documentation of every tool, plus
+ * the help each contributed tool brings.
+ */
+export declare class ToolbarHelpDialogComponent implements OnChanges {
+    /** The dialog is open. */
+    visible: boolean;
+    /** The dialog was closed (`false`); two-way with {@link visible}. */
+    visibleChange: EventEmitter<boolean>;
+    /** Contributed no-prompt tools (their help entries are listed). */
+    contributedTools: ToolbarToolContribution[];
+    /** Contributed dialog tools (their help entries are listed). */
+    dialogTools: ToolbarDialogToolContribution[];
+    /** Contributed tool names for the prompted/no-prompt contrast, e.g.
+     *  "YOLO, Retinal layers". Empty when nothing is registered, which is why
+     *  the sentence that uses it is itself conditional. */
+    protected contributedToolNames: string;
+    ngOnChanges(changes: SimpleChanges): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ToolbarHelpDialogComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarHelpDialogComponent, "toolbar-help-dialog", never, { "visible": { "alias": "visible"; "required": false; }; "contributedTools": { "alias": "contributedTools"; "required": false; }; "dialogTools": { "alias": "dialogTools"; "required": false; }; }, { "visibleChange": "visibleChange"; }, never, never, true, never>;
+}