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

package/index.d.ts

@@ -46,6 +46,18 @@ export { clearSamModelCache } from './lib/toolbar/segmentation/sam-onnx-core';
 export * from './lib/models/region';
 export * from './lib/models/class-preset';
 export { ShapeSelection } from './lib/models/shape';
+export { openGeoJsonRegionSource } from './lib/region-source/worker-region-source';
+export { openHttpRegionSource } from './lib/region-source/http-region-source';
+export type { HttpRegionSourceOptions, WireTileFeature } from './lib/region-source/http-region-source';
+export { REGION_SOURCE_MIN_CHARS } from './lib/region-source/region-source';
+export { isLabelVolumeName, readLabelVolume } from './lib/region-import/label-volume';
+export type { LabelVolume } from './lib/region-import/label-volume';
+export { labelClasses, labelSliceGeoJson } from './lib/region-import/label-classes';
+export type { LabelClasses } from './lib/region-import/label-classes';
+export { importFile, planRegionImport } from './lib/region-import/region-import';
+export type { RegionImportFile, RegionImportPlan } from './lib/region-import/region-import';
+export type { RegionSource, RegionSourceView, SourceFeature } from './lib/region-source/region-source';
+export type { RegionIndexPage, RegionIndexQuery, RegionIndexRow, RegionSourceInfo, RegionTile, RegionTileKey, TileFeature, } from './lib/region-source/region-tiles';
 export { VisualizationModule } from './lib/visualization.module';
 export { RoutingVisualizerService } from './lib/routing-visualizer.service';
 export { provideVisualization } from './lib/provide-visualization';

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

