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

package/lib/region-source/worker-region-source.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A {@link RegionSource} over a GeoJSON string, parsed and tiled in the region-source Web Worker.
+ *
+ * One worker serves every open source. Where no worker can start (jsdom, SSR, a blocked worker
+ * URL) the same tables run on the main thread; if the worker dies, each source re-opens itself
+ * there from its text (which the host holds anyway: it handed it over) and carries on — whether
+ * it had a call in flight then or not (see {@link RegionSourceWorkerClient.generation}).
+ */
+import { RegionSource } from './region-source';
+import { RegionSourceRequest, RegionSourceResults } from './region-source-ops';
+import type { ReconstructOptions, SliceOutlines } from '../geometry/reconstruct';
+import type { Mesh } from 'napari-js/geometry';
+/** Makes the worker; may be async, as the default one is (it imports the factory on demand). */
+export type RegionSourceWorkerFactory = () => Worker | Promise<Worker>;
+/** Owns the region-source worker and the calls in flight on it. */
+export declare class RegionSourceWorkerClient {
+    private readonly factory?;
+    private worker;
+    private starting;
+    private unavailable;
+    private nextId;
+    private readonly pending;
+    /** The main-thread tables, once anything runs here. */
+    private local;
+    private tables;
+    /**
+     * `factory` is optional: without one the real worker module is imported on demand —
+     * dynamically, because it holds an `import.meta.url` that ts-jest's CommonJS compile
+     * rejects.
+     */
+    constructor(factory?: RegionSourceWorkerFactory | undefined);
+    /** Whether calls now run on the main thread. */
+    get inThread(): boolean;
+    /**
+     * Which table set calls run on: bumped when the worker is lost. A handle opened under another
+     * names a table that is gone (or, here, another source's), so its source must open again.
+     */
+    get generation(): number;
+    /** Run `request` in the worker, or here when there is none. */
+    call<R extends RegionSourceRequest>(request: R): Promise<RegionSourceResults[R['op']]>;
+    /** {@link call}, with the {@link generation} the request ran on. */
+    run<R extends RegionSourceRequest>(request: R): Promise<{
+        result: RegionSourceResults[R['op']];
+        generation: number;
+    }>;
+    /** Terminate the worker; calls in flight reject. */
+    dispose(): void;
+    private ensureWorker;
+    private startWorker;
+    private onReply;
+    /** Stop the worker for good: every later call runs here, every call in flight is lost. */
+    private lose;
+}
+/** The worker client every GeoJSON source shares. */
+export declare function sharedRegionSourceClient(): RegionSourceWorkerClient;
+/**
+ * Open a GeoJSON FeatureCollection string as a tiled region source. Rejects on invalid JSON or
+ * a collection without `features`.
+ */
+export declare function openGeoJsonRegionSource(text: string, client?: RegionSourceWorkerClient): Promise<RegionSource>;
+/**
+ * The 3D reconstruction of a region from its outlines on a stack (see `geometry/reconstruct`),
+ * meshed in the region-source worker (on the main thread where there is none).
+ */
+export declare function reconstructInWorker(slices: readonly SliceOutlines[], options?: ReconstructOptions, client?: RegionSourceWorkerClient): Promise<Mesh>;

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

