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

package/lib/visualizer/region-load.d.ts

@@ -0,0 +1,46 @@
+import type { HttpClient } from '@angular/common/http';
+import { IImageInfo } from '../contracts/image.contract';
+import { IRegionStore } from '../contracts/visualizer.contract';
+import { RegionSource } from '../region-source/region-source';
+import type { RegionSourceOpener, RegionSourceSlices } from '../store/region-source-scope';
+/** The region-store members {@link applyImageRois} writes through. A target without
+ *  `attachRegionSource` loads every ROI file as regions. */
+export type RegionLoadTarget = Pick<IRegionStore, 'importRegions' | 'enterStackMode' | 'setRegions' | 'resetUndoHistory'> & {
+    attachRegionSource?(source: RegionSource | RegionSourceOpener, slices?: RegionSourceSlices): void;
+    /** The slice shown now (what a stack's source, laid out once it opens, makes live). */
+    getDisplaySlice?(): number;
+    /** Record the slice shown (outside stack mode it only records it): see {@link applyImageRois}. */
+    setDisplaySlice?(z: number): void;
+    isStackMode?(): boolean;
+};
+/**
+ * Apply an image's saved ROIs once its render has landed, choosing the region
+ * layout from the image's shape:
+ *
+ *  - **Folder stack** (`isStack && tiled === false`, see loadSeriesAsStack): a stack
+ *    of self-contained per-slice files. Each slice-file may carry its own sibling
+ *    `<stem>.geojson` (`roiJsonStrs[z]`), but a fresh folder with none yet leaves
+ *    `roiJsonStrs` undefined — so this keys off `tiled === false`, NOT `roiJsonStrs`,
+ *    and an unannotated folder stack still enters the per-slice-file layout (saving
+ *    back one geojson per slice-file) rather than the combined one (jit-ui#93).
+ *  - **Single-file z-stack**: one sibling geojson holding every slice's regions,
+ *    indexed by QuPath's `geometry.plane.z`. Per-slice (combined) mode is entered when
+ *    the geojson actually carries slice indices, or when there is nothing yet to
+ *    author against. A legacy geojson whose regions are all on the default plane
+ *    stays global (shown on every slice), so existing single-plane annotations are
+ *    not confined to slice 0.
+ *  - **Single plane** (or that legacy global stack): one region set for the image.
+ *    Loading saved ROIs is not a user edit, so the undo history starts fresh and the
+ *    first undo cannot wipe them (jit-ui#85).
+ *
+ * Large ROI files (`minSourceChars` and up) and a server-side source (`regionSourceUrl`)
+ * become tiled region sources instead of regions; a z-indexed one serves each slice its own
+ * plane. On a single-file stack the source is opened first, to tell which: one on the default
+ * plane only stays global, as its regions would. A folder stack's sources open lazily, the first
+ * time their slice is shown.
+ *
+ * `z` is the slice shown now; entering stack mode makes it live and resets undo. `http`, the
+ * host's `HttpClient`, carries a server-side source's requests, so the host's interceptors (its
+ * auth) apply to them as to the image tiles.
+ */
+export declare function applyImageRois(info: IImageInfo, target: RegionLoadTarget, z: number, minSourceChars?: number, http?: HttpClient): void;

package/lib/visualizer/spatial-dataset-binder.d.ts