@@ -61,6 +61,10 @@ export interface IImageInfo {
      *  opposed to the scalar `roiJsonStr`, which is one ROI set for the whole
      *  image (a single file or a server z-stack). (jit-ui#93) */
     roiJsonStrs?: (string | null)[];
+    /** Base URL of a server-side region source for this image (see `openHttpRegionSource`):
+     *  its regions are drawn from the server's level-of-detail tiles instead of being loaded
+     *  from `roiJsonStr`. On a stack, slice z shows the source's plane z. */
+    regionSourceUrl?: string;
     /** Per-slice, per-channel plane URLs for a SERVERLESS multichannel image
      *  (`tiled: false` + `imageMeta[0].channelCount > 1`). `channelUrls[z][c]`
      *  is a complete single-band image of channel c at slice z. The OSD simple

package/lib/contracts/ports/region-io.port.d.ts

@@ -25,6 +25,30 @@ export interface RegionIoPort {
         z: number;
         geoJsonStr: string;
     }[]): Observable<void>;
+    /**
+     * "Import regions from server": let the user pick region files or a region set in the host's
+     * storage (the current project's bucket, say) and hand them over. Emits null when the user
+     * cancels. Without it, the Region Editor shows no server import.
+     */
+    pickServerRegions?(): Observable<ServerRegionPick | null>;
 }
+/**
+ * Regions picked on the host's server (see {@link RegionIoPort.pickServerRegions}): files it
+ * downloaded, imported as the Region Editor imports chosen files (one GeoJSON; a label volume
+ * `.nii` / `.nii.gz` / `.nrrd` with its ontology JSON; a folder's per-slice GeoJSON files with its
+ * `regionset.json`), or a region set its server serves by level of detail (jit-service's
+ * `/regions/{id}/`), read through the host's `HttpClient` without downloading it.
+ */
+export type ServerRegionPick = {
+    kind: 'files';
+    files: Array<{
+        name: string;
+        data: Blob | ArrayBuffer | Uint8Array | string;
+    }>;
+} | {
+    kind: 'source';
+    url: string;
+    name?: string;
+};
 /** DI token for the host's {@link RegionIoPort}. Required by the region editor. */
 export declare const REGION_IO_PORT: InjectionToken<RegionIoPort>;

package/lib/contracts/region-editor-api.contract.d.ts

@@ -3,6 +3,9 @@ import { Observable } from 'rxjs';
 import { Region } from '../models/region';
 import { ClassPreset, PresetSet } from '../models/class-preset';
 import { IImageMetadata } from './image.contract';
+import type { RegionSource, RegionSourceView } from '../region-source/region-source';
+import type { RegionIndexPage, RegionIndexQuery } from '../region-source/region-tiles';
+import type { RegionStyle } from '../region-overlay/region-style';
 /**
  * Public, implementation-agnostic surface that the Region Editor (an *external*
  * consumer of the visualization package) depends on. It deals only in
@@ -78,6 +81,105 @@ export interface IRegionEditorApi {
         width: number;
         height: number;
     } | null;
+    /**
+     * Load `geoJsonStr` as the slice's region source when it is large enough
+     * (`VizConfig.regionSourceMinChars`): resolves true once it is open, false when it is small
+     * and should be imported as regions; rejects when it is not a GeoJSON FeatureCollection.
+     */
+    importRegionSource?(geoJsonStr: string): Promise<boolean>;
+    /**
+     * A ticket for an import about to read or decode its files: an import method given a stale one
+     * (another import took a ticket since, or another image was plotted) changes nothing.
+     */
+    regionImportTicket?(): number;
+    /**
+     * Replace the regions and region sources with one source per slice (an imported label volume,
+     * or a folder of per-slice region files): 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 one, or null
+     * (changing nothing) when `ticket` is stale. A save writes every imported slice.
+     */
+    importSliceRegionSources?(openers: ReadonlyMap<number, () => Promise<RegionSource>>, ticket?: number): number | null;
+    /**
+     * Replace them with one imported source (a region set a server serves): over every slice of a
+     * stack when z-indexed, else on the slice shown. Resolves false, changing nothing, when the
+     * import went stale while the source opened.
+     */
+    importRegionSourceOpener?(open: () => Promise<RegionSource>, ticket?: number): Promise<boolean>;
+    /**
+     * Drop the slice's region source, for regions imported in its place (a small file replacing a
+     * large one). The other slices keep theirs.
+     */
+    dropRegionSource?(): Promise<void>;
+    /** The slice's region source (null without one) and every change of it. */
+    getRegionSourceView$?(): Observable<RegionSourceView | null>;
+    /** A page of the slice source's features that were not taken from it. */
+    getRegionSourceIndex?(query: Omit<RegionIndexQuery, 'exclude'>): Promise<RegionIndexPage>;
+    /** Take source features into the regions and select them (added with `additive`). */
+    selectSourceFeatures?(ids: readonly string[], additive?: boolean): Promise<number[]>;
+    /** Delete source features without taking them (one undo step). */
+    deleteSourceFeatures?(ids: readonly string[]): void;
+    /**
+     * Features per class still in the slice's region source (not taken); with `stack`, a z-stack's
+     * over every slice.
+     */
+    getRegionSourceClassCounts?(stack?: boolean): Promise<Record<string, number>>;
+    /** The region look (outlines, or filled with labels inside) and every change of it. */
+    getRegionStyle$?(): Observable<RegionStyle>;
+    /** Choose the region look, field by field (overrides a region source's hint). */
+    setRegionStyle?(patch: Partial<RegionStyle>): void;
+    /** Whether a volume view is on screen (regions can then be shown in 3D). */
+    getVolumeView$?(): Observable<boolean>;
+    /**
+     * Whether the volume view's slice pane is wanted (one slice edited beside the 3D view). A volume
+     * view without it lists every slice's classes; with it, the slice's.
+     */
+    getSliceEditor$?(): Observable<boolean>;
+    /** Whether the volume view draws the region reconstructions through the volume, and changes. */
+    getRegionsThroughVolume$?(): Observable<boolean>;
+    /**
+     * Draw the region reconstructions through the volume (it hides none: surfaces traced inside its
+     * bright structures) or hidden behind what it shows in front of them (the default).
+     */
+    setRegionsThroughVolume?(through: boolean): void;
+    /**
+     * Show these groups of classes in the volume view as 3D reconstructions (one surface per group,
+     * in its colour), and only these; [] hides them.
+     */
+    showRegionClasses3d?(groups: ReadonlyArray<{
+        key: string;
+        classes: readonly string[];
+        color: string;
+        label?: string;
+    }>): Promise<void>;
+    /**
+     * Each class's volume over the whole stack, in px² × slices: its outlines' area on every slice,
+     * one slice thick. Times the pixel size and the slice spacing, µm³.
+     */
+    getClassVolumes?(classes: readonly string[]): Promise<Record<string, number>>;
+    /** 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;
+    }>;
+    /** The class groups shown in 3D on the image on screen; emits [] when another image is plotted. */
+    getRegionClasses3d$?(): Observable<ReadonlyArray<{
+        key: string;
+        classes: readonly string[];
+    }>>;
+    /** The classes hidden from view, and every change of them. */
+    getHiddenClasses$?(): Observable<ReadonlySet<string>>;
+    /**
+     * Hide (or show again) these classes: their regions and the region source's features are not
+     * drawn or picked, and their surfaces in the volume view are hidden.
+     */
+    setClassesHidden?(classes: readonly string[], hidden: boolean): void;
+    /** Select every region of these classes on the slice, the source's included (taken). */
+    selectRegionClasses?(classes: readonly string[], additive?: boolean): Promise<void>;
+    /** {@link getGeoJsonString} merged with the region source behind the regions (see
+     *  `RegionStore.getGeoJsonWithSource`); `slice` names a folder stack's slice. */
+    getGeoJsonStringWithSource?(regions: Region[], slice?: number): Promise<string>;
 }
 /** DI token the Region Editor injects instead of the concrete service. */
 export declare const REGION_EDITOR_API: InjectionToken<IRegionEditorApi>;

