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

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>;

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 {
@@ -73,6 +76,16 @@ export declare function parseHex(hex: string): Rgb;
  * 40-cluster column still gets stable, distinct-ish colours.
  */
 export declare function resolveCategoryColors(meta: CategoricalColumnMeta, palette?: string[]): string[];
+/** The user's group colours: by column name, then category (see `SpatialViewState.groupColors`). */
+export type GroupColorOverrides = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/**
+ * Categorical column `column`'s colours ({@link resolveCategoryColors}) with the user's choices
+ * for its groups over them. Every place a grouping is coloured goes through this, so a group
+ * recoloured in the list is that colour on the cells, the markers, the legend and the charts.
+ */
+export declare function categoryColorsFor(column: string, meta: CategoricalColumnMeta, overrides?: GroupColorOverrides | null): string[];
+/** What a cache keyed on a grouping's colours must include of the user's choices for it. */
+export declare function groupColorsKey(column: string | null, overrides?: GroupColorOverrides | null): string;
 /** Categorical column → flat per-point RGBA (length `4 * codes.length`). */
 export declare function encodeCategorical(codes: Uint16Array, opts: CategoricalEncodingOptions): Float32Array;
 /** Continuous column / gene vector → flat per-point RGBA. */
@@ -119,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>;
 }