@@ -0,0 +1,74 @@
+import { Observable } from 'rxjs';
+import { IImageInfo } from '../contracts/image.contract';
+import { PlotType, PlotTypeId } from '../contracts/plot-type';
+import { SpatialDataPort } from '../contracts/ports/spatial-data.port';
+import { SpatialDataset } from '../contracts/spatial-dataset.contract';
+import { SpatialGates } from '../plot-mode/plot-type-menu';
+/** What a dataset switch asks of the viewer. */
+export interface SpatialBinderHost {
+    /** The plot-type gates changed: recompute the selector. */
+    gatesChanged(): void;
+    /** The selector's current id, and the built-in type rendered for it. */
+    selectedId(): PlotTypeId;
+    basePlotType(): PlotType;
+    /** Whether an image is loaded. */
+    hasImage(): boolean;
+    selectPlotType(type: PlotType): void;
+    /** Re-plot the current mode. */
+    replot(): void;
+    /** Publish an image as the host's current one. */
+    publishImage(info: IImageInfo): void;
+    setImageLoading(loading: boolean): void;
+    /** The switch is handled: reconcile the selection with the new gates and re-render. */
+    settled(): void;
+    detectChanges(): void;
+}
+/**
+ * Binds the viewer to the spatial-omics dataset on `SPATIAL_DATA_PORT`: the gates it
+ * puts on the plot-type selector ({@link gates}), the mode an image-less dataset opens
+ * on, and publishing a dataset's registered volume AS the image.
+ *
+ * No-op when the host provides no port — the spatial types then stay hidden.
+ */
+export declare class SpatialDatasetBinder implements SpatialGates {
+    private readonly port;
+    private readonly host;
+    /** The dataset on offer, for drawing one that brings no image. */
+    dataset: SpatialDataset | null;
+    /** A dataset is published — gates the spatial plot types; the toolbar binds it too. */
+    hasDataset: boolean;
+    /** Its observations carry a z, gating the 3D spatial mode. */
+    has3d: boolean;
+    /** It brings pixels of its own (see {@link SpatialGates.hasPixels}). */
+    hasPixels: boolean;
+    /** Dataset identity + capability shape the last emission was handled at, so a
+     *  switch between two datasets of the same shape is not mistaken for a repeat. */
+    private key;
+    /** Dataset + geometry the published volume image was built from, so a re-emitted
+     *  dataset doesn't re-fetch megabytes or reset the user's scrub. */
+    private volumeImageKey;
+    /** Blob URLs backing that image — ours to revoke. */
+    private volumeImageUrls;
+    constructor(port: SpatialDataPort | undefined, host: SpatialBinderHost);
+    /** Follow the port's dataset until `until$` emits. */
+    bind(until$: Observable<unknown>): void;
+    /** Revoke the published volume image's blob URLs (teardown). */
+    dispose(): void;
+    private onDataset;
+    /**
+     * Publish a dataset's reference volume AS the image, and open the 2D Image view on it:
+     * the slice bar scrubs z, and the contrast window, colormaps and region tools all work
+     * because the volume genuinely is the image now. The 3D cloud stays one pick away.
+     *
+     * Keyed by dataset + geometry: the dataset stream re-emits on things like a
+     * colour-column change, and rebuilding then would re-fetch the voxels and throw the
+     * user back to the middle slice.
+     */
+    private showVolumeAsImage;
+    /** Forget the published volume image so re-selecting the dataset rebuilds it. The
+     *  URLs deliberately stay alive: the host may still be displaying that image, and
+     *  revoking under it would break every later tile read. They are freed when the next
+     *  volume replaces them, or on {@link dispose}. */
+    private dropVolumeImage;
+    private revokeVolumeImageUrls;
+}

package/lib/visualizer/tool-modes.d.ts

@@ -0,0 +1,49 @@
+import { NgZone } from '@angular/core';
+import { Observable } from 'rxjs';
+import { PlotModeTools } from '../contracts/plot-type-contribution.contract';
+import { IVisualizer } from '../contracts/visualizer.contract';
+/** The backend members tool arming drives. */
+export type ToolModesTarget = Pick<IVisualizer, 'getRegionOverlay' | 'setDragMode' | 'setActiveTool' | 'setWandOptions' | 'setBrushOptions' | 'setVertexEraserRadius'>;
+/** Where the armed tool is recorded for everyone else (the shared session store). */
+export interface ActiveToolRecord {
+    setActiveTool(id: string | null): void;
+    getActiveTool$(): Observable<string | null>;
+}
+/**
+ * The armed tool mode (one at a time across the region overlay, the viewport drag
+ * modes and the on-canvas tools) and the toolbar's tool settings it arms them with.
+ */
+export declare class ToolModes {
+    private readonly target;
+    private readonly record;
+    /** Runs after every arm/disarm with the newly armed mode. */
+    private readonly armed;
+    /** The armed mode, or null. */
+    active: string | null;
+    /** Wand sensitivity — higher = stricter (smaller selection). Matches QuPath default. */
+    wandSensitivity: number;
+    /** Brush diameter in image-pixel coordinates (drives the painted disc size). */
+    brushSize: number;
+    /** Vertex eraser radius in image-pixel coordinates. */
+    vertexEraserRadius: number;
+    /** The toolbar tools a contributed plot mode may arm. Calls can come from outside
+     *  Angular, hence the zone. */
+    readonly plotModeTools: PlotModeTools;
+    /** Class the brush paints while a plot mode armed it; null = plain brush. */
+    private brushClass;
+    constructor(target: ToolModesTarget, record: ActiveToolRecord, zone: NgZone, 
+    /** Runs after every arm/disarm with the newly armed mode. */
+    armed: (mode: string | null) => void, markForCheck: () => void);
+    /** A tool picked by the user (always the plain tool, never a plot mode's brush class);
+     *  re-picking the armed one disarms it. */
+    toggle(mode: string): void;
+    /** Arm `mode` (or nothing) across every tool. */
+    apply(mode: string | null): void;
+    /** Disarm whatever is armed and clear every tool mode (a plot-type switch). */
+    deactivate(): void;
+    setWandSensitivity(value: number | undefined): void;
+    setBrushSize(value: number | undefined): void;
+    setVertexEraserRadius(value: number | undefined): void;
+    /** The options a canvas tool is armed with, from the toolbar's settings. */
+    private options;
+}