package/lib/contracts/region-store.contract.d.ts

@@ -1,5 +1,8 @@
 import { Rectangle, Polygon, MultiPolygon } from '../models/region';
 import { Region } from '../models/region';
+import type { Observable } from 'rxjs';
+import type { RegionSourceView } from '../region-source/region-source';
+import type { RegionStyle } from '../region-overlay/region-style';
 /**
  * Region-native editing surface — typed geometry operations on the neutral
  * {@link Region} model. The OpenSeadragon overlay (and any future editing UI)
@@ -72,3 +75,22 @@ export interface IRegionEditApi {
     beginBatch(): void;
     endBatch(): void;
 }
+/**
+ * The region-source side of the store, as the overlays use it: a large region set held as a
+ * tiled source (see `RegionStore.attachRegionSource`) that the overlays draw at the zoom's level
+ * of detail and pick from. Optional on the overlays' store: a store without it simply has no
+ * source to draw.
+ */
+export interface IRegionSourceApi {
+    /** The current slice's source as a layer draws it, and every change of it; null without one. */
+    getRegionSourceView$(): Observable<RegionSourceView | null>;
+    /** Take source features into the working set as regions and select them (added to the
+     *  selection with `additive`). Resolves the region ids. */
+    selectSourceFeatures(ids: readonly string[], additive?: boolean): Promise<number[]>;
+    /** The region look (outlines, or filled with inside labels). */
+    getRegionStyle(): RegionStyle;
+    /** Whether a class's label is left out because a subclass of it is drawn too. */
+    isLabelCovered(label: string | undefined): boolean;
+    /** Whether regions labelled `label` are hidden: not drawn, not picked. */
+    isClassHidden(label: string | null | undefined): boolean;
+}

