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

package/lib/region-import/open-annotations.d.ts

@@ -0,0 +1,73 @@
+import type { IImageInfo } from '../contracts/image.contract';
+import type { RegionSource } from '../region-source/region-source';
+import { LabelClasses } from './label-classes';
+import { Gunzip } from './label-volume';
+import { LabelStack } from './ome-zarr-labels';
+import { RegionImportFile } from './region-import';
+import { Inflate } from './zarr-codecs';
+import { InflateRaw } from './zip';
+/** The longest side an image built for annotations may have: OpenSeadragon's non-tiled limit. */
+export declare const ANNOTATION_IMAGE_MAX_DIM = 8192;
+/** Opens a slice's region source (again, after the store closed it). */
+type Opener = () => Promise<RegionSource>;
+/** Decoders, injectable for tests and workers (defaults: the platform's streams). */
+export interface AnnotationDecoders {
+    inflateRaw?: InflateRaw;
+    inflate?: Inflate;
+    gunzip?: Gunzip;
+    /** Open a GeoJSON text as a region source (default: in the shared region worker). */
+    openGeoJson?: (text: string) => Promise<RegionSource>;
+    /**
+     * Give a label image's regions the atlas look (dark outlines, labels) when its ontology names
+     * no style: drawn over the label image itself, outlines in their classes' own colours would not
+     * show. (Imported over a real image, the default look reads.)
+     */
+    outlineLabels?: boolean;
+}
+/** The annotations among some files, as one region source per slice. */
+export interface AnnotationSlices {
+    kind: 'labels' | 'folder' | 'single';
+    /** A name for what was opened (the label image's, the folder's, the file's). */
+    name: string;
+    slices: number;
+    /** One opener per slice index. */
+    openers: Map<number, Opener>;
+    /** A label image's slices and classes (to draw them, see openAnnotations). */
+    labels?: {
+        stack: LabelStack;
+        classes: LabelClasses;
+    };
+    /** Slice width and height, when known without opening the sources (a label image's). */
+    size?: [number, number];
+    /** Voxel size x, y, z in micrometres, when the source says. */
+    spacing?: [number, number, number];
+    /** What was read, for a message ("12 slices of 456 × 320"). */
+    summary: string;
+}
+/**
+ * The annotations among `files` (zips expanded), as one region source per slice; null when there
+ * are none to read. A label image's slices are traced, and a GeoJSON parsed, when the slice is
+ * first shown.
+ */
+export declare function readAnnotationSlices(chosen: readonly RegionImportFile[], decoders?: AnnotationDecoders): Promise<AnnotationSlices | null>;
+/** What {@link openAnnotations} built: the image to publish, and how to release it. */
+export interface OpenedAnnotations {
+    info: IImageInfo;
+    summary: string;
+    /** Revoke the image's blob URLs, and release the slices' sources the region store never took
+     *  (once another image replaced it). */
+    dispose(): void;
+}
+/**
+ * The image `files`' annotations are shown on by themselves (see the module comment). Throws when
+ * there are none, or when their regions span more than {@link ANNOTATION_IMAGE_MAX_DIM} pixels
+ * (they are then imported onto the image they were drawn on).
+ */
+export declare function openAnnotations(files: readonly RegionImportFile[], decoders?: AnnotationDecoders): Promise<OpenedAnnotations>;
+/**
+ * One GeoJSON's slices: a collection whose features name planes (`geometry.plane.z`) split into
+ * one collection per plane, each keeping the set's class tree and style, its features moved to
+ * plane 0 (a slice's source shows plane 0); any other GeoJSON is one slice as it is.
+ */
+export declare function splitByPlane(text: string): string[];
+export {};

package/lib/region-import/region-import.d.ts

