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

package/lib/spatial/plane-cells.d.ts

@@ -0,0 +1,37 @@
+import type { SpatialImageRef, SpatialObservations, SpatialPolygonTile } from '../contracts/spatial-dataset.contract';
+import type { TileFeature } from '../region-source/region-tiles';
+/** Each observation's index by its id, or null when the observations carry no ids. */
+export declare function observationIndex(obs: SpatialObservations): Map<string, number> | null;
+/** A feature's cell id: its id without the slice a folder region set qualifies it with. */
+export declare function cellIdOf(featureId: string): string;
+/**
+ * The rings of `tiles`' features (each once, though a feature is in every tile it meets), owned by
+ * their cells, in observation units (the region set's are the image's pixels: back through `ref`).
+ * A feature of no observation, and an open one (a polyline), is left out; each ring of a feature
+ * (its parts and holes) is a ring of its cell.
+ */
+export declare function planeCellRings(tiles: readonly {
+    features: readonly TileFeature[];
+}[], index: ReadonlyMap<string, number>, ref: SpatialImageRef | null | undefined): SpatialPolygonTile;
+/** One plane's tiles of a region set: the plane's slice index (its place among the set's planes). */
+export interface PlaneTiles {
+    slice: number;
+    tiles: readonly {
+        features: readonly TileFeature[];
+    }[];
+}
+/**
+ * Each cell's outlines on every plane it spans, from the planes' tiles (a feature once, though in
+ * every tile it meets), for the 3D reconstruction of each cell by itself (`CellOutlines`, slice k
+ * at z = k). Only cells of `classes` (all when null), whose outlines' centre over all planes is in
+ * `within` (`[x0, y0, x1, y1]`, image px; anywhere when absent): the tiles fetched for an area hold
+ * the cells crossing its edge too, which belong to the area their centre is in.
+ */
+export declare function cellOutlinesFromTiles(planes: readonly PlaneTiles[], index: ReadonlyMap<string, number>, classes: ReadonlySet<string> | null, within?: readonly [number, number, number, number]): {
+    cell: number;
+    label: string | null;
+    slices: {
+        z: number;
+        rings: Float32Array[];
+    }[];
+}[];

package/lib/spatial/spatial-controls.facade.d.ts

@@ -1,3 +1,4 @@
+import type { Cells3dStatus } from '../contracts/display-types';
 import { Observable } from 'rxjs';
 import { PlotType } from '../contracts/plot-type';
 import { SpatialDataPort } from '../contracts/ports/spatial-data.port';