package/lib/contracts/section-view.contract.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The sections shown beside a split volume view: the planes x = const and y = const through the
+ * stack, each as an image cut from the volume with the regions' outlines cut by the same plane.
+ *
+ * Section coordinates `(u, v)` (see `geometry/section`): through x, u is the slice (slice k spans
+ * [k, k + 1)) and v the image y; through y, u is the image x and v the slice.
+ */
+export type SectionAxis = 'x' | 'y';
+/** A class's outlines in a section, as interleaved `u, v`. */
+export interface SectionRegions {
+    label: string;
+    /** `#rrggbb`. */
+    color: string;
+    /** Closed outlines, holes included (even-odd). */
+    rings: Float64Array[];
+    /** Open lines (a layer boundary across the slices); one point where it crosses one slice only. */
+    lines: Float64Array[];
+}
+export interface SectionView {
+    axis: SectionAxis;
+    /** Where the plane is: image x (through x) or y (through y), px. */
+    at: number;
+    /** The section's image, RGBA row by row, spanning [0, size[0]] × [0, size[1]]. */
+    image: {
+        width: number;
+        height: number;
+        data: Uint8ClampedArray;
+    };
+    /** Section units across (u) and down (v). */
+    size: [number, number];
+    /** The volume's world units per section unit across and down: draws it in its proportions. */
+    scale: [number, number];
+    regions: SectionRegions[];
+    /** The other two planes, across (a u) and down (a v); null where there is none. */
+    crosshair: {
+        u: number | null;
+        v: number | null;
+    };
+}
+/** Both sections; null until the split volume view has a volume to cut. */
+export interface SectionViews {
+    x: SectionView | null;
+    y: SectionView | null;
+}

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

@@ -1,4 +1,5 @@
 import { InjectionToken } from '@angular/core';
+import type { SectionAxis, SectionViews } from './section-view.contract';
 import { Observable } from 'rxjs';
 import { Image } from 'image-js';
 import { IImageInfo, IImageMetadata } from './image.contract';
@@ -490,6 +491,15 @@ export interface IVisualizer extends IDataRenderer, IRegionStore, IToolControlle
     /** This backend's region renderer. May be null until a plot is mounted
      *  (OpenSeadragon). Drives region draw/select modes uniformly. */
     getRegionOverlay(): IRegionOverlay | null;
+    /** Split a volume view: the displayed slice, with every region tool, in the div `div` beside
+     *  the 3D view; null closes it. Resolves whether the slice shows. Optional: the router's. */
+    setSliceEditor?(div: string | null): Promise<boolean>;
+    /** The slice editor's sections through x and y (nulls while it is closed). Optional: the router's. */
+    getSectionViews$?(): Observable<SectionViews>;
+    /** Move the slice editor's section plane through `axis` 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). */
+    getSliceDrag$?(): Observable<number>;
     /** Isosurface controls when this backend advertises `ViewerFeature.Isosurface`,
      *  else null — so consumers gate on the returned object, not a no-op method. */
     getIsosurfaceControls(): IIsosurfaceControls | null;

package/lib/contracts/viz-config.d.ts

@@ -21,6 +21,14 @@ export interface VizConfig {
      * are unaffected.
      */
     useNapariRenderer?: boolean;
+    /**
+     * An image's ROI GeoJSON (`roiJsonStr`, or a slice's `roiJsonStrs[z]`) at least this many
+     * characters long loads as a tiled region source rather than as regions: drawn from the tiles
+     * in view at the zoom's level of detail (OpenSeadragon and napari; Plotly does not draw it),
+     * each feature joining the regions when it is selected or edited. Default 1 000 000; 0 makes
+     * every ROI file a source, `Infinity` none.
+     */
+    regionSourceMinChars?: number;
 }
 /** DI token for the host's {@link VizConfig}. Required by the router. */
 export declare const VIZ_CONFIG: InjectionToken<VizConfig>;

package/lib/geometry/loft.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The sheet through open polylines traced on a stack of slices (a retinal layer boundary on each
+ * B-scan, say): each line joined to its counterpart on the next slice that has lines by a strip of
+ * triangles. Slices without lines in between are bridged straight across.
+ *
+ * Pure: usable from workers.
+ */
+import type { Mesh } from 'napari-js/geometry';
+/** A class's open polylines on one slice: interleaved `x, y` image pixels. */
+export interface SliceLines {
+    z: number;
+    lines: readonly ArrayLike<number>[];
+}
+/**
+ * The sheet through `slices`' lines, in image pixels (x, y) and slice indices (z: slice k's line at
+ * z = k). Every line is resampled at the same number of points, evenly along its length (about one
+ * per `step` px of the longest), so a line shared by the strips above and below it is one row of
+ * vertices. Lines are matched between neighbouring slices closest first, each at most once, and only
+ * when their boxes overlap; a line without a match ends the sheet there. Empty without two slices
+ * with lines.
+ */
+export declare function loftLines(slices: readonly SliceLines[], step?: number): Mesh;