@@ -11,6 +11,10 @@ import { IVisualizer, LoadedImage, PixelData, IntensityProfile, IIsosurfaceContr
 import { SpatialDataPort } from './contracts/ports/spatial-data.port';
 import { CanvasToolOptions, ColormapNode, IBrushOptions, IWandOptions } from './contracts/display-types';
 import { RegionStore } from './store/region-store.service';
+import { RegionSource, RegionSourceView } from './region-source/region-source';
+import type { RegionIndexPage, RegionIndexQuery } from './region-source/region-tiles';
+import type { RegionStyle } from './region-overlay/region-style';
+import type { RegionSourceOpener, RegionSourceSlices } from './store/region-source-scope';
 import { SpatialSelectionStore } from './store/spatial-selection.service';
 import { ViewerCapabilities } from './contracts/capabilities.contract';
 import { IRegionOverlay } from './contracts/region-overlay.contract';
@@ -21,7 +25,10 @@ import { NapariVisualizerService } from './implementations/napari-js/napari-visu
 import { VizConfig } from './contracts/viz-config';
 import { PlotModeViewport } from './contracts/plot-type-contribution.contract';
 import { IntensityProfileService } from './intensity/intensity-profile.service';
+import type { SectionAxis, SectionViews } from './contracts/section-view.contract';
 import * as i0 from "@angular/core";
+/** How long after the last edit the surfaces of the classes it touched are rebuilt (ms). */
+export declare const REGION_SURFACE_REBUILD_MS = 600;
 /**
  * The visualizer chain's front door: implements `IVisualizer`, `IRegionEditorApi`
  * and `IChannelHistogramApi` (bound to the `VISUALIZER` / `REGION_EDITOR_API` /
@@ -68,7 +75,57 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     private plottedFileName;
     /** The div the backends render into (every backend shares it); '' before the first plot. */
     private plotDiv;
+    /** Whether a napari volume view is the current plot type. */
+    private readonly volumeView$;
+    /** Whether the volume view's slice pane is wanted (see {@link setSliceEditor}). */
+    private readonly sliceEditor$;
+    /** Whether the volume view draws the region reconstructions through the volume. */
+    private readonly regionsThroughVolume$;
+    /** Region reconstructions built so far, by image, resolution and classes (with those classes). */
+    private readonly meshCache;
+    /** Bumped per {@link showRegionClasses3d} (and per new image), so only the latest one shows. */
+    private meshRequest;
+    /** The class groups shown in 3D, and the image they belong to. */
+    private readonly classes3d$;
+    private classes3dImage;
+    /** The groups last asked for in 3D, with their colours: what an edit's rebuild shows again. */
+    private shown3d;
+    /**
+     * Each class's fingerprint on the live slice (see classSignatures), which image and slice, and
+     * what the region sources hold (see RegionStore.getSourceStateKey). Null while nothing follows
+     * the edits (no surface built, no sections).
+     */
+    private liveClasses;
+    /** The pending rebuild of the surfaces an edit touched. */
+    private rebuildTimer;
+    private readonly regionUpdates;
+    /** The div the slice pane renders into while it is wanted (null: no split). */
+    private sliceDiv;
+    /** Whether OSD is mounted in the slice pane: region, tool and overlay calls go to it. */
+    private sliceMounted;
+    /** The image the slice pane shows. */
+    private sliceFile;
+    /** Bumped per slice-pane mount or teardown, so only the latest one lands. */
+    private sliceRequest;
+    /** The sections beside the split volume view (the planes x and y through the stack). */
+    private readonly sections;
+    /** The z plane dragged in the volume: the slice to show (see {@link getSliceDrag$}). */
+    private readonly sliceDrag$;
+    private readonly sectionSubs;
+    /** The image info and screen height of the last plot (what the slice pane mounts). */
+    private plottedInfo;
+    /** The current region import (see regionImportTicket): its id and the image it was taken for. */
+    private importTicket;
+    private plottedHeight;
     constructor(plotly: PlotlyService, osd: OpenSeadragonVisualizerService, napari: NapariVisualizerService, store: VisualizerStore, config: VizConfig, regionStore: RegionStore, selectionStore: SpatialSelectionStore, intensity: IntensityProfileService, spatialData?: SpatialDataPort | null);
+    /** A class's colour: its classification colour, else its region source's, else a default. */
+    private classColor;
+    /** The sections beside the split volume view (nulls while it is not split). */
+    getSectionViews$(): Observable<SectionViews>;
+    /** Move a section's plane to `at` (image px). */
+    setSectionPlane(axis: SectionAxis, at: number): void;
+    /** The slice picked by dragging the z plane in the volume: the host shows it (its slider). */
+    getSliceDrag$(): Observable<number>;
     private isImageType;
     /** The 2D napari types (image, region-centroid scatter, spatial omics) — a 2D fallback chain
      *  (OSD, then Plotly).
@@ -92,11 +149,27 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     private imageBackend;
     /** Backend currently on screen — what ongoing zoom/tool/region ops act on. */
     private renderer;
+    /**
+     * Backend region, tool and overlay calls act on: the slice pane's OSD while the volume view is
+     * split (regions are edited there), else the backend on screen. View calls (zoom, fit, colour,
+     * export) stay with {@link renderer}.
+     */
+    private regionBackend;
     get capabilities(): ViewerCapabilities;
     load(imageInfo: IImageInfo, zIndex: number, signal?: AbortSignal): Promise<LoadedImage>;
     /** Try OSD; on failure fall back to Plotly for this image (not permanent — see reset()). */
     private loadViaOsdThenPlotly;
     plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
+    /**
+     * Split the volume view: show the slice being edited in `div` (OpenSeadragon, with every region
+     * tool) beside the 3D view, or stop (null). Kept across re-plots of a volume view; another plot
+     * type takes the pane down and a volume view brings it back. Resolves whether the pane shows.
+     */
+    setSliceEditor(div: string | null): Promise<boolean>;
+    /** Mount (or refresh in place) OSD in the slice pane on the displayed slice. */
+    private mountSlice;
+    /** Take the slice pane's viewer down (the split stays wanted while {@link sliceDiv} is set). */
+    private unmountSlice;
     reloadAndPlot(): void;
     reset(): void;
     relayout(trueImageSize?: number[]): void;
@@ -190,9 +263,102 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** Download `regions` as GeoJSON, named after the image last plotted. */
     exportRegions(regions: Region[]): void;
     getGeoJsonString(regions: Region[]): string;
+    /** Hold a large region set as a tiled region source (see RegionStore.attachRegionSource). */
+    attachRegionSource(source: RegionSource | RegionSourceOpener, slices?: RegionSourceSlices): void;
+    importRegionSource(geoJsonStr: string): Promise<boolean>;
+    dropRegionSource(): Promise<void>;
+    /**
+     * A ticket for a region import that is about to read or decode its files: the import methods
+     * given it change nothing once it is stale — another import took a ticket since, another image
+     * was plotted, or the service was destroyed — so an import that finishes late never lands on an
+     * image it was not started for.
+     */
+    regionImportTicket(): number;
+    /** Whether `ticket` is still the current import's, on the image it was taken for. */
+    private importTicketValid;
+    private importImageKey;
+    /**
+     * Replace the image's regions and region sources with one source per slice, as an imported label
+     * volume or folder of per-slice region files gives them: `openers` by slice index, each opened
+     * the first time its slice is shown. A single image takes slice 0's. Returns how many slices
+     * have a source, or null (changing nothing) when `ticket` is stale (see
+     * {@link regionImportTicket}). The sources are marked imported, so a save writes every slice.
+     */
+    importSliceRegionSources(openers: ReadonlyMap<number, RegionSourceOpener>, ticket?: number): number | null;
+    /**
+     * Replace the image's regions and region sources with one imported source (a region set the
+     * host's server serves): over every slice of a stack when it is z-indexed, else on the slice
+     * shown, as {@link applyImageRois} lays out an image's own. Resolves false, changing nothing
+     * (and disposing the source), when the import went stale while it opened: another import, or
+     * another image (see {@link regionImportTicket}; one is taken here when `ticket` is not given).
+     */
+    importRegionSourceOpener(open: RegionSourceOpener, ticket?: number): Promise<boolean>;
+    /** Empty every slice of a stack (its regions and undo history) for regions imported over it. */
+    private enterImportedStack;
+    getRegionSourceView$(): Observable<RegionSourceView | null>;
+    getRegionSourceIndex(query: Omit<RegionIndexQuery, 'exclude'>): Promise<RegionIndexPage>;
+    selectSourceFeatures(ids: readonly string[], additive?: boolean): Promise<number[]>;
+    deleteSourceFeatures(ids: readonly string[]): void;
+    getRegionStyle$(): Observable<RegionStyle>;
+    setRegionStyle(patch: Partial<RegionStyle>): void;
+    /** Whether a napari volume (or isosurface) view is on screen: regions can be shown in 3D. */
+    getVolumeView$(): Observable<boolean>;
+    /** Whether the volume view's slice pane is wanted (it shows while a volume view is on screen). */
+    getSliceEditor$(): Observable<boolean>;
+    /** Whether the volume view draws the region reconstructions through the volume. */
+    getRegionsThroughVolume$(): Observable<boolean>;
+    /**
+     * Draw the region reconstructions through the volume (it hides none of them: surfaces inside its
+     * bright structures, an OCT's layer boundaries) or hidden behind what it shows (the default).
+     */
+    setRegionsThroughVolume(through: boolean): void;
+    /** The class groups shown in 3D on this image ([] after a switch to another image). */
+    getRegionClasses3d$(): Observable<ReadonlyArray<{
+        key: string;
+        classes: readonly string[];
+    }>>;
+    /** Hide every region surface and forget them (a build still running is dropped). */
+    private clearRegionClasses3d;
+    /** Highlight the surfaces of these group keys in the volume view (none: all as usual). */
+    highlightRegionClasses3d(keys: readonly string[]): void;
+    /** A surface clicked in the volume view with the selection tool (its group key), or none (null). */
+    getRegionPicked3d$(): Observable<{
+        key: string | null;
+        additive: boolean;
+    }>;
+    /**
+     * Show these groups of classes in the volume view as 3D reconstructions (each group one surface
+     * in its colour: an atlas structure with its substructures), and only these; [] hides them.
+     * Reconstructed from every slice's outlines at the volume's resolution, cached per image.
+     */
+    showRegionClasses3d(groups: ReadonlyArray<{
+        key: string;
+        classes: readonly string[];
+        color: string;
+        label?: string;
+    }>): Promise<void>;
+    /**
+     * The regions changed: when the live slice's regions of some classes did (an edit, an undo, not
+     * a slice or image switch), their reconstructions are stale. They are dropped, and those shown
+     * in 3D are rebuilt once the edits pause.
+     */
+    private onRegionsChanged;
+    /** Fingerprint the live slice's classes, unless already: what the next edit is compared with. */
+    private trackLiveClasses;
+    /** Which slice of which image the live regions are. */
+    private liveSliceKey;
+    /** Each class's volume over the whole stack, in px² × slices (see RegionStore.classVolumes). */
+    getClassVolumes(classes: readonly string[]): Promise<Record<string, number>>;
+    getRegionSourceClassCounts(stack?: boolean): Promise<Record<string, number>>;
+    getHiddenClasses$(): Observable<ReadonlySet<string>>;
+    setClassesHidden(classes: readonly string[], hidden: boolean): void;
+    selectRegionClasses(classes: readonly string[], additive?: boolean): Promise<void>;
+    getGeoJsonStringWithSource(regions: Region[], slice?: number): Promise<string>;
     enterStackMode(slices: Map<number, Region[]>, initialZ?: number, saveLayout?: 'combined' | 'per-slice-file'): void;
     exitStackMode(): void;
     isStackMode(): boolean;
+    /** The slice the regions are shown for (recorded outside stack mode too). */
+    getDisplaySlice(): number;
     getStackSaveLayout(): 'combined' | 'per-slice-file';
     setDisplaySlice(z: number): void;
     getSliceRegions(): Region[];
@@ -261,7 +427,8 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     getInvert$(): Observable<boolean>;
     setInvert(on: boolean): void;
     /**
-     * The active backend's region overlay. Falls back to Plotly's when the active backend
+     * The active backend's region overlay (the slice pane's while the volume view is split). Falls
+     * back to Plotly's when the active backend
      * (OSD or napari-js) is selected but a plot isn't mounted yet, so callers always get a
      * usable overlay.
      */

package/lib/section-pane/section-pane.component.d.ts

@@ -0,0 +1,47 @@
+import { AfterViewInit, EventEmitter, NgZone, OnChanges, OnDestroy } from '@angular/core';
+import type { SectionAxis, SectionView } from '../contracts/section-view.contract';
+import * as i0 from "@angular/core";
+export declare class SectionPaneComponent implements AfterViewInit, OnChanges, OnDestroy {
+    private readonly zone;
+    axis: SectionAxis;
+    view: SectionView | null;
+    /** A point clicked, in section coordinates (u across, v down). */
+    readonly pick: EventEmitter<{
+        u: number;
+        v: number;
+    }>;
+    private canvasRef;
+    private zoom;
+    private pan;
+    private press;
+    private image;
+    private resize?;
+    private frame;
+    constructor(zone: NgZone);
+    protected get axisColor(): string;
+    protected get label(): string;
+    ngAfterViewInit(): void;
+    ngOnChanges(): void;
+    ngOnDestroy(): void;
+    /** Back to the whole section, centred. */
+    fit(): void;
+    protected onWheel(e: WheelEvent): void;
+    protected onDown(e: PointerEvent): void;
+    protected onMove(e: PointerEvent): void;
+    protected onUp(e: PointerEvent): void;
+    private local;
+    /** Section units → CSS px in the pane: scale per unit across and down, and the origin. */
+    private transform;
+    private toSection;
+    /** Redraw on the next frame (outside Angular: a canvas paint needs no change detection). */
+    private draw;
+    private paint;
+    /** Each class's cut: its outlines filled and stroked, its lines drawn (a dot for one point). */
+    private paintRegions;
+    /** The other planes: across (u) and down (v), dashed in their axis colours. */
+    private paintCrosshair;
+    /** The section's image on a canvas of its own size (made again only for a new image). */
+    private imageCanvas;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SectionPaneComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SectionPaneComponent, "viz-section-pane", never, { "axis": { "alias": "axis"; "required": true; }; "view": { "alias": "view"; "required": false; }; }, { "pick": "pick"; }, never, never, true, never>;
+}

package/lib/store/class-color.util.d.ts

@@ -30,7 +30,10 @@ export declare function findPreset(label: string, set: PresetSet): ClassPreset |
  * HSL hue. Same name -> same colour, every run.
  */
 export declare function fallbackColorFor(label: string, palette: string[]): string;
-/** Resolve a colour for `label`: a matching preset's colour, else the deterministic fallback. */
+/**
+ * Resolve a colour for `label`: a matching preset's colour, else the colour an imported file
+ * gave the class, else the deterministic fallback.
+ */
 export declare function colorForLabel(label: string, set: PresetSet): string;
 /** Options for {@link applyPresetColors}. */
 export interface ApplyPresetColorsOptions {
@@ -49,8 +52,8 @@ export interface ApplyPresetColorsOptions {
 /**
  * Resolve each labelled region's colour from the preset set (jit-ui#70). The
  * presets are the source of truth: a matching preset gives the class colour,
- * an unknown class its deterministic fallback, **overriding any colour already
- * on the region** (e.g. embedded in imported GeoJSON). Unlabelled regions and
+ * an unknown class the colour an imported file gave it (`importedColors`) or else
+ * its deterministic fallback, **overriding any colour already on the region**. Unlabelled regions and
  * ones the user recoloured (`colorOverridden`) are left untouched. Unknown
  * classes are reported through `onPromote` when `autoPromote` is on.
  *

package/lib/store/class-signatures.d.ts

@@ -0,0 +1,11 @@
+import { Region } from '../models/region';
+/**
+ * A fingerprint of each class's regions (by label): their ids and geometry folded into one number
+ * per class. Two sets give the same fingerprint for a class when its regions did not change, so
+ * comparing a slice's fingerprints before and after an edit names the classes the edit touched
+ * (a recoloured or relabelled region touches its old class and its new one). Profile lines and
+ * unlabelled regions are left out: they are in no class.
+ */
+export declare function classSignatures(regions: readonly Region[]): Map<string, number>;
+/** The classes whose fingerprints differ between `before` and `after` (added and removed included). */
+export declare function changedClasses(before: ReadonlyMap<string, number>, after: ReadonlyMap<string, number>): Set<string>;

package/lib/store/region-scope-cache.d.ts

@@ -26,6 +26,8 @@ export declare class RegionScopeCache {
     private initialNonEmpty;
     /** The cache key for an image: its first URL, else its file name. */
     static imageKey(imageInfo: IImageInfo | undefined): string | undefined;
+    /** The active image's cache key (see {@link imageKey}). */
+    get activeImage(): string | undefined;
     /** True while a z-stack is loaded and regions are held per slice. */
     get stackMode(): boolean;
     /** The current display slice (zero-based; 0 outside stack mode unless set). */

package/lib/store/region-source-scope.d.ts

@@ -0,0 +1,74 @@
+import type { RegionSource } from '../region-source/region-source';
+/** Opens a region source on demand (and again after it was closed to save memory). */
+export type RegionSourceOpener = () => Promise<RegionSource>;
+/** Which slices a source serves: one slice (plane `plane` of the source), or every slice z
+ *  from the source's plane z (a z-indexed GeoJSON over a whole stack). */
+export type RegionSourceSlices = {
+    slice: number;
+    plane?: number;
+} | 'planes';
+/** The region source behind one slice: the source and which of its planes the slice shows. */
+export interface RegionSourceBinding {
+    source: RegionSource;
+    plane: number;
+}
+/** Sources held open, past which the least recently used one is closed (never the one shown). */
+export declare const OPEN_REGION_SOURCES = 6;
+/**
+ * The region sources of every image the store has seen, per slice, and per slice the ids of
+ * the source features taken out of the source (into the working set, or deleted) — those the
+ * source no longer draws and an export leaves out.
+ *
+ * Sources open lazily, the first time their slice is shown or read, and at most
+ * {@link OPEN_REGION_SOURCES} stay open: the least recently used are closed and re-opened from
+ * their opener when used again (a source's ids are stable, so what was taken stays taken). The
+ * source of the slice on screen ({@link show}) is never closed for another: a read across every
+ * slice must not close the source the viewer draws and takes from.
+ */
+export declare class RegionSourceScope {
+    private readonly images;
+    /** Open entries, least recently used first. */
+    private readonly openOrder;
+    /** The entry of the slice on screen: kept open. */
+    private shown;
+    /**
+     * Attach `open` to `image` for `slices`, replacing (and closing) what was there. `imported` names
+     * the slices it brings that a save must write (see {@link importedSlices}): for a source of one
+     * slice, that slice when non-empty; for a `'planes'` source, the slices its planes cover.
+     */
+    attach(image: string, open: RegionSourceOpener, slices: RegionSourceSlices, imported?: readonly number[]): void;
+    /** Drop every source of `image` (closing the open ones) and what was taken from them. */
+    detachImage(image: string): void;
+    /** Drop the source of one slice of `image`. */
+    detachSlice(image: string, slice: number): void;
+    /** The slice on screen (null: none): its source stays open while others are read. */
+    show(image: string | undefined, slice: number | null): void;
+    /** Whether `image` has a source for `slice`. */
+    has(image: string | undefined, slice: number): boolean;
+    /** Whether `slice` of `image` has a source of its own (not a `'planes'` source's plane). */
+    hasOwnSource(image: string | undefined, slice: number): boolean;
+    /** Every slice of `image` with a source of its own (not counting a `'planes'` source). */
+    slicesWithSource(image: string | undefined): number[];
+    /** Whether `image` has one source over all its slices. */
+    hasPlanesSource(image: string | undefined): boolean;
+    /**
+     * The source behind `slice` of `image`, opening it if needed. Resolves null when there is
+     * none, and rejects when it cannot be opened.
+     */
+    binding(image: string | undefined, slice: number): Promise<RegionSourceBinding | null>;
+    /** The ids taken from `slice`'s source. */
+    taken(image: string | undefined, slice: number): ReadonlySet<string>;
+    /** Every id taken from any slice of `image` (a `'planes'` source's ids are unique across them). */
+    allTaken(image: string | undefined): string[];
+    /** The slices of `image` whose source was imported (see {@link attach}), in order. */
+    importedSlices(image: string | undefined): number[];
+    /** The slices of `image` with anything taken from their source. */
+    slicesWithTaken(image: string | undefined): number[];
+    /** Replace the ids taken from `slice`'s source (copy-on-write: `ids` is kept as given). */
+    setTaken(image: string | undefined, slice: number, ids: ReadonlySet<string>): void;
+    private entry;
+    private imageSources;
+    private openEntry;
+    private close;
+    private closeSource;
+}