@jax-data-science/sci-image-visualizer 0.17.0 → 0.18.0

package/lib/implementations/napari-js/napari-volume-region-meshes.d.ts

@@ -1,4 +1,7 @@
 import type { Viewer } from 'napari-js';
+import { PlanePlacement, VolumeFrame, sliceZ, toWorld } from '../../geometry/place';
+export type { PlanePlacement, VolumeFrame };
+export { sliceZ, toWorld };
 /** A region's 3D reconstruction to show in the volume: a mesh in image px (x, y) and slices (z). */
 export interface RegionMesh3D {
     /** Identity (a class name): a mesh with the same key and arrays is kept, not rebuilt. */
@@ -10,25 +13,20 @@ export interface RegionMesh3D {
     vertices: Float32Array;
     faces: Uint32Array;
 }
-/** Where the stack sits in the volume's world: its full size, and the centred world box it fills. */
-export interface VolumeFrame {
-    /** Image width, height (px) and slice count. */
-    size: [number, number, number];
-    /** The world box (centred on the origin), Z as currently stretched. */
-    world: [number, number, number];
-    /**
-     * How much of {@link world}'s depth is the view's Z stretch (default 1). The region surfaces keep
-     * their geometry in the unstretched box and take the stretch as a GPU scale (`scale3d`), so
-     * dragging the Z handle re-uploads no mesh.
-     */
-    zScale?: number;
-}
+/** Places a mesh's vertices (image px, slices) in a 3D view's world, off the main thread. */
+export type RegionPlacer = (vertices: Float32Array, frame: VolumeFrame) => Promise<Float32Array>;
 /** Opacity of a region's surface in the volume. */
 export declare const REGION_MESH_OPACITY = 0.55;
 /** While some surfaces are highlighted: theirs (near opaque, so their shape reads) … */
 export declare const REGION_MESH_HIGHLIGHT_OPACITY = 0.9;
 /** … and the others' (ghosted: still there for context, not in the way). */
 export declare const REGION_MESH_DIMMED_OPACITY = 0.12;
+/**
+ * A selection's surfaces while the others are ghosted: opaque, so they are drawn first and write
+ * depth, and the ghosted surfaces in front of them are blended over them rather than hiding them
+ * (a translucent surface draws only its own nearest faces, and is drawn after the opaque ones).
+ */
+export declare const REGION_MESH_SELECTED_OPACITY = 1;
 /**
  * The region reconstructions shown in a volume view: one translucent surface per region, in its
  * colour, placed in the volume's world box (pixel x, y and slice z mapped onto it the way the
@@ -42,13 +40,25 @@ export declare const REGION_MESH_DIMMED_OPACITY = 0.12;
  */
 export declare class VolumeRegionMeshes {
     private readonly viewer;
+    private readonly placer?;
     private readonly layers;
     private highlighted;
     private hidden;
+    /** Surfaces faded: none of what is selected is in them. */
+    private muted;
     /** The meshes to show (kept while the volume has no frame yet). */
     private wanted;
     private frame;
-    constructor(viewer: Viewer);
+    /** The placements in flight, by key: the mesh and box each is for. */
+    private readonly placing;
+    private token;
+    /**
+     * `placer`, when given, places a mesh's vertices in the world off the main thread (a worker, see
+     * `placeInWorker`): a class's surface has hundreds of thousands of vertices, and placing every
+     * one in a loop here held the UI for seconds. Each surface then comes up as its placement lands,
+     * the one it replaces kept until then. Without one, they are placed at once (the tests).
+     */
+    constructor(viewer: Viewer, placer?: RegionPlacer | undefined);
     /** Show exactly `meshes` (adding, keeping or removing surfaces). */
     set(meshes: readonly RegionMesh3D[]): void;
     /**
@@ -60,6 +70,12 @@ export declare class VolumeRegionMeshes {
     private scale3d;
     /** Highlight the surfaces of these keys (none: every surface as usual). */
     setHighlight(keys: Iterable<string>): void;
+    /**
+     * Fade the surfaces of these keys, as a picked region fades the others (none: each as usual):
+     * with a selection, the regions none of it is in fade and those it is in come forward, each
+     * keeping its colour.
+     */
+    setMuted(keys: Iterable<string>): void;
     /** Hide the surfaces of these keys (they are kept, so showing them again is instant). */
     setHidden(keys: Iterable<string>): void;
     /** The front-most surface under screen point (`x`, `y`) (canvas CSS px), or null. */
@@ -73,12 +89,15 @@ export declare class VolumeRegionMeshes {
      */
     clearFrame(): void;
     private sync;
+    /**
+     * Place `mesh` in the current box, adding its surface or updating it: at once, or through the
+     * placer, its result kept only if the mesh and the box are still the ones wanted. A placement
+     * already in flight for the same mesh and box is not asked again.
+     */
+    private place;
+    /** `mesh`'s surface with its vertices placed at `world`: updated in place, or added. */
+    private apply;
     private add;
     private opacityOf;
     private remove;
 }
-/**
- * Image px / slice coordinates → the volume's centred world box: pixel x of a `w`-wide image
- * spans the box's width, slice k sits at the middle of its share of the box's depth.
- */
-export declare function toWorld(vertices: Float32Array, frame: VolumeFrame): Float32Array;

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

@@ -99,6 +99,8 @@ export declare class VolumeScene implements NapariScene {
     histogram(channel: number, bins: number): IHistogram | null;
     isoControls(): IIsosurfaceControls | null;
     surface3dControls(): ISurface3dControls | null;
+    /** Gives the camera back napari-js's own depth range (see keepSceneInDepth). */
+    private restoreDepth;
     dispose(): void;
     /**
      * Restretch the volume's Z height live (driven by the in-view {@link NapariVolumeZHandle}). Only

package/lib/implementations/napari-js/spatial-tiles/cell-layers.d.ts

@@ -1,12 +1,23 @@
+import type { Colormap, RGBA } from 'napari-js';
 import type { Rgb } from '../../../contracts/colormap-lut';
 import type { SpatialDataPort } from '../../../contracts/ports/spatial-data.port';
 import type { SpatialViewState } from '../../../contracts/display-types';
 import { SpatialDataset } from '../../../contracts/spatial-dataset.contract';
 import { SpatialSelectionMask } from '../../../spatial/spatial-selection';
 import { DataRect } from '../../../spatial/lod';
+import { ContrastWindowCache } from '../napari-spatial-encoding';
 import type { CategoricalLookup } from './categorical-lookup';
 import type { OrderedLayerGroups, TileGroup } from './layer-groups';
 import type { PlanContext } from './plan-context';
+/** The cells' colours as a shapes layer takes them: per-shape RGBA, values over a colormap, or
+ *  one colour. */
+export interface CellColors {
+    values?: Float32Array;
+    colormap?: Colormap;
+    contrastLimits?: [number, number];
+    color?: RGBA;
+    faceColor?: Float32Array;
+}
 /** What the cell layers need from the service. */
 export interface CellLayersHost {
     /** The continuous LUT the view is using (so cells coloured by a gene match the markers). */
@@ -39,9 +50,25 @@ export declare class CellLayers {
     /** Continuous colourings' windows, per (vector, clip, log): `contrastWindow` sorts every
      *  value, and a selection or opacity change recolours with the vector unchanged (SPATIAL-12). */
     private readonly contrastWindows;
+    /**
+     * The plane of a 3D segmentation the view shows (see {@link setPlane}), or null: every set draws
+     * its own tiles.
+     */
+    private plane;
+    /** The region set opened for a boundary set's per-plane outlines: its id and the source. */
+    private planeSource;
     constructor(port: SpatialDataPort, groups: OrderedLayerGroups<TileGroup>, lookup: CategoricalLookup, host: CellLayersHost);
     /** True while outlines are on screen. */
     get outlinesShown(): boolean;
+    /**
+     * Show plane `plane` (an index into the region set's planes) of a 3D segmentation, or none: a
+     * boundary set that names its region set (`regionSource`, a cell outlined on every plane it spans)
+     * then draws that plane's outlines, rather than one outline per cell, so the cells follow the
+     * slice. Its cells keep the view's colouring, groups and selection.
+     */
+    setPlane(plane: number | null): void;
+    /** Close the region set opened for the per-plane outlines. */
+    dispose(): void;
     /** The viewer went away (its layers with it): the outlines are no longer shown. */
     detached(): void;
     /** Draw the cells covering `rect` at the level `pxPerUnit` calls for, or drop them. */
@@ -64,7 +91,33 @@ export declare class CellLayers {
      * view went stale or the dataset has no set to draw.
      */
     private cellGeometry;
+    /**
+     * The cells of boundary set `set` on the plane shown, from its region set (`regionSource`): the
+     * plane's tiles meeting `rect`, at the detail the zoom calls for, each outline owned by its cell
+     * (by its id among the observations'), minus the hidden groups. Undefined when it cannot be drawn
+     * so (no observation ids to tell its cells by, no port to open the set, or a plane it has not), so
+     * the set's own tiles are drawn; null when the view went stale.
+     */
+    private planeGeometry;
+    /** The region set `id`, opened once (another id closes the one before). */
+    private openPlaneSource;
     /** Remove the cell layers and forget what they showed. */
     drop(): void;
     private setPolygonsShown;
 }
+/** What {@link cellColorsFor} reads with: the port, the categorical columns, the windows cache, the LUT. */
+export interface CellColorDeps {
+    port: SpatialDataPort;
+    lookup: CategoricalLookup;
+    contrastWindows: ContrastWindowCache;
+    continuousLut(view: SpatialViewState): Rgb[];
+}
+/**
+ * The cells' colours by their owners (`owners[i]` the observation of shape i), by the view's
+ * cell-colour mode (Xenium Explorer's "Cell Color"): one RGBA per shape for a grouping, values +
+ * colormap for a measurement, one colour for "single". A selection mutes what it leaves out. The 2D
+ * cell outlines and the 3D cells both colour by it.
+ */
+export declare function cellColorsFor(deps: CellColorDeps, dataset: SpatialDataset, view: SpatialViewState, selection: SpatialSelectionMask, owners: Uint32Array): Promise<CellColors>;
+/** {@link cellColorsFor}'s colours as one RGBA (0..1) per shape, `n` shapes. */
+export declare function cellColorsRgba(colors: CellColors, n: number): Float32Array;

package/lib/implementations/napari-js/spatial-tiles/transcript-layers.d.ts

@@ -1,6 +1,7 @@
 import type { PointSymbol } from 'napari-js';
 import type { SpatialViewState } from '../../../contracts/display-types';
 import { SpatialDataset } from '../../../contracts/spatial-dataset.contract';
+import type { SpatialSelectionMask } from '../../../spatial/spatial-selection';
 import { DataRect } from '../../../spatial/lod';
 import { TranscriptGlyph } from '../../../spatial/glyphs';
 import type { CategoricalLookup } from './categorical-lookup';
@@ -40,8 +41,12 @@ export declare class TranscriptLayers {
     geneCountsIn(rect: DataRect): Record<string, number> | null;
     /** The viewer went away: no counts until the next plan. */
     detached(): void;
-    /** Draw the view's transcript markers (or drop them); an unchanged plan key is a no-op. */
-    plan(dataset: SpatialDataset, view: SpatialViewState, rect: DataRect, pxPerUnit: number, ctx: PlanContext): Promise<void>;
+    /**
+     * Draw the view's transcript markers (or drop them); an unchanged plan key is a no-op. With a
+     * `zBand`, the view shows one plane of a 3D assay: only the transcripts at that depth are drawn
+     * (summed density grids and aggregates, which mix depths, stay whole).
+     */
+    plan(dataset: SpatialDataset, view: SpatialViewState, rect: DataRect, pxPerUnit: number, ctx: PlanContext, zBand?: readonly [number, number] | null, selection?: SpatialSelectionMask | null): Promise<void>;
     /**
      * Gene icons: each entry drawn as its gene's napari-js point symbol, in the same one points
      * layer as the circles. With every gene drawn there is one icon for all of them — 18,000
@@ -53,6 +58,10 @@ export declare class TranscriptLayers {
      * for, drawn as the layer's disc or as each entry's `symbols` code.
      */
     private drawTranscripts;
+    /** The selection the last plan faded by, and its revision, bumped each time it changes. */
+    private lastSelection;
+    private selectionRevision;
+    private selectionRev;
     /** Per-entry colours, as packed RGBA. */
     private transcriptColors;
 }

package/lib/implementations/spatial-data-http/spatial-data-http.service.d.ts

@@ -3,6 +3,7 @@ import { Observable } from 'rxjs';
 import { SpatialDataPort, TranscriptTileQuery } from '../../contracts/ports/spatial-data.port';
 import { SpatialColumn, SpatialDataset, SpatialDensityRaster, SpatialEmbedding, SpatialPolygonTile, SpatialPolygons, CategoricalColumnMeta, SpatialMarkerGenes, SpatialTranscriptCounts, SpatialTranscriptSummary, SpatialTranscriptTile } from '../../contracts/spatial-dataset.contract';
 import { SpatialDatasetSummary, SpatialManifest } from './spatial-wire';
+import type { RegionSource } from '../../region-source/region-source';
 import * as i0 from "@angular/core";
 /**
  * A dataset selection that a newer selection (or a `clear`) overtook.
@@ -137,6 +138,12 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     /** Oldest first, past the entry cap or the byte budget, keeping the newest. */
     private evictTiles;
     private dropTile;
+    /**
+     * The region set a boundary set names (`polygonTiles.sets[i].regionSource`), served beside the
+     * datasets as an HTTP region source (`{base}/regions/{id}/…`, see `openHttpRegionSource`), its
+     * requests through the host's `HttpClient` as every other request here.
+     */
+    openRegionSet(id: string): Promise<RegionSource>;
     /**
      * The reference volume's voxels, single-flighted like the polygons.
      *

package/lib/region-editor/class-tree/class-tree.component.d.ts

@@ -33,6 +33,15 @@ export declare class ClassTreeComponent implements OnChanges {
     volume: boolean;
     /** The classes shown in 3D. */
     shown3d: ReadonlySet<string>;
+    /** Classes that can be drawn as individual cells here (a 3D segmentation's, in spatial 3D). */
+    cellable: ReadonlySet<string>;
+    /** Those drawn as individual cells now. */
+    individual: ReadonlySet<string>;
+    /** Draw a class (its subclasses with it) as individual cells, or merged again. */
+    toggleCells: EventEmitter<{
+        classes: string[];
+        individual: boolean;
+    }>;
     /** The classes hidden from view. */
     hidden: ReadonlySet<string>;
     pick: EventEmitter<ClassTreePick>;
@@ -63,6 +72,12 @@ export declare class ClassTreeComponent implements OnChanges {
     protected total(name: string): number;
     protected toggle(row: ClassTreeRow, event: Event): void;
     protected choose(name: string, event: Event): void;
+    /** A class (with its subclasses) as individual cells, or merged again: all of them as it is. */
+    protected flipCells(name: string, event: Event): void;
+    /** Whether every cellable class of `name`'s subtree is drawn as cells. */
+    protected allIndividual(name: string): boolean;
+    /** Whether `name` or a subclass can be drawn as cells. */
+    protected anyCellable(name: string): boolean;
     /** The eye: a class hidden (wholly) is shown again with its subclasses; otherwise they are hidden. */
     protected flipHidden(name: string, event: Event): void;
     protected flip3d(name: string, event: Event): void;
@@ -72,7 +87,7 @@ export declare class ClassTreeComponent implements OnChanges {
     protected readonly trackRow: (_: number, r: ClassTreeRow) => string;
     private refresh;
     static ɵfac: i0.ɵɵFactoryDeclaration<ClassTreeComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ClassTreeComponent, "region-class-tree", never, { "nodes": { "alias": "nodes"; "required": false; }; "counts": { "alias": "counts"; "required": false; }; "colorOf": { "alias": "colorOf"; "required": false; }; "picked": { "alias": "picked"; "required": false; }; "marked": { "alias": "marked"; "required": false; }; "volume": { "alias": "volume"; "required": false; }; "shown3d": { "alias": "shown3d"; "required": false; }; "hidden": { "alias": "hidden"; "required": false; }; }, { "pick": "pick"; "recolor": "recolor"; "toggle3d": "toggle3d"; "toggleHidden": "toggleHidden"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ClassTreeComponent, "region-class-tree", never, { "nodes": { "alias": "nodes"; "required": false; }; "counts": { "alias": "counts"; "required": false; }; "colorOf": { "alias": "colorOf"; "required": false; }; "picked": { "alias": "picked"; "required": false; }; "marked": { "alias": "marked"; "required": false; }; "volume": { "alias": "volume"; "required": false; }; "shown3d": { "alias": "shown3d"; "required": false; }; "cellable": { "alias": "cellable"; "required": false; }; "individual": { "alias": "individual"; "required": false; }; "hidden": { "alias": "hidden"; "required": false; }; }, { "toggleCells": "toggleCells"; "pick": "pick"; "recolor": "recolor"; "toggle3d": "toggle3d"; "toggleHidden": "toggleHidden"; }, never, never, true, never>;
 }
 /** Scroll the row matching `selector` inside `host` into view, if it is out of it. */
 export declare function scrollToPicked(host: HTMLElement, selector: string): void;

package/lib/region-editor/classes-panel/classes-panel.component.d.ts

@@ -41,6 +41,15 @@ export declare class ClassesPanelComponent implements OnChanges {
     volume: boolean;
     /** The classes shown in 3D. */
     shown3d: ReadonlySet<string>;
+    /** Classes that can be drawn as individual cells here (a 3D segmentation's, in spatial 3D). */
+    cellable: ReadonlySet<string>;
+    /** Those drawn as individual cells now. */
+    individual: ReadonlySet<string>;
+    /** Draw a class (its subclasses with it) as individual cells, or merged again. */
+    toggleCells: EventEmitter<{
+        classes: string[];
+        individual: boolean;
+    }>;
     /** The classes hidden from view. */
     hidden: ReadonlySet<string>;
     /** A class's eye (its name): hide it, or show it again. */
@@ -81,6 +90,6 @@ export declare class ClassesPanelComponent implements OnChanges {
     protected rowTooltip(name: string): string;
     protected removeTooltip(name: string): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<ClassesPanelComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ClassesPanelComponent, "region-classes-panel", never, { "classes": { "alias": "classes"; "required": false; }; "counts": { "alias": "counts"; "required": false; }; "matchMode": { "alias": "matchMode"; "required": false; }; "activeClass": { "alias": "activeClass"; "required": false; }; "picked": { "alias": "picked"; "required": false; }; "marked": { "alias": "marked"; "required": false; }; "selectedCount": { "alias": "selectedCount"; "required": false; }; "defaultClassName": { "alias": "defaultClassName"; "required": false; }; "volume": { "alias": "volume"; "required": false; }; "shown3d": { "alias": "shown3d"; "required": false; }; "hidden": { "alias": "hidden"; "required": false; }; "treeView": { "alias": "treeView"; "required": false; }; }, { "toggleHidden": "toggleHidden"; "toggle3d": "toggle3d"; "treeViewChange": "treeViewChange"; "pick": "pick"; "recolor": "recolor"; "remove": "remove"; "manage": "manage"; }, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ClassesPanelComponent, "region-classes-panel", never, { "classes": { "alias": "classes"; "required": false; }; "counts": { "alias": "counts"; "required": false; }; "matchMode": { "alias": "matchMode"; "required": false; }; "activeClass": { "alias": "activeClass"; "required": false; }; "picked": { "alias": "picked"; "required": false; }; "marked": { "alias": "marked"; "required": false; }; "selectedCount": { "alias": "selectedCount"; "required": false; }; "defaultClassName": { "alias": "defaultClassName"; "required": false; }; "volume": { "alias": "volume"; "required": false; }; "shown3d": { "alias": "shown3d"; "required": false; }; "cellable": { "alias": "cellable"; "required": false; }; "individual": { "alias": "individual"; "required": false; }; "hidden": { "alias": "hidden"; "required": false; }; "treeView": { "alias": "treeView"; "required": false; }; }, { "toggleCells": "toggleCells"; "toggleHidden": "toggleHidden"; "toggle3d": "toggle3d"; "treeViewChange": "treeViewChange"; "pick": "pick"; "recolor": "recolor"; "remove": "remove"; "manage": "manage"; }, never, ["*"], true, never>;
 }
 export {};

package/lib/region-editor/region-editor.component.d.ts

@@ -196,6 +196,10 @@ export declare class RegionEditorComponent implements OnInit, OnDestroy {
      */
     protected toggleClass3d(name: string, classes?: string[]): void;
     /** Hide (or show again) these classes' regions, wherever they are drawn. */
+    /** Classes that can be drawn as individual cells in spatial 3D, and those that are. */
+    protected cellableClasses: ReadonlySet<string>;
+    protected individualClasses: ReadonlySet<string>;
+    protected setClassesIndividual3d(classes: readonly string[], individual: boolean): void;
     protected setClassesHidden(classes: readonly string[], hidden: boolean): void;
     /** The surfaces shown in 3D, in their classes' colours now. */
     private groups3d;

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

@@ -6,6 +6,8 @@
  * Protocol: `{ id, op, ...args }` → `{ id, ok: true, result }` | `{ id, ok: false, error }`.
  */
 import { ReconstructOptions, SliceOutlines } from '../geometry/reconstruct';
+import { CellOutlines, CellsMesh } from '../geometry/cell-meshes';
+import { VolumeFrame } from '../geometry/place';
 import type { Mesh } from 'napari-js/geometry';
 import { ClassOutlines, RegionIndexPage, RegionIndexQuery, RegionSourceInfo, RegionTile } from './region-tiles';
 import type { SourceFeature } from './region-source';
@@ -44,6 +46,14 @@ export type RegionSourceRequest = {
     op: 'mesh';
     slices: readonly SliceOutlines[];
     options?: ReconstructOptions;
+} | {
+    op: 'cells';
+    cells: readonly CellOutlines[];
+    options?: ReconstructOptions;
+} | {
+    op: 'place';
+    vertices: Float32Array;
+    frame: VolumeFrame;
 } | {
     op: 'export';
     handle: number;
@@ -64,6 +74,8 @@ export interface RegionSourceResults {
     classes: Record<string, number>;
     outlines: ClassOutlines[];
     mesh: Mesh;
+    cells: CellsMesh;
+    place: Float32Array;
     export: string;
     close: null;
 }

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

@@ -53,6 +53,14 @@ export interface RegionSourceInfo {
     hierarchy?: RegionClassNode[];
     /** How the set wants to be drawn, when it says. */
     style?: RegionSourceStyle;
+    /**
+     * Where each plane is, when the set says: `sliceZ[i]` the z of plane `planes[i]`, in the units of
+     * the coordinates its outlines are in (a 3D segmentation's planes, in its observations' units).
+     * Planes stay ordinals for addressing; these place them (see the spatial 3D view).
+     */
+    sliceZ?: number[];
+    /** Microns per unit of the set's coordinates, when it says. */
+    micronsPerUnit?: number;
 }
 /** One feature as a tile carries it: identity, class and outline at the tile's level. */
 export interface TileFeature {

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

@@ -9,6 +9,8 @@
 import { RegionSource } from './region-source';
 import { RegionSourceRequest, RegionSourceResults } from './region-source-ops';
 import type { ReconstructOptions, SliceOutlines } from '../geometry/reconstruct';
+import type { CellOutlines, CellsMesh } from '../geometry/cell-meshes';
+import type { VolumeFrame } from '../geometry/place';
 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>;
@@ -58,6 +60,22 @@ export declare function sharedRegionSourceClient(): RegionSourceWorkerClient;
  * a collection without `features`.
  */
 export declare function openGeoJsonRegionSource(text: string, client?: RegionSourceWorkerClient): Promise<RegionSource>;
+/**
+ * The worker client cells are meshed on: a worker of its own, so a few thousand cells meshing does
+ * not hold up the region tiles the 2D views read from the shared one.
+ */
+export declare function cellsWorkerClient(): RegionSourceWorkerClient;
+/**
+ * A 3D segmentation's cells, each meshed by itself (see `geometry/cell-meshes`), in the cells'
+ * worker (on the main thread where there is none). Batch them: one call meshes its cells in one go.
+ */
+export declare function reconstructCellsInWorker(cells: readonly CellOutlines[], options?: ReconstructOptions, client?: RegionSourceWorkerClient): Promise<CellsMesh>;
+/**
+ * A mesh's vertices placed in a 3D view's world (see `geometry/place`), in the cells' worker: a
+ * class's surface has hundreds of thousands, and placing every surface on the main thread held it
+ * for seconds.
+ */
+export declare function placeInWorker(vertices: Float32Array, frame: VolumeFrame, client?: RegionSourceWorkerClient): Promise<Float32Array>;
 /**
  * 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).

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

@@ -12,7 +12,7 @@ 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 { RegionIndexPage, RegionIndexQuery, RegionSourceInfo } 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';
@@ -94,6 +94,38 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** The class groups shown in 3D, and the image they belong to. */
     private readonly classes3d$;
     private classes3dImage;
+    /**
+     * The spatial dataset's region set attached to its image (see attachDatasetRegionSet): the image
+     * (its region scope key), the set's key, and where its slices are when it says (its `sliceZ`),
+     * which places its surfaces in spatial 3D on an image of one plane. `shown3d` once its classes
+     * were shown in 3D by themselves, which happens once per image.
+     */
+    private datasetRegionSet;
+    /**
+     * Each image's attached region set, kept across image switches: coming back to the image finds
+     * its source still in the store (with what was taken from it, or deleted) and restores the set
+     * rather than attaching it again, which would start the source afresh.
+     */
+    private readonly attachedRegionSets;
+    /** The spatial dataset on offer (the port's), for the boundary set its region set is. */
+    private spatialDataset;
+    /**
+     * Whether the Annotations switch last hid every class in a spatial view (see syncAnnotations), so
+     * a change of it, not every view emission, hides or shows them.
+     */
+    private annotationsHidden;
+    /** The 3D view's global cells switch as last applied (see updateCells3d). */
+    private cells3dMode;
+    /** Classes set the other way than the global switch in the Region Editor. */
+    private readonly cells3dOverrides;
+    /** The classes drawn as individual cells in spatial 3D, as last applied. */
+    private readonly individual3d$;
+    /** The classes that can be drawn as individual cells now (see getCellableClasses3d$). */
+    private readonly cellable3d$;
+    /** Follows the dataset and the spatial view for {@link updatePlaneCells}. */
+    private readonly planeCellsSub;
+    /** The dataset region set's planes while they slice the plotted image (see getDatasetPlanes$). */
+    private readonly datasetPlanes$;
     /** The groups last asked for in 3D, with their colours: what an edit's rebuild shows again. */
     private shown3d;
     /**
@@ -202,6 +234,18 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     setImageSmoothingEnabled(enabled: boolean): void;
     setShowStack(showstack: boolean): void;
     setZIndex(zIndex: number): void;
+    /**
+     * The image's own slice for slider position `z`: 0 while the dataset region set's planes slice an
+     * image of one plane (the slider then picks the plane, see getDatasetPlanes$), else `z`.
+     */
+    private imageSlice;
+    /**
+     * The planes of the spatial dataset's region set (its `sliceZ`, in observation units) while they
+     * slice the plotted image, an image of one plane; null otherwise. The host's slice slider then
+     * runs over them: each position shows that plane's regions and, in the 2D spatial view, the
+     * observations and transcripts nearest it, over the same image.
+     */
+    getDatasetPlanes$(): Observable<readonly number[] | null>;
     getTrueImageSize(): {
         width: number;
         height: number;
@@ -299,6 +343,88 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
      * another image (see {@link regionImportTicket}; one is taken here when `ticket` is not given).
      */
     importRegionSourceOpener(open: RegionSourceOpener, ticket?: number): Promise<boolean>;
+    /**
+     * Attach a spatial dataset's region set (a 3D segmentation's cells, outlined on every plane they
+     * span) to its image, the image plotted now, as the image's own regions are: over every slice
+     * from the set's planes (`'planes'`), not marked imported (it is the dataset's, nothing to save),
+     * leaving the image's drawn regions as they are. Once per image and set: called again (the
+     * dataset re-emitted, the image re-plotted) it changes nothing. Where the set's slices are (its
+     * `sliceZ`) places its surfaces among the observations in spatial 3D, where the region editor then
+     * offers its classes in 3D; there, every class is shown once by itself (see showDatasetRegionSet3d).
+     * Back on an image the set was attached to, with its source still the store's, it is restored as
+     * it was (what was taken from the source, or deleted, stays so), not attached again.
+     * Resolves false, changing nothing (the source disposed), when another image was plotted or
+     * another set attached while it opened, it could not be opened, or the image has region sources
+     * of its own (which it would replace, see keepsOwnSources).
+     */
+    attachDatasetRegionSet(open: RegionSourceOpener, key: string): Promise<boolean>;
+    /**
+     * Whether the plotted image has region sources of its own (a served set, large saved ROIs, an
+     * annotation folder's slices), which attaching the dataset's set over every plane would replace,
+     * dropping them and what was taken from them: they are kept, and the set is not attached.
+     */
+    private keepsOwnSources;
+    /**
+     * Make `set` the plotted image's region set: its planes slice the image (its regions per plane,
+     * as a stack's per slice: those drawn before go to the plane shown), place its surfaces in
+     * spatial 3D and drive the slider.
+     */
+    private useDatasetRegionSet;
+    /**
+     * The dataset no longer names the attached set while its image is still plotted (see
+     * IVisualizer.releaseDatasetRegionSet): its planes, its surfaces and cells in 3D go, as on another
+     * image. Its attachment is kept (attachedRegionSets): the same set asked for again is restored.
+     */
+    releaseDatasetRegionSet(keep: string | null): void;
+    /** The dataset region set's classes while in spatial 3D: those that can be drawn as cells. */
+    getCellableClasses3d$(): Observable<ReadonlySet<string>>;
+    /** The classes the spatial 3D view draws as individual cells (see updateCells3d). */
+    getIndividualClasses3d$(): Observable<ReadonlySet<string>>;
+    /** Draw these classes as individual cells in spatial 3D, or merged again (the global switch aside). */
+    setClassesIndividual3d(classes: readonly string[], individual: boolean): void;
+    /**
+     * Which of the dataset region set's classes the spatial 3D view draws as individual cells: every
+     * one with the panel's global switch on "cells", none on "types", each class the Region Editor
+     * set the other way excepted. Turning the global switch resets those. The individual classes'
+     * merged surfaces are left out (see showRegionClasses3d); their cells are drawn instead.
+     */
+    private updateCells3d;
+    /**
+     * In the spatial views (2D and 3D), the spatial panel's Regions switch (`showAnnotations`, off by
+     * default) is every class's in the Region Editor's list, as their eyes are: off, every class is
+     * hidden (the drawn regions' and the dataset region set's cell types alike: their regions in 2D,
+     * their surfaces in 3D, and the eyes show it); on again, every class is shown. Applied when the
+     * switch changes, or on entering a spatial view with it off (so by default), so a class hidden or
+     * shown by its own eye meanwhile stays as it was set.
+     */
+    private syncAnnotations;
+    /**
+     * Every class the Region Editor lists for the image: the dataset region set's, those shown in 3D,
+     * the drawn regions', and any hidden now.
+     */
+    private knownClasses;
+    /**
+     * The Cells panel's boundary set that is the dataset's region set (the one naming it as its
+     * `regionSource`), while its planes are shown on the plotted image with its source still the
+     * store's; null otherwise.
+     */
+    private planeCellSet;
+    /**
+     * While the dataset region set's planes are shown, the Cells panel draws each plane's cells from
+     * it (its boundary set, see `CellLayers.setPlane`):
+     *  - that set is the panel's boundaries by default: a view that has not chosen a set (none yet, or
+     *    after a reset) is given it;
+     *  - in the 2D spatial view, while the panel draws them, the overlays do not draw the same
+     *    outlines a second time (`RegionStore.setRegionSourceDrawn`). They stay listed and editable
+     *    in the Region Editor, and are drawn by the overlays everywhere else.
+     */
+    private updatePlaneCells;
+    /**
+     * In spatial 3D, with the dataset's region set placed there: show each of its classes in 3D, in
+     * its colour, once per image, unless classes are shown already (the region editor's choice
+     * stands, and hiding them all stays hidden).
+     */
+    private showDatasetRegionSet3d;
     /** Empty every slice of a stack (its regions and undo history) for regions imported over it. */
     private enterImportedStack;
     getRegionSourceView$(): Observable<RegionSourceView | null>;
@@ -462,6 +588,8 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** Displayed slice. Only a volume-backed spatial dataset reads it, to keep a
      *  region drawn over one section from selecting the whole depth behind it. */
     private currentZIndex;
+    /** The slice shown, the plot type or the dataset's planes changed (the spatial controls recount). */
+    private readonly spatialViewChanged$;
     /** Angular calls this when the injector providing the router is destroyed — the host
      *  component for a `provideVisualization()` chain. The dataset subscription would
      *  otherwise keep the whole isolated chain reachable from the root data port. */
@@ -497,3 +625,14 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     static ɵfac: i0.ɵɵFactoryDeclaration<RoutingVisualizerService, [null, null, null, null, null, null, null, null, { optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<RoutingVisualizerService>;
 }
+/**
+ * A region set's classes as 3D groups, as the region editor's class tree shows them: one per root of
+ * its hierarchy with every class under it (one per class of a flat one), in the hierarchy's order;
+ * without a hierarchy, one per class its features have. Each in the colour the set gives it (its
+ * hierarchy's, else its features').
+ */
+export declare function regionSetGroups(info: RegionSourceInfo): Array<{
+    key: string;
+    classes: string[];
+    color: string;
+}>;

package/lib/spatial/observations-in-selection.d.ts

@@ -0,0 +1,43 @@
+import type { SpatialViewState } from '../contracts/display-types';
+import type { SpatialDataPort } from '../contracts/ports/spatial-data.port';
+import { type SpatialDataset } from '../contracts/spatial-dataset.contract';
+/**
+ * The observations of a selection (a mask), described: how many, by the grouping they are coloured
+ * by (else the cell types), the mean of a few measurements — or, for one cell, its id, its groups
+ * and its values. Pure but for the port's columns (cached by it).
+ */
+/** At most this many measurements (continuous columns) are given. */
+export declare const OBSERVATION_DETAIL_COLUMNS = 6;
+/** One group's observations in the selection. */
+export interface GroupCount {
+    name: string;
+    count: number;
+    /** The group's colour, as the legend shows it. */
+    color: string;
+}
+/** What {@link describeObservations} finds. */
+export interface ObservationsDescription {
+    total: number;
+    /** The grouping the observations are counted by, or null when the dataset has none. */
+    groupColumn: string | null;
+    /** Groups by count, most first (empty groups left out). */
+    groups: GroupCount[];
+    /**
+     * A few measurements: the mean over the selection (`mean` true), or one cell's own values. With
+     * one cell, its other groupings come first, as text.
+     */
+    measures: {
+        name: string;
+        value: string | number;
+        unit?: string;
+        mean: boolean;
+    }[];
+    /** The one cell's id, when the selection is one cell. */
+    cellId?: string;
+}
+/**
+ * Describe the observations `mask` selects (see {@link ObservationsDescription}): counted by the
+ * categorical column the view colours by, else the cell-type column; at most `maxMeasures`
+ * continuous columns averaged (or read, for one cell).
+ */
+export declare function describeObservations(port: Pick<SpatialDataPort, 'getColumn'>, dataset: SpatialDataset, view: Pick<SpatialViewState, 'colorBy' | 'cellTypeColumn' | 'groupColors'>, mask: Uint8Array, maxMeasures?: number): Promise<ObservationsDescription>;