package/lib/geometry/polylabel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where to put a label inside a polygon: its pole of inaccessibility, the inside point farthest
+ * from every edge (Garcia-Castellanos & Lombardo's grid search, as in Mapbox's polylabel). Unlike
+ * the centroid it is always inside, also for a U-shaped or ring-shaped region.
+ *
+ * Pure: usable from workers.
+ */
+/** A polygon as interleaved `x, y` rings: the exterior first, then its holes. */
+export type FlatRings = readonly ArrayLike<number>[];
+/** The pole of inaccessibility `[x, y]` and its distance to the nearest edge. */
+export interface LabelPoint {
+    x: number;
+    y: number;
+    /** Distance from the point to the nearest edge: how much room a label has around it. */
+    distance: number;
+}
+/**
+ * The pole of inaccessibility of `rings`, to within `precision` (default: 1/100 of the shorter
+ * side of the exterior's box, at least 0.5). Null for an exterior with fewer than three vertices.
+ */
+export declare function polylabel(rings: FlatRings, precision?: number): LabelPoint | null;
+/** Distance from (x, y) to the nearest edge of `rings`, positive inside (even-odd), negative outside. */
+export declare function signedDistance(x: number, y: number, rings: FlatRings): number;

package/lib/geometry/reconstruct.d.ts

@@ -0,0 +1,54 @@
+import type { Mesh } from 'napari-js/geometry';
+/**
+ * A region's outlines on one slice: rings as interleaved `x, y` image pixels (holes included), and
+ * open polylines (a layer boundary), likewise.
+ */
+export interface SliceOutlines {
+    z: number;
+    rings: ArrayLike<number>[];
+    /**
+     * The feature each ring is part of (equal ids, one feature): a feature's rings fill even-odd (its
+     * holes), the features as their union, so one inside or over another cuts no hole in it. Absent:
+     * the rings are one feature.
+     */
+    ringGroups?: ArrayLike<number>;
+    lines?: ArrayLike<number>[];
+}
+export interface ReconstructOptions {
+    /** In-plane voxel edge, image px (default 1). Raised to keep the mask within `maxVoxels`. */
+    pixelStep?: number;
+    /** At most this many voxels (default 32 M). */
+    maxVoxels?: number;
+    /** Laplacian smoothing passes (default 2). */
+    smooth?: number;
+}
+/**
+ * The mesh of the region outlined by `slices`, in image pixels (x, y) and slice indices (z: slice
+ * k's plane at z = k): the filled outlines' surface, and the sheet through the lines (see
+ * {@link loftLines}). Empty when no slice has an area and no two slices have lines.
+ */
+export declare function reconstruct(slices: readonly SliceOutlines[], opts?: ReconstructOptions): Mesh;
+/**
+ * The area inside `rings` (interleaved `x, y`), even-odd: a ring inside an odd number of others is
+ * a hole. Exact for rings that do not cross (a polygon set's exteriors and holes).
+ */
+export declare function ringsArea(rings: readonly ArrayLike<number>[]): number;
+/**
+ * The rings of each feature (see {@link SliceOutlines.ringGroups}), in the order first met; one
+ * feature of every ring without `groups`.
+ */
+export declare function featureRings(rings: readonly ArrayLike<number>[], groups?: ArrayLike<number>): ArrayLike<number>[][];
+/**
+ * The area of a slice's outlines (px²): each feature's (even-odd, see {@link ringsArea}), the
+ * features as their union, so a feature inside or over another of the slice adds only what it
+ * covers beyond it. Features whose extents overlap are measured together, by the length of their
+ * union along each row, exact between the rows through their vertices where no outline crosses
+ * another (and refined where one does).
+ */
+export declare function outlinesArea(rings: readonly ArrayLike<number>[], groups?: ArrayLike<number>): number;
+/**
+ * The volume of the region outlined by `slices`, in px² × slices (one slice thick per outline):
+ * the sum of each slice's area (see {@link outlinesArea}; Cavalieri's estimator). Times µm per px²
+ * and per slice, µm³.
+ */
+export declare function outlinedVolume(slices: readonly SliceOutlines[]): number;