@@ -0,0 +1,46 @@
+/** A file to import regions from: one the user chose, or one the host's server sent. */
+export interface RegionImportFile {
+    name: string;
+    text(): Promise<string>;
+    bytes(): Promise<Uint8Array>;
+}
+/** A file's contents as the host may hand them over (see `ServerRegionPick`). */
+export type RegionImportData = Blob | ArrayBuffer | Uint8Array | string;
+/** `data`, named `name`, as an import file. A `File`'s own name is used when `name` is omitted. */
+export declare function importFile(data: RegionImportData, name?: string): RegionImportFile;
+/** What a set of chosen files imports as. */
+export type RegionImportPlan = 
+/** A label volume, its classes named by an ontology (or a region set description) beside it. */
+{
+    kind: 'volume';
+    volume: RegionImportFile;
+    ontology: RegionImportFile | null;
+}
+/** A folder of per-slice region files, in slice order, with the set's `regionset.json`. */
+ | {
+    kind: 'folder';
+    slices: RegionImportFile[];
+    regionSet: RegionImportFile | null;
+}
+/** One region file. */
+ | {
+    kind: 'single';
+    file: RegionImportFile;
+};
+/**
+ * What `files` import as: a label volume (`.nii`, `.nii.gz`, `.nrrd`) with the ontology JSON chosen
+ * with it (a `regionset.json`, else an Allen `structure_graph*.json`, else any `.json`); several
+ * region files (a folder of per-slice `.geojson`, in natural name order, its `regionset.json`
+ * apart); or one region file (`.geojson` or `.json`). Null when none of them is one.
+ */
+export declare function planRegionImport(files: readonly RegionImportFile[]): RegionImportPlan | null;
+/** "slice_2" before "slice_10": runs of digits compared as numbers. */
+export declare function naturalCompare(a: string, b: string): number;
+/**
+ * A folder slice's GeoJSON with the set's class tree and style (its `regionset.json`) as the
+ * collection's own members, unless the file has its own: what a served folder's slice carries.
+ */
+export declare function folderSliceGeoJson(file: RegionImportFile, regionSet: {
+    classHierarchy?: unknown;
+    style?: unknown;
+} | null): Promise<string>;

package/lib/region-import/zarr-codecs.d.ts

@@ -0,0 +1,14 @@
+/** Inflate gzip or zlib data (default: the platform's `DecompressionStream`). */
+export type Inflate = (bytes: Uint8Array, format: 'gzip' | 'deflate') => Promise<Uint8Array>;
+/** Decode a Blosc frame. */
+export declare function bloscDecompress(frame: Uint8Array, inflate?: Inflate): Promise<Uint8Array>;
+/** Decode one LZ4 block (no frame) of `size` bytes. */
+export declare function lz4BlockDecompress(src: Uint8Array, size: number): Uint8Array;
+/**
+ * Decode a zarr chunk through `codecs`, outermost last as zarr lists them (v2: the one
+ * `compressor`; v3: the bytes-to-bytes codecs after `bytes`).
+ */
+export declare function decodeChunk(bytes: Uint8Array, codecs: readonly {
+    id: string;
+    [k: string]: unknown;
+}[], inflate?: Inflate): Promise<Uint8Array>;