package/lib/visualizer/viewer-shortcuts.d.ts

@@ -0,0 +1,71 @@
+import { NgZone } from '@angular/core';
+/** What the shortcuts drive: the viewer's actions and the state they gate on. */
+export interface ShortcutHost {
+    /** Id of the plot div; the wheel and the context menu act only over it. */
+    readonly plotDivName: string;
+    /** The viewer's own element (toolbar + plot); its keys are scoped to it. Falls back
+     *  to the plot div when absent. */
+    readonly hostElement?: HTMLElement | null;
+    /** The armed tool — SAM point mode takes Enter / Escape. */
+    activeDragMode(): string | null;
+    /** ←/→ step the slice: a loaded stack in the Image view. */
+    canStepSlice(): boolean;
+    /** The wheel steps the zoom: a 2D view whose renderer does not read the wheel itself. */
+    wheelZooms(): boolean;
+    stepSlice(delta: number): void;
+    /** SAM point mode: commit (Enter) or discard (Escape) the prompt. */
+    resolveSamPrompt(commit: boolean): void;
+    undo(): void;
+    redo(): void;
+    deleteRegion(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    toggleDragMode(mode: string): void;
+    openContextMenu(event: MouseEvent): void;
+}
+/**
+ * The viewer's keyboard, wheel and context-menu handling: one window listener each,
+ * registered OUTSIDE the Angular zone (zone-patched, every event anywhere in the host
+ * app ran app-wide change detection) and re-entering it only to act.
+ *
+ * Keys: ←/→ step the slice; Enter/Escape resolve a SAM point prompt; Ctrl/Cmd+Z undo,
+ * Ctrl/Cmd+Shift+Z or +Y redo; bare Delete/Backspace/d delete the selected region,
+ * +/= and -/_ zoom, and single letters toggle tools (`TOOL_KEYS`). Any other
+ * modified key is left to the browser (Cmd/Ctrl+D must not delete a region).
+ *
+ * Keys are per viewer: with two live viewers (a main view and a pipeline preview)
+ * one Delete must not delete in both. A key goes to the viewer that holds focus, or
+ * — focus elsewhere — to the viewer the pointer last moved over; any other viewer
+ * ignores it (review CORE-2).
+ */
+export declare class ViewerShortcuts {
+    private readonly host;
+    private readonly zone;
+    /** Every attached instance, to find the one holding focus. */
+    private static readonly live;
+    /** The viewer the pointer last moved over. */
+    private static lastHovered;
+    private readonly listeners;
+    constructor(host: ShortcutHost, zone: NgZone);
+    /** Register the window listeners (outside the zone). */
+    attach(): void;
+    /** Remove every listener {@link attach} added. */
+    detach(): void;
+    private listen;
+    private contains;
+    /** Whether this viewer takes keys now: it holds focus, or nothing does and the
+     *  pointer was last over it. */
+    private ownsKeys;
+    private overPlot;
+    private run;
+    private onContextMenu;
+    private onWheel;
+    private onKeydown;
+    /**
+     * ←/→ step the slice in the Image view, the same way the slider does — only for a
+     * loaded stack, and not while a form field or the slider itself has focus (it
+     * handles arrows natively; stepping here too would double-step). Up/Down are left
+     * to OpenSeadragon (panning).
+     */
+    private isSliceStepKey;
+}

package/lib/visualizer/visualizer-context-menu.d.ts

@@ -0,0 +1,55 @@
+import { MenuItem } from 'primeng/api';
+import { PlotType } from '../contracts/plot-type';
+import { Region } from '../models/region';
+/** What the right-click menu is built from: the view, the armed modes and the regions. */
+export interface ContextMenuState {
+    /** 2D view (region tools, step zoom) vs a 3D scene (camera modes). */
+    isHeatmap: boolean;
+    /** The built-in type on screen; the Image view adds the vertex and Bézier items. */
+    basePlotType: PlotType;
+    activeDragMode: string | null;
+    activeSurface3dMode: string;
+    /** Every region on the image (intensity-profile lines included). */
+    regions: Region[];
+    /** The selection, as indices into {@link regions}. */
+    selectedIndices: number[];
+    /** Whether a region is a multi-part region that can be split back into parts. */
+    canUngroup(region: Region): boolean;
+}
+/** What the menu's items do (the viewer's own toolbar handlers). */
+export interface ContextMenuActions {
+    autoscaleImage(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    toggleDragMode(mode: string): void;
+    toggleSurface3dMode(mode: string): void;
+    resetSurfaceCamera(): void;
+    selectAllRegions(): void;
+    mergeRegions(): void;
+    ungroupRegions(): void;
+    inverseRegions(): void;
+    simplifyRegions(thresholdPx: number): void;
+    openSimplifyDialog(): void;
+    toBezierRegion(): void;
+    toPolygonRegion(): void;
+    deleteRegion(): void;
+}
+/** The live regions at `indices` (stale indices dropped). */
+export declare function regionsAt(regions: Region[], indices: number[]): Region[];
+/** Regions eligible for set-ops: closed areas (rect / closed polygon / multi-polygon),
+ *  excluding intensity-profile lines. */
+export declare function opEligible(regions: Region[]): Region[];
+/**
+ * The right-click menu: the selected-region actions lead (2D only), then the
+ * viewport and tool toggles for a 2D view, or the camera modes for a 3D scene. The
+ * armed mode is highlighted.
+ */
+export declare function buildContextMenu(state: ContextMenuState, actions: ContextMenuActions): MenuItem[];
+/**
+ * Immediate region actions on the current selection (jit-ui#85): merge, ungroup,
+ * inverse, simplify, the Bézier conversions, and delete — the one-shot geometry
+ * transforms, grouped apart from the tool/mode toggles and shown only when something
+ * is selected. Each item is gated on what the selection supports. "Select all" leads
+ * whenever the image has regions.
+ */
+export declare function buildRegionActionItems(state: ContextMenuState, actions: ContextMenuActions): MenuItem[];

package/lib/visualizer/volume-sections.d.ts

@@ -0,0 +1,64 @@
+import { Observable } from 'rxjs';
+import type { IChannelState } from '../contracts/channel-histogram-api.contract';
+import type { Colormap } from 'napari-js';
+import type { SectionAxis, SectionViews } from '../contracts/section-view.contract';
+import type { SliceOutlines } from '../geometry/reconstruct';
+import type { VolumeVoxelsOnScreen } from '../implementations/napari-js/napari-scene';
+import type { SlicePlanes } from '../implementations/napari-js/napari-volume-slice-planes';
+/** What the sections are cut from and shown with. */
+export interface VolumeSectionsDeps {
+    /** The volume on screen as assembled, or null (not a volume view, or not assembled yet). */
+    volume(): VolumeVoxelsOnScreen | null;
+    /** The image the volume is of: another one drops the outlines read and puts the planes back. */
+    image(): string | undefined;
+    /** Show the planes in the volume (null: hide one). */
+    showPlanes(planes: SlicePlanes): void;
+    /** Every class's outlines on every slice (see RegionStore.outlinesByClass). */
+    outlinesByClass(level: number): Promise<Map<string, SliceOutlines[]>>;
+    isClassHidden(label: string): boolean;
+    colorOf(label: string): string;
+    channelStates(): IChannelState[];
+    /** The colormap the 3D view draws a channel with: its tint in a multichannel volume, else the volume's. */
+    colormap(channel: IChannelState | undefined, multichannel: boolean): Colormap;
+    invert(): boolean;
+    /** The slice shown and edited. */
+    slice(): number;
+}
+/**
+ * The sections beside a split volume view: the planes x = const and y = const (image px), each cut
+ * from the assembled volume as an image, displayed like the 2D view displays a slice (the channel
+ * windows, tints and invert), with every class's outlines cut by the same plane and the other two
+ * planes as a crosshair. Recut when a plane moves, the slice changes, the regions or their
+ * visibility change, the display changes or the volume is assembled again — once per frame at most.
+ */
+export declare class VolumeSections {
+    private readonly deps;
+    private readonly views$;
+    private open;
+    private planes;
+    /** The image the planes and outlines are of. */
+    private image;
+    /** Every class's outlines at a level, read and indexed once until the regions change. */
+    private outlines;
+    private scheduled;
+    /** Bumped per cut, so a cut that waited on the outlines is dropped when a newer one starts. */
+    private request;
+    constructor(deps: VolumeSectionsDeps);
+    /** Both sections as they are cut; nulls while closed. */
+    getViews$(): Observable<SectionViews>;
+    /** Show the sections (their planes through the middle of the image at first). */
+    start(): void;
+    stop(): void;
+    /** Move a section's plane to `at` (image px; clamped into the image). */
+    setPlane(axis: SectionAxis, at: number): void;
+    /** The planes as they are (image px), the z plane being the slice. */
+    getPlanes(): SlicePlanes;
+    /** The regions changed (an edit): their outlines are read again, once the edits pause. */
+    regionsChanged(): void;
+    /** Something the sections show changed (the slice, the display, the visible classes, the volume). */
+    schedule(): void;
+    private cut;
+    private view;
+    /** The volume's channels as displayed now. */
+    private voxels;
+}