@@ -27,6 +28,9 @@ export interface SpatialRendererFeeds {
     readonly geneFilterFailed$?: {
         asObservable(): Observable<boolean>;
     };
+    readonly cells3dStatus$?: {
+        asObservable(): Observable<Cells3dStatus | null>;
+    };
     /** Observations projected to canvas pixels by the 3D camera, or null when the cloud is not mounted. */
     getSpatialScreenProjection(obs: SpatialObservations): Float32Array | null;
     /** The ids of the regions drawn over the 3D cloud in screen space (its lassos). */
@@ -45,6 +49,19 @@ export interface SpatialControlsContext {
     plotType(): PlotType;
     /** The displayed slice (a volume-backed dataset selects within one section). */
     zIndex(): number;
+    /**
+     * The dataset region set's planes while they slice an image of one plane (see the router's
+     * `getDatasetPlanes$`): the slice is then one of them, and a region selects within it. Optional.
+     */
+    planes?(): readonly number[] | null;
+    /**
+     * The dataset region set's planes (its `sliceZ`), whether or not they slice the image (a stack of
+     * as many planes is sliced by its own slices): the 2D view shows plane `zIndex()`'s transcripts.
+     * Optional.
+     */
+    slicePlanes?(): readonly number[] | null;
+    /** Emits when the plot type, the slice shown or the dataset's planes change. Optional. */
+    readonly viewChanged$?: Observable<unknown>;
 }
 /**
  * The spatial-omics controls (`ISpatialControls`) over a host's `SPATIAL_DATA_PORT`.
@@ -77,5 +94,47 @@ export declare class SpatialControlsFacade {
      * in its grid; by the drawn regions otherwise.
      */
     private roiSelectionMode;
+    /**
+     * The selections the "in selection" lists follow, as they change: the latest of three, as the user
+     * made them — the selected cells (a cell clicked, a legend group, a brush), the classes picked in
+     * the region editor (in spatial 3D the cell types of the type surfaces), or the regions selected on
+     * the image (2D only). Clearing the latest goes back to the one before, when it still stands. Emits
+     * (debounced) the sources standing, latest last, whenever the selection, the regions, the plane
+     * shown, the plot type, the dataset or `viewKey` of the view state change.
+     */
+    private selectionChanges$;
+    /**
+     * `work` as a stream: what it reports through `progress`, then its answer (or `failed`'s message);
+     * unsubscribing abandons it (`cancelled()` then says so).
+     */
+    private runCancellable;
+    /**
+     * What the latest selection in `active` is (see {@link selectionChanges$}), and where it applies:
+     * through the whole volume in spatial 3D; on the plane shown in 2D when the dataset's planes slice
+     * it and what is listed carries z (`hasZ`). `what` names what is listed, for the hints.
+     */
+    private resolveSelection;
+    /** The transcripts of the selection, by gene (see {@link selectionChanges$}). */
+    private transcriptsInSelection$;
+    /**
+     * Count the transcripts of the latest selection in `active`: through the whole volume in spatial
+     * 3D, on the plane shown in 2D when the dataset's planes slice it.
+     */
+    private transcriptsOf;
+    /** The observations of the selection, by group (see {@link selectionChanges$}). */
+    private observationsInSelection$;
+    /**
+     * The observations of the latest selection in `active`, by the grouping the observations are
+     * coloured by (else the cell types): every one in spatial 3D; in 2D, those on the plane shown when
+     * the dataset's planes slice it. One cell is described too: its id and its values.
+     */
+    private observationsOf;
+    /**
+     * The categorical column the picked classes are cell types of: the dataset's cell-type column
+     * when it holds any of them, else the first categorical column that does; null when none does.
+     */
+    private cellTypeColumnOf;
+    /** How far from a cell's centre its transcripts are looked for, in observation units. */
+    private cellReach;
     private build;
 }

package/lib/spatial/spatial-encoding.d.ts

@@ -33,7 +33,10 @@ export declare const DEFAULT_MUTED_OPACITY = 0.15;
  * Fallback categorical palette. Colour-blind-safe and stable, so a category
  * without an authored colour still lands somewhere sensible and lands there
  * every run (`fallbackColorFor` hashes the name — same name, same colour).