package/lib/region-import/zip.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The members of a `.zip`, read in the browser: annotations handed over as one archive (a folder
+ * of per-slice GeoJSON, a label volume with its ontology, an OME-Zarr store's labels).
+ *
+ * Only what such archives use: stored or deflated members, ZIP64 sizes and offsets, UTF-8 or
+ * legacy names. An encrypted or otherwise compressed member throws when it is read, rather than be
+ * read wrongly; a member's CRC-32 is checked. Members are read on demand, so an archive of many
+ * chunks (a zarr store) is not inflated whole. Pure: usable from workers.
+ */
+import type { RegionImportFile } from './region-import';
+/** One member of an archive. */
+export interface ZipEntry {
+    /** Its path in the archive, '/'-separated. */
+    name: string;
+    /** Its uncompressed size, in bytes. */
+    size: number;
+    bytes(): Promise<Uint8Array>;
+}
+/** Inflate raw DEFLATE data (default: the platform's `DecompressionStream('deflate-raw')`). */
+export type InflateRaw = (bytes: Uint8Array) => Promise<Uint8Array>;
+/** Whether a file name is a zip archive. */
+export declare function isZipName(name: string): boolean;
+/** The members of the archive in `bytes` (directories and macOS metadata left out). */
+export declare function readZip(bytes: Uint8Array, inflateRaw?: InflateRaw): ZipEntry[];
+/**
+ * `files` with every `.zip` among them replaced by its members, named by their paths in it (a
+ * single top folder the archive wraps everything in is kept, as a folder pick would keep it).
+ */
+export declare function expandZips(files: readonly RegionImportFile[], inflateRaw?: InflateRaw): Promise<RegionImportFile[]>;
+/** CRC-32 (IEEE), as zip records it. */
+export declare function crc32(data: Uint8Array): number;

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

@@ -75,8 +75,14 @@ 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. */
+    /**
+     * Whether regions can be shown in 3D on screen: a napari volume (or isosurface) view, or the 3D
+     * spatial cloud over a stack image (its reference volume's, see showVolumeAsImage). Both draw the
+     * region reconstructions the same way (VolumeRegionMeshes), in the volume's box.
+     */
     private readonly volumeView$;
+    /** Whether a napari volume (or isosurface) view is the current plot type: the slice pane's. */
+    private imageVolumeView;
     /** 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. */
@@ -114,6 +120,8 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     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. */
@@ -265,12 +273,42 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     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;
+    /** Recompute which 3D view is on screen for `plotType` (see {@link volumeView$}). */
+    private updateVolumeView;
     /** 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). */

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

@@ -31,8 +31,12 @@ export declare class RegionSourceScope {
     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. */
-    attach(image: string, open: RegionSourceOpener, slices: RegionSourceSlices): void;
+    /**
+     * 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`. */
@@ -56,6 +60,8 @@ export declare class RegionSourceScope {
     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). */

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

@@ -338,8 +338,13 @@ export declare class RegionStore implements IRegionStore, IRegionEditApi, IRegio
      * source was closed to save memory). `slices` says which slice of the current image it
      * serves: one (default: the slice shown; plane 0 of the source), or `'planes'`, every slice z
      * from plane z of a z-indexed source. Replaces the source those slices had.
+     *
+     * `imported` marks a source brought in over the image (an imported volume, folder or served set)
+     * rather than the image's own regions: it is on no file yet, so a save writes its slices though
+     * nothing was taken from it — `true` for a source of one slice, the slices its planes cover for a
+     * `'planes'` source. The image's own sources are not marked: loading them changes nothing to save.
      */
-    attachRegionSource(source: RegionSource | RegionSourceOpener, slices?: RegionSourceSlices): void;
+    attachRegionSource(source: RegionSource | RegionSourceOpener, slices?: RegionSourceSlices, imported?: boolean | readonly number[]): void;
     /** Drop the current image's region sources (closing them) and what was taken from them. */
     detachRegionSources(): void;
     /**
@@ -439,10 +444,15 @@ export declare class RegionStore implements IRegionStore, IRegionEditApi, IRegio
      */
     getRegionSourceIndex(query: Omit<RegionIndexQuery, 'exclude'>): Promise<RegionIndexPage>;
     /**
-     * `regions` as a GeoJSON FeatureCollection string merged with the region source behind them:
-     * the source's features that were not taken (or deleted), then `regions`. Without a source,
-     * {@link getGeoJsonString}. `slice` names a folder stack's slice (default the one shown);
-     * on a z-indexed stack's source (`'planes'`) the export spans every slice.
+     * `regions` as a GeoJSON FeatureCollection string merged with the region sources behind them:
+     * the sources' features that were not taken (or deleted), then `regions`. Without a source,
+     * {@link getGeoJsonString}.
+     *
+     * `slice` names one slice-file of a folder stack (a per-slice-file save): its source's features,
+     * on the file's own plane — of a z-indexed source over every slice, only that slice's plane.
+     * Without it, the export is the image's: on a stack saved as one file, every slice's source
+     * (each feature on its slice's plane, `geometry.plane.z`) and a z-indexed source's every plane;
+     * otherwise the source of the slice shown.
      */
     getGeoJsonWithSource(regions: Region[], slice?: number): Promise<string>;
     /**

package/lib/visualizer.component.d.ts

@@ -290,6 +290,8 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     protected get hasSpatialDataset(): boolean;
     /** Keyboard, wheel and context-menu handling; created once the view exists. */
     private shortcuts?;
+    /** Waits for a viewer created outside the document to be attached (see {@link whenInDocument}). */
+    private attachObserver;
     /** Debounced z-slice scrubbing (see SliceScrubber — refactoring plan Step 7). */
     private readonly scrubber;
     constructor(state: ImageStatePort, plotService: IVisualizer, messageService: MessageService, ngZone: NgZone, cdr: ChangeDetectorRef, session: VisualizerStore, samTool: SamToolService, cellSegmentTool: CellSegmentToolService, samPointTool: SamPointToolService, regionOps: RegionOpsService, vizConfig?: VizConfig | undefined, toolContributions?: readonly ToolbarContribution[], spatialData?: SpatialDataPort | undefined, plotTypeContributions?: readonly PlotTypeContribution[], injector?: Injector | undefined, hostRef?: ElementRef<HTMLElement> | undefined, destroyRef?: DestroyRef);
@@ -338,6 +340,13 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     ngAfterViewInit(): void;
     /** The plot div exists now: run an image-less draw that arrived before it did. */
     private onViewReady;
+    /**
+     * Run `ready` once this viewer is in the document. A host may create it detached — a closed
+     * dialog's projected content, such as jit-ui's pipeline preview — and the backends find the
+     * plot div by id, so a draw then found no target and alerted "the renderer could not start"
+     * over another viewer. Until then its view is not ready, and an image-less draw waits.
+     */
+    private whenInDocument;
     /** What the keyboard, wheel and context-menu shortcuts act on. Their listeners live
      *  outside this view, so every action that changes what it shows marks it for check. */
     private shortcutHost;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jax-data-science/sci-image-visualizer",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -39,6 +39,7 @@
   "dependencies": {
     "cellpose-js": "^0.6.0",
     "fast-png": "^6.4.0",
+    "fzstd": "^0.1.1",
     "napari-js": "^0.18.0",
     "openseadragon": "^6.0.2",
     "plotly.js-dist-min": "^3.0.1",