package/lib/geometry/reslice-image.d.ts

@@ -0,0 +1,33 @@
+import type { Colormap } from 'napari-js';
+import type { SectionAxis } from './section';
+/** One channel of a volume as it is displayed. */
+export interface VolumeChannelVoxels {
+    /** uint8 voxels, x fastest, then y, then z. */
+    data: Uint8Array;
+    /** The colormap the 3D view draws the channel with (a tint, or the display colormap). */
+    colormap: Colormap;
+    /** Display window over 0..255. */
+    min: number;
+    max: number;
+    /** napari-js gamma (see `toNapariGamma`): the windowed value t shows as t^γ. */
+    gamma: number;
+    visible: boolean;
+}
+export interface VolumeVoxels {
+    width: number;
+    height: number;
+    depth: number;
+    channels: readonly VolumeChannelVoxels[];
+    invert: boolean;
+}
+/** An RGBA image, row by row. */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}
+/**
+ * The image of the plane `axis = index` (a voxel index): through x, slices across and y down;
+ * through y, x across and slices down — the section coordinates of `geometry/section`.
+ */
+export declare function resliceImage(vol: VolumeVoxels, axis: SectionAxis, index: number): RgbaImage;

package/lib/geometry/section.d.ts

@@ -0,0 +1,52 @@
+import { SliceOutlines } from './reconstruct';
+/** The plane: x = const (a section along y and the slices) or y = const (along x and the slices). */
+export type SectionAxis = 'x' | 'y';
+/** A class's outlines in a section, as interleaved `u, v`. */
+export interface ClassSection {
+    /** Closed outlines, holes included (even-odd). */
+    rings: Float64Array[];
+    /** Open lines; a line of one point is where the class crosses on one slice only. */
+    lines: Float64Array[];
+}
+export interface SectionOptions {
+    /** Slices in the stack. */
+    depth: number;
+    /** Image px across the section's in-plane axis: the image height through x, its width through y. */
+    extent: number;
+    /** In-plane cell size of the closed shapes' cut, image px (default 1). */
+    step?: number;
+    /** Farthest a line moves between neighbouring slices and is still joined, image px (default extent / 10). */
+    maxJump?: number;
+}
+/** `[x0, y0, x1, y1]`, image px. */
+type Box = [number, number, number, number];
+/** A ring or line with its extent. */
+interface Indexed {
+    points: ArrayLike<number>;
+    box: Box;
+}
+interface IndexedSlice {
+    z: number;
+    rings: Indexed[];
+    /** Each ring's feature (see SliceOutlines.ringGroups); absent: one feature. */
+    ringGroups?: ArrayLike<number>;
+    lines: Indexed[];
+}
+/**
+ * Every class's outlines with each ring's and line's extent (and the class's): made once, it cuts
+ * any number of sections visiting only the outlines a plane crosses.
+ */
+export interface SectionIndex {
+    readonly classes: ReadonlyMap<string, {
+        box: Box;
+        slices: readonly IndexedSlice[];
+    }>;
+}
+/** Index every class's outlines for cutting (see {@link SectionIndex}). */
+export declare function indexOutlines(byClass: ReadonlyMap<string, readonly SliceOutlines[]>): SectionIndex;
+/**
+ * Each class's cut by the plane `axis = at`; classes the plane misses are left out. Pass an
+ * {@link indexOutlines} index to cut many sections of the same outlines.
+ */
+export declare function sectionOutlines(outlines: SectionIndex | ReadonlyMap<string, readonly SliceOutlines[]>, axis: SectionAxis, at: number, opts: SectionOptions): Map<string, ClassSection>;
+export {};

package/lib/implementations/napari-js/napari-loading-badge.d.ts