- * Okabe–Ito, plus two greys for long tails.
+ * Okabe–Ito and three greys, then twelve more (Tol's muted, a few of Paired), so a grouping of up
+ * to 22 groups (the MERFISH ileum's 20 cell types) has no two alike; the first ten come first, so a
+ * grouping of ten or fewer keeps its colours. jit-bioformats' `SegmentationRegionSet.PALETTE` (a 3D
+ * segmentation's region set, coloured at conversion) must stay this, colour for colour.
  */
 export declare const DEFAULT_CATEGORICAL_PALETTE: string[];
 interface MuteOptions {
@@ -129,4 +132,14 @@ export declare function isGrayscaleLut(lut: readonly Rgb[]): boolean;
  * them can disagree about what a colour means, whichever way the choice falls.
  */
 export declare function spatialContinuousLut(colormapValue: unknown, reverse?: boolean, override?: ColormapValue | null): Rgb[];
+/**
+ * Fade the transcripts outside a selection, as the cells and markers are: while `selected` (an
+ * observation mask) selects any cell, every packed-RGBA entry of `rgba` whose cell (`ownerOf(i)`)
+ * is not selected, or that is in no cell, has its alpha scaled to {@link DEFAULT_MUTED_OPACITY}.
+ * The selection's own transcripts keep their colour. Nothing changes without a selection.
+ */
+export declare function fadeOutsideSelection(rgba: Float32Array, count: number, ownerOf: (i: number) => number, selected: {
+    mask: Uint8Array;
+    count: number;
+} | null): void;
 export {};

package/lib/spatial/spatial-hover.d.ts

@@ -35,3 +35,26 @@ export type HoverSource = {
  * cell whose annotation is genuinely missing.
  */
 export declare function hoverText(source: HoverSource | null, index: number): string[] | null;
+/**
+ * What the 3D view says of a cell under the pointer (a 3D segmentation's, drawn by itself or as
+ * its type's surface): its type (the cell-type column), its id, and a few of its measurements.
+ */
+export interface CellInfo {
+    /** The cell-type column, its categories and each observation's code (null without one). */
+    typeName: string | null;
+    categories: readonly string[];
+    codes: Uint16Array | null;
+    /** Cells per category, by code. */
+    counts: Uint32Array | null;
+    ids?: readonly string[];
+    /** Measurements shown (the dataset's continuous columns, a few). */
+    measures: readonly {
+        name: string;
+        values: Float32Array;
+        unit?: string;
+    }[];
+}
+/** The tooltip of cell `index`: its type, its id, the colouring's value (when not the type), measurements. */
+export declare function cellText(info: CellInfo | null, index: number, color: HoverSource | null): string[] | null;
+/** The tooltip of a cell type's surface: its name (and title), and how many cells it has. */
+export declare function cellTypeText(info: CellInfo | null, key: string, label?: string): string[];

package/lib/spatial/spatial-planes.d.ts

@@ -0,0 +1,22 @@
+import { SpatialObservations } from '../contracts/spatial-dataset.contract';
+/**
+ * The planes a spatial dataset's region set was outlined on (its `sliceZ`, in observation units,
+ * one per slice in slice order), as the 2D view slices them over an image of one plane: plane `k`
+ * holds whatever lies nearer to it than to its neighbours, so each z belongs to exactly one plane
+ * and the planes together hold the whole depth.
+ *
+ * Pure, like `spatial-sections.ts` (which offers a sectioned dataset's own z values; these are the
+ * planes its segmentation was imaged at).
+ */
+/**
+ * The z band of plane `k`: from halfway to the plane before to halfway to the one after (open
+ * ended past the first and the last). The planes may run either way; `[lo, hi)` comes out ordered.
+ */
+export declare function planeBand(planes: readonly number[], k: number): [number, number];
+/** Whether `z` lies in `band` (`[lo, hi)`; a non-finite z lies in none). */
+export declare function inBand(z: number, band: readonly [number, number]): boolean;
+/**
+ * Indices of the observations on plane `k` (see {@link planeBand}). Every observation is when the
+ * dataset carries no z: a flat dataset has nothing to slice.
+ */
+export declare function observationsOnPlane(obs: SpatialObservations, planes: readonly number[], k: number): Uint32Array;

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

@@ -42,8 +42,9 @@ export declare function mutedFromSelection(selection: SpatialSelectionMask): Uin
  * the shared `geometry/ring` one the region overlays and tools use.
  */
 export declare function pointInRing(xs: readonly number[], ys: readonly number[], px: number, py: number): boolean;
+export declare function inBounds(b: Bounds, px: number, py: number): boolean;
 /** A region flattened to something testable: bounds + a hit test. */
-interface Shape {
+export interface Shape {
     bounds: Bounds;
     hit(px: number, py: number): boolean;
 }

package/lib/spatial/spatial-tile-merge.d.ts

@@ -40,6 +40,15 @@ export declare function filterTranscripts(t: SpatialTranscriptTile, px: Float32A
     merged: SpatialTranscriptTile;
     px: Float32Array;
 };
+/**
+ * The transcripts of a tile whose z lies in `band` (`[lo, hi)`, see `planeBand`), with their
+ * marker sizes: the 2D view of one plane of a 3D assay. An aggregated entry stands for transcripts
+ * at several depths, so a tile of them is kept whole.
+ */
+export declare function transcriptsInBand(t: SpatialTranscriptTile, px: Float32Array, band: readonly [number, number]): {
+    merged: SpatialTranscriptTile;
+    px: Float32Array;
+};
 /** The median of `v`, from a sample of about 1024 values. */
 export declare function median(v: Float32Array): number;
 /** Concatenate tiles' rings into one set, dropping rings already seen (a cell straddling

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

@@ -0,0 +1,95 @@
+import type { SpatialDataPort } from '../contracts/ports/spatial-data.port';
+import { type SpatialBounds, type SpatialImageRef, type SpatialObservations, type SpatialTileLevel } from '../contracts/spatial-dataset.contract';
+import type { TileKey } from './lod';
+import { type Shape } from './spatial-selection';
+/**
+ * The transcripts of a selection, by gene: the molecules of the selected cells (each transcript
+ * tile names the cell every molecule lies in), or those inside drawn regions — over the whole depth
+ * (spatial 3D) or on one plane (the 2D view of a sliced dataset).
+ *
+ * Read from the finest level of the transcript pyramid, every gene (`ALL_GENES`), and only the
+ * tiles the selection touches: a cell's transcripts lie near it, a region's inside its bounds.
+ * Pure but for the port; the facade decides what is selected.
+ */
+/** At most this many tiles are read for one list; a selection spanning more is counted in part. */
+export declare const TRANSCRIPT_LIST_MAX_TILES = 2048;
+/** About this many transcripts at most are read for one list (estimated from the dataset's mean). */
+export declare const TRANSCRIPT_LIST_MAX_TRANSCRIPTS = 20000000;
+/**
+ * How far from a cell's centre its transcripts are looked for, in microns: past the largest cells'
+ * reach (a cell's molecules lie inside its outline; Baysor cells of the ileum are up to ~25 µm).
+ */
+export declare const CELL_REACH_MICRONS = 30;
+/**
+ * How many level-0 tiles one list may read: {@link TRANSCRIPT_LIST_MAX_TILES}, fewer when the
+ * dataset's tiles are dense (its transcripts over the tiles of its bounds), so that about
+ * {@link TRANSCRIPT_LIST_MAX_TRANSCRIPTS} are read at most — a whole cell type of a sparse section
+ * is read whole, of a dense one in part.
+ */
+export declare function tileBudget(meta: {
+    bounds: SpatialBounds;
+    count?: number;
+    levels: readonly SpatialTileLevel[];
+}): number;
+/** One gene's transcripts in the selection. */
+export interface GeneCount {
+    name: string;
+    count: number;
+}
+/** What {@link countTranscripts} found. */
+export interface TranscriptCount {
+    total: number;
+    /** Distinct cells the counted transcripts lie in (those in no cell are not counted here). */
+    cells: number;
+    /** Genes by count, most first. */
+    genes: GeneCount[];
+    /** Some tiles could not be read (or were left out): the counts are a lower bound. */
+    partial: boolean;
+}
+/** Which transcripts count: those of these cells, or those inside these shapes (image px). */
+export type TranscriptFilter = {
+    kind: 'cells';
+    mask: Uint8Array;
+} | {
+    kind: 'shapes';
+    shapes: readonly Shape[];
+    imageRef?: SpatialImageRef;
+};
+/**
+ * Level-0 tiles within `reach` of the selected cells' centres (observation units), clipped to
+ * `bounds`. When there are more than `max`, those holding the most selected cells are kept and
+ * `partial` says so.
+ */
+export declare function tilesAroundCells(obs: SpatialObservations, mask: Uint8Array, reach: number, levels: readonly SpatialTileLevel[], bounds: SpatialBounds | null | undefined, max?: number): {
+    tiles: TileKey[];
+    partial: boolean;
+};
+/**
+ * Level-0 tiles under `shapes` (image px, mapped to observation units through `imageRef`), clipped
+ * to `bounds`; at most `max`, the most covered first.
+ */
+export declare function tilesUnderShapes(shapes: readonly Shape[], imageRef: SpatialImageRef | undefined, levels: readonly SpatialTileLevel[], bounds: SpatialBounds | null | undefined, max?: number): {
+    tiles: TileKey[];
+    partial: boolean;
+};
+/**
+ * Count the transcripts of `tiles` (level 0, every gene) that pass `filter` and, when given, lie in
+ * the z `band`, by gene (`names` are the dataset's genes by code, `transcriptTiles.genes`).
+ * Resolves null once `cancelled()` says so; a tile that fails to load leaves the count partial.
+ */
+export declare function countTranscripts(opts: {
+    port: SpatialDataPort;
+    tiles: readonly TileKey[];
+    quality: 'high' | 'all';
+    filter: TranscriptFilter;
+    band?: readonly [number, number] | null;
+    names?: readonly string[] | null;
+    cancelled?: () => boolean;
+    /** Tiles left out before counting (see {@link tilesAroundCells}). */
+    partial?: boolean;
+}): Promise<TranscriptCount | null>;
+/** The cells of `categories` (names) in a categorical column's `codes`, as a selection mask. */
+export declare function cellsOfCategories(codes: ArrayLike<number>, categories: readonly string[], names: readonly string[]): {
+    mask: Uint8Array;
+    count: number;
+};

package/lib/spatial-controls/spatial-cells-panel/spatial-cells-panel.component.d.ts

@@ -1,14 +1,14 @@
-import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
+import { OnChanges, SimpleChanges } from '@angular/core';
 import type { ISpatialControls } from '../../contracts/visualizer.contract';
 import type { SpatialDataset } from '../../contracts/spatial-dataset.contract';
-import { SpatialViewState } from '../../contracts/display-types';
+import { SpatialViewState, Cells3dStatus } from '../../contracts/display-types';
 import { PanelOption } from '../../spatial/spatial-panel-model';
-import type { GenePickerModel } from '../spatial-gene-picker';
 import * as i0 from "@angular/core";
 /**
- * The Cells section, as Xenium Explorer's: the outlines' on/off switch, which boundary set
- * is drawn, how cells are coloured (with the gene, the colour, or the colour bar that
- * goes with it), the {@link SpatialGroupsPanelComponent groups}, and how cells are drawn.
+ * The Observations section's "Cell segmentations" part (projected into it), shown while the
+ * observations are shown as cells: which boundary sets are drawn and how the cells are drawn (fill,
+ * outline, opacity), or in 3D, by cell type or each by itself. Their colour is the section's
+ * shared "Colour by", the markers' too.
  *
  * Writes only through `controls.setViewState`.
  */
@@ -19,19 +19,18 @@ export declare class SpatialCellsPanelComponent implements OnChanges {
     dataset: SpatialDataset | null;
     /** The current spatial view state: what is drawn, and how. */
     view: SpatialViewState;
-    /** The gene list the "Gene Expression" colouring picks from, shared with the other
-     *  gene dropdowns. */
-    genes: GenePickerModel | null;
-    /** The observations' continuous colour bar, shown for the gene colouring while it has one. */
-    colorBarCss: string | null;
-    /** Whether the section is expanded. */
-    open: boolean;
-    /** Asks to open or close it; two-way with `open`. */
-    readonly openChange: EventEmitter<boolean>;
-    /** Virtual-scrolled only past this many options: the scroller earns its complexity for
-     *  a few thousand names, and for eight it adds only overhead — a virtual viewport that
-     *  short swallows the clicks it is meant to forward. */
-    protected readonly geneVirtualScrollFrom = 200;
+    /**
+     * In the 3D view: the cells are a 3D segmentation's, drawn by cell type or each by itself, and
+     * the 2D boundaries and draw mode do not apply.
+     */
+    is3d: boolean;
+    /** The 3D view's individual cells as they stand (null: none drawn). */
+    cells3dStatus: Cells3dStatus | null;
+    /** How the 3D view draws the cells: one surface per cell type, or each cell by itself. */
+    protected readonly cells3dOptions: PanelOption<SpatialViewState['cells3d']>[];
+    protected onCells3d(mode: SpatialViewState['cells3d']): void;
+    /** What the 3D cells' status line says, or null. */
+    protected get cells3dHint(): string | null;
     protected readonly cellDrawOptions: PanelOption<SpatialViewState['cellDraw']>[];
     /**
      * Option lists for the cell controls. Built once per dataset rather than in getters: a
@@ -48,11 +47,6 @@ export declare class SpatialCellsPanelComponent implements OnChanges {
         name: string;
         label: string;
     }[];
-    /** Cell colour modes on offer (Xenium Explorer's "Cell Color"). */
-    protected cellColorOptions: PanelOption<SpatialViewState['cellColorMode']>[];
-    /** The density colour bar, rebuilt only when its colormap changes (a 256-entry LUT). */
-    protected densityColorBarCss: string;
-    private densityBarFor;
     ngOnChanges(changes: SimpleChanges): void;
     /** Whether outlines are on — the explicit choice, or automatically for data that has them. */
     protected get cellsOn(): boolean;
@@ -73,9 +67,6 @@ export declare class SpatialCellsPanelComponent implements OnChanges {
     protected onCellDraw(draw: SpatialViewState['cellDraw']): void;
     protected onCellOpacity(value: number | undefined): void;
     protected onCellOpacityPercent(v: number | null): void;
-    protected onCellColorMode(mode: SpatialViewState['cellColorMode']): void;
-    protected onCellColorGene(gene: string | null): void;
-    protected onCellSingleColor(hex: string): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SpatialCellsPanelComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialCellsPanelComponent, "spatial-cells-panel", never, { "controls": { "alias": "controls"; "required": false; }; "dataset": { "alias": "dataset"; "required": false; }; "view": { "alias": "view"; "required": false; }; "genes": { "alias": "genes"; "required": false; }; "colorBarCss": { "alias": "colorBarCss"; "required": false; }; "open": { "alias": "open"; "required": false; }; }, { "openChange": "openChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialCellsPanelComponent, "spatial-cells-panel", never, { "controls": { "alias": "controls"; "required": false; }; "dataset": { "alias": "dataset"; "required": false; }; "view": { "alias": "view"; "required": false; }; "is3d": { "alias": "is3d"; "required": false; }; "cells3dStatus": { "alias": "cells3dStatus"; "required": false; }; }, {}, never, never, true, never>;
 }

package/lib/spatial-controls/spatial-color-by/spatial-color-by.component.d.ts

@@ -0,0 +1,64 @@
+import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
+import type { ISpatialControls } from '../../contracts/visualizer.contract';
+import type { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import { ColormapNode, SpatialViewState } from '../../contracts/display-types';
+import type { PanelOption } from '../../spatial/spatial-panel-model';
+import type { GenePickerModel } from '../spatial-gene-picker';
+import type { SpatialLegendEntry } from '../spatial-key/spatial-key.model';
+import * as i0 from "@angular/core";
+/** What colours the observations: a grouping, a gene, a measurement, or one colour. */
+export type ColorByMode = 'group' | 'gene' | 'measure' | 'single';
+/**
+ * The Observations section's "Colour by": one colouring for the markers and the cells alike —
+ * a grouping (the {@link SpatialGroupsPanelComponent groups} with their colours and switches),
+ * one gene's expression, a measurement (a numeric column), or one colour. Each choice writes
+ * the markers' colour source (`colorBy`) and the cells' (`cellColorMode` and its own fields)
+ * together, so the two cannot disagree.
+ *
+ * Writes only through `controls.setViewState`.
+ */
+export declare class SpatialColorByComponent implements OnChanges {
+    /** The spatial controls this panel reads and writes through; null without a `SPATIAL_DATA_PORT`. */
+    controls: ISpatialControls | null;
+    /** The dataset on offer, or null. */
+    dataset: SpatialDataset | null;
+    /** The current spatial view state. */
+    view: SpatialViewState;
+    /** The gene list the gene colouring picks from, shared with the other gene dropdowns. */
+    genes: GenePickerModel | null;
+    /** The key's categorical legend, or null (continuous). */
+    legend: SpatialLegendEntry[] | null;
+    /** The key's continuous colour bar (a CSS gradient), or null. */
+    colorBarCss: string | null;
+    /** The selected category (its code), for highlighting its group. */
+    selectedCategory: number | null;
+    /** Colormap tree for the continuous colour scale. */
+    colormapOptions: ColormapNode[];
+    /** A group was clicked: its category's code, to select its observations. */
+    readonly categoryClicked: EventEmitter<number>;
+    /** Virtual-scrolled only past this many options (see the gene dropdowns elsewhere). */
+    protected readonly geneVirtualScrollFrom = 200;
+    /** The modes the dataset can be coloured in. */
+    protected modeOptions: PanelOption<ColorByMode>[];
+    /** The dataset's numeric columns. */
+    protected measureOptions: PanelOption<string>[];
+    /** A mode picked before its gene or measurement is: shown, nothing written yet. */
+    private pending;
+    ngOnChanges(changes: SimpleChanges): void;
+    /** The mode on show: one picked and waiting for its value, else what the view is coloured by. */
+    protected get mode(): ColorByMode | null;
+    /** What the view is coloured by, as a mode; null for the flat default. */
+    private get viewMode();
+    /** The gene the observations are coloured by, or null. */
+    protected get selectedGene(): string | null;
+    /** The measurement the observations are coloured by, or null. */
+    protected get selectedMeasure(): string | null;
+    protected onMode(mode: ColorByMode | null): void;
+    /** Colour the markers and the cells by gene `name`. */
+    protected onGene(name: string | null): void;
+    /** Colour the markers and the cells by measurement `name`. */
+    protected onMeasure(name: string | null): void;
+    protected onSingleColor(hex: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialColorByComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialColorByComponent, "spatial-color-by", never, { "controls": { "alias": "controls"; "required": false; }; "dataset": { "alias": "dataset"; "required": false; }; "view": { "alias": "view"; "required": false; }; "genes": { "alias": "genes"; "required": false; }; "legend": { "alias": "legend"; "required": false; }; "colorBarCss": { "alias": "colorBarCss"; "required": false; }; "selectedCategory": { "alias": "selectedCategory"; "required": false; }; "colormapOptions": { "alias": "colormapOptions"; "required": false; }; }, { "categoryClicked": "categoryClicked"; }, never, never, true, never>;
+}

package/lib/spatial-controls/spatial-controls.component.d.ts

@@ -1,7 +1,7 @@
 import { EventEmitter, NgZone, OnInit } from '@angular/core';
 import { IVisualizer, ISpatialControls, RoiSelectionMode } from '../contracts/visualizer.contract';
 import { SpatialDataset } from '../contracts/spatial-dataset.contract';
-import { ColormapNode, SpatialViewState } from '../contracts/display-types';
+import { Cells3dStatus, ColormapNode, SpatialViewState } from '../contracts/display-types';
 import { PanelOption, parseGeneGroups } from '../spatial/spatial-panel-model';
 import { SpatialSelectionMask } from '../spatial/spatial-selection';
 import { GenePickerModel } from './spatial-gene-picker';
@@ -137,14 +137,29 @@ export declare class SpatialControlsComponent implements OnInit {
     protected get hasSelection(): boolean;
     /** Boundaries on offer: tiled (level-of-detail) or whole-dataset rings. */
     protected get hasCells(): boolean;
+    /** The 3D view's individual cells as they stand (null: none drawn). */
+    protected cells3dStatus: Cells3dStatus | null;
+    /**
+     * Whether the router has the dataset's region set attached and placed (null: it does not say).
+     * See {@link hasCells3d}.
+     */
+    protected cells3dAvailable: boolean | null;
+    /**
+     * The dataset's cells can be drawn in 3D: its boundaries name a 3D segmentation's region set, and
+     * it is attached with its planes (else the 3D view draws no cells, and the markers stay).
+     */
+    protected get hasCells3d(): boolean;
     /** Transcripts on offer: tiles to draw, or a density map. */
     protected get hasTranscripts(): boolean;
     /** Whether the 3D cloud can draw the transcripts too: they carry z (a MERFISH volume's do). */
     protected get hasTranscripts3d(): boolean;
     protected onShowImage(on: boolean): void;
+    /** The reference volume, in 3D (the Volume section's switch). */
+    protected onShowVolume(on: boolean): void;
+    protected onVolumeOpacity(value: number | undefined): void;
     protected onShowAnnotations(on: boolean): void;
     /** Which collapsible sections are open. Per dialog instance, not persisted. */
-    protected open: Record<'images' | 'cells' | 'transcripts' | 'annotations' | 'observations', boolean>;
+    protected open: Record<'images' | 'volume' | 'transcripts' | 'annotations' | 'observations', boolean>;
     protected toggleSection(name: keyof SpatialControlsComponent['open']): void;
     /** Expand or collapse a section — what a panel's header asks for. */
     protected setOpen(name: keyof SpatialControlsComponent['open'], on: boolean): void;

package/lib/spatial-controls/spatial-groups-panel/spatial-groups-panel.component.d.ts

@@ -1,16 +1,18 @@
-import { ChangeDetectorRef, NgZone, OnChanges, SimpleChanges } from '@angular/core';
+import { ChangeDetectorRef, EventEmitter, NgZone, OnChanges, SimpleChanges } from '@angular/core';
 import type { ISpatialControls } from '../../contracts/visualizer.contract';
 import type { SpatialDataset } from '../../contracts/spatial-dataset.contract';
 import { SpatialViewState } from '../../contracts/display-types';
 import { GroupOptionSection, GroupRow, PanelOption } from '../../spatial/spatial-panel-model';
 import * as i0 from "@angular/core";
 /**
- * The cells' grouping, as Xenium Explorer's Groups section: the group picker (columns under
- * their section heading, a k-means family once, with its k beside it), CSV import of a new
+ * The observations' grouping, as Xenium Explorer's Groups section: the group picker (columns
+ * under their section heading, a k-means family once, with its k beside it), CSV import of a new
  * grouping, and the grouping's categories with their colours (each one's swatch opens a colour
- * picker), cell counts and show/hide switches.
+ * picker), cell counts and show/hide switches. A group's name selects its observations.
  *
- * Writes only through `controls.setViewState` (`cellTypeColumn`, `hiddenGroups`, `groupColors`).
+ * The Observations section's "Colour by" in Group mode: the grouping colours the markers and the
+ * cells alike. Writes only through `controls.setViewState` (`cellTypeColumn` with `colorBy` and
+ * `cellColorMode`, `hiddenGroups`, `groupColors`).
  */
 export declare class SpatialGroupsPanelComponent implements OnChanges {
     private readonly zone;
@@ -21,6 +23,10 @@ export declare class SpatialGroupsPanelComponent implements OnChanges {
     dataset: SpatialDataset | null;
     /** The current spatial view state: what is drawn, and how. */
     view: SpatialViewState;
+    /** The category selected (its code in the grouping), for highlighting its row. */
+    selectedCategory: number | null;
+    /** A group's name was clicked: its category's code in the grouping, to select its observations. */
+    readonly categoryClicked: EventEmitter<number>;
     /**
      * The group picker: categorical columns under their section heading, a family of
      * variants (k-means at k = 2…10) listed once. Values are a column name, or
@@ -53,6 +59,10 @@ export declare class SpatialGroupsPanelComponent implements OnChanges {
     protected onGroupEntry(value: string): void;
     protected onGroupVariant(name: string): void;
     onCellTypeColumn(name: string | null): void;
+    /** Group `label`'s category code in the active grouping, or -1. */
+    protected codeOf(label: string): number;
+    /** Select (or, selected already, clear) group `label`'s observations. */
+    protected onGroupClicked(label: string): void;
     /** {@link SpatialViewState.hiddenGroups} as a set, for the per-row checks. */
     private hiddenGroups;
     protected isGroupShown(label: string): boolean;
@@ -79,5 +89,5 @@ export declare class SpatialGroupsPanelComponent implements OnChanges {
     /** Apply an async result inside the zone and re-render this OnPush panel. */
     private apply;
     static ɵfac: i0.ɵɵFactoryDeclaration<SpatialGroupsPanelComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialGroupsPanelComponent, "spatial-groups-panel", never, { "controls": { "alias": "controls"; "required": false; }; "dataset": { "alias": "dataset"; "required": false; }; "view": { "alias": "view"; "required": false; }; }, {}, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialGroupsPanelComponent, "spatial-groups-panel", never, { "controls": { "alias": "controls"; "required": false; }; "dataset": { "alias": "dataset"; "required": false; }; "view": { "alias": "view"; "required": false; }; "selectedCategory": { "alias": "selectedCategory"; "required": false; }; }, { "categoryClicked": "categoryClicked"; }, never, never, true, never>;
 }