@@ -1,6 +1,7 @@
 /**
  * "Transcripts reloading…" at the bottom of the canvas while a layer's data is in flight: one
  * line naming every layer still loading, on a semi-opaque backing so it reads over any tissue.
+ * Longer work names itself ("Building HPF in 3D…") and joins the line.
  *
  * Shown only once something has been loading for {@link SHOW_AFTER_MS}, so a redraw served from
  * cache does not flash it.
@@ -9,10 +10,11 @@ export declare const SHOW_AFTER_MS = 150;
 export declare class NapariLoadingBadge {
     private readonly el;
     private names;
+    private tasks;
     private timer;
     constructor(host: HTMLElement);
-    /** The layers loading now; empty hides the badge. */
-    set(names: readonly string[]): void;
+    /** The layers loading now, and the tasks running (their messages); both empty hides the badge. */
+    set(names: readonly string[], tasks?: readonly string[]): void;
     /** The text currently set (shown or about to be). */
     get text(): string;
     destroy(): void;

package/lib/implementations/napari-js/napari-loading-state.d.ts

@@ -9,6 +9,9 @@ export type LoadingSource = 'Image' | 'Observations';
  * the counts are dropped, and an `end` from a load that began before it is a no-op, so a load
  * that settles after a re-plot can neither un-count the new scene's work nor drive a count below
  * zero (which hid the next scene's "Observations reloading…" until a second load overlapped it).
+ *
+ * A {@link beginTask} is work that outlives a scene (a region's 3D reconstruction, built for
+ * whichever volume is on screen when it is done): its message stays across a reset.
  */
 export declare class LoadingBadgeState {
     private host;
@@ -16,15 +19,19 @@ export declare class LoadingBadgeState {
     private readonly counts;
     private tileLayers;
     private generation;
+    private readonly tasks;
     /** The element the badge is drawn into (the plot host); set per plot. */
     attach(host: HTMLElement): void;
     /** One load of `source` started; call the returned function once it settles. */
     begin(source: LoadingSource): () => void;
+    /** A task started, shown by its `message` ("Building HPF in 3D…"); call the returned function
+     *  once it settles. */
+    beginTask(message: string): () => void;
     /** The spatial tile layers still loading (their own names, in their order). */
     setTileLayers(layers: readonly string[]): void;
     /** The text the badge has set (shown, or about to be once the show delay passes). */
     get text(): string;
-    /** A new scene: forget every count and remove the badge. */
+    /** A new scene: forget every count and remove the badge (tasks show again on the next attach). */
     reset(): void;
     private show;
 }

package/lib/implementations/napari-js/napari-region-mesh-pointer.d.ts

@@ -0,0 +1,32 @@
+import type { RegionMesh3D } from './napari-volume-region-meshes';
+export interface RegionMeshPointerOptions {
+    /** The surface under canvas point (`x`, `y`) (CSS px), or null. */
+    pickAt(x: number, y: number): RegionMesh3D | null;
+    /** Whether a click picks (the selection tool armed, surfaces shown); otherwise clicks are left alone. */
+    active(): boolean;
+    /** Whether hovering names the surface under the pointer (surfaces shown, whatever the tool). */
+    hoverable(): boolean;
+    /** A click on a surface (its key), or on none (null); `additive` with Shift / Ctrl / ⌘. */
+    onPick(key: string | null, additive: boolean): void;
+}
+/**
+ * Clicks and hover on the region surfaces of a volume view: a click (a press that does not orbit)
+ * picks the surface under it, or none; resting over a surface shows its name in a tooltip (and a
+ * pointer cursor when a click would pick it). Listens on the canvas without stopping events, so the
+ * camera still orbits.
+ */
+export declare class RegionMeshPointer {
+    private readonly canvas;
+    private readonly opts;
+    private readonly tip;
+    private down;
+    private hoverTimer;
+    constructor(canvas: HTMLElement, host: HTMLElement, opts: RegionMeshPointerOptions);
+    destroy(): void;
+    private local;
+    private readonly onDown;
+    private readonly onUp;
+    private readonly onMove;
+    private readonly onLeave;
+    private hide;
+}

package/lib/implementations/napari-js/napari-region-overlay.d.ts

@@ -56,6 +56,9 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     private readonly store;
     private readonly svg;
     private readonly renderer;
+    /** The image's region source, drawn under the regions at the zoom's level of detail; null
+     *  where world is not the image (the 3D view's screen-space lassos). */
+    private readonly sourceLayer;
     /** Client ↔ svg-local ↔ world conversions, with the svg origin read once per gesture/redraw. */
     private readonly projection;
     private readonly subs;
@@ -72,7 +75,9 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     /** In-progress manipulation (select/move modes): dragging a body, a polygon vertex, or a
      *  rectangle corner. `anchor` is the fixed opposite corner for a rectangle resize. */
     private edit;
-    constructor(host: HTMLElement, viewer: OverlayViewer, store: RegionStore);
+    constructor(host: HTMLElement, viewer: OverlayViewer, store: RegionStore, opts?: {
+        regionSource?: boolean;
+    });
     /**
      * Whether a region tool currently owns the pointer.
      *

package/lib/implementations/napari-js/napari-scene.d.ts

@@ -1,4 +1,7 @@
+import type { RegionMesh3D } from './napari-volume-region-meshes';
 import type { Viewer } from 'napari-js';
+import type { VolumeFrame } from './napari-volume-region-meshes';
+import type { PlaneAxis, SlicePlanes } from './napari-volume-slice-planes';
 import { IImageInfo } from '../../contracts/image.contract';
 import { IHistogram } from '../../contracts/channel-histogram-api.contract';
 import { IIsosurfaceControls, ISurface3dControls } from '../../contracts/visualizer.contract';
@@ -34,6 +37,23 @@ export interface NapariScene {
     setNavigatorVisible?(visible: boolean): void;
     /** Observations projected to canvas pixels (the spatial 3D cloud), or null. */
     screenProjection?(obs: SpatialObservations): Float32Array | null;
+    /** Show these region reconstructions in the 3D view (volume scenes only). */
+    setRegionMeshes?(meshes: readonly RegionMesh3D[]): void;
+    /** Highlight the reconstructions of these keys (none: all as usual). */
+    setRegionHighlight?(keys: readonly string[]): void;
+    /** Hide the reconstructions of these keys. */
+    setRegionHidden?(keys: readonly string[]): void;
+    /**
+     * Draw the region reconstructions through the volume (it hides none of them) rather than hidden
+     * where it is in front of them (see VolumeScene.setRegionsThroughVolume).
+     */
+    setRegionsThroughVolume?(through: boolean): void;
+    /** Show the planes of the sections beside the 3D view (volume scenes only). */
+    setSlicePlanes?(planes: SlicePlanes): void;
+    /** The assembled volume the sections are cut from (volume scenes only). */
+    volumeVoxels?(): VolumeVoxelsOnScreen | null;
+    /** Image px per voxel of the assembled volume, in-plane (volume scenes only). */
+    voxelStep?(): number | null;
     /** Remove everything the scene added; called before the viewer is disposed. */
     dispose(): void;
 }
@@ -59,6 +79,15 @@ export interface StackProgress {
 }
 /** Everything a scene is built from: the viewer and its DOM, the service's collaborators, and the
  *  service state a scene reads live. */
+/** A volume as assembled for display (voxels per channel, key 0 the grayscale one) and its frame. */
+export interface VolumeVoxelsOnScreen {
+    width: number;
+    height: number;
+    depth: number;
+    channels: ReadonlyMap<number, Uint8Array>;
+    multichannel: boolean;
+    frame: VolumeFrame;
+}
 export interface SceneContext {
     readonly viewer: Viewer;
     readonly host: HTMLElement;
@@ -90,4 +119,8 @@ export interface SceneContext {
     fitCameraSoon(): void;
     outsideZone<T>(fn: () => T): T;
     inZone<T>(fn: () => T): T;
+    /** A region reconstruction was clicked (its key), or the volume beside them (null). */
+    regionMeshPicked(key: string | null, additive: boolean): void;
+    /** A section's plane dragged in the volume to `value` along its axis. */
+    slicePlaneMoved(axis: PlaneAxis, value: number): void;
 }