@jax-data-science/sci-image-visualizer 0.3.2 → 0.4.0

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

@@ -0,0 +1,73 @@
+import { SpatialDataset, SpatialObservations } from '../contracts/spatial-dataset.contract';
+/**
+ * Turning a cell cloud into a density field — the honest way to render a cluster
+ * in 3D when the sections it was measured on are hundreds of microns apart.
+ *
+ * Individual cells CANNOT be interpolated between sections: consecutive sections
+ * sample entirely different cells, so there is no correspondence to interpolate
+ * along, and inventing positions would fabricate observations indistinguishable
+ * from measured ones. A density field is a different object: a continuous
+ * estimate, legitimately defined between the planes that were imaged, and it
+ * renders as a translucent cloud rather than as dots, so it reads as an estimate.
+ *
+ * Two things make the estimate honest rather than decorative, and both are
+ * implemented here:
+ *  - the kernel is **anisotropic**, with a z bandwidth at least the section
+ *    spacing. An isotropic kernel leaves one disc per section — a sampling
+ *    artefact that looks like biology;
+ *  - the field is **coverage-normalised** along z (Nadaraya–Watson): unsampled
+ *    planes would otherwise read as genuinely empty tissue rather than as tissue
+ *    nobody imaged.
+ */
+/** The voxel lattice a density field is estimated on. */
+export interface DensityGrid {
+    width: number;
+    height: number;
+    depth: number;
+    /** World size of one voxel per axis, in the observations' units. */
+    voxelSize: [number, number, number];
+}
+export interface DensityOptions {
+    /** Kernel σ per axis, in the observations' units. */
+    sigma: [number, number, number];
+    /** Observations to include. Every observation when absent. */
+    indices?: Uint32Array;
+}
+/**
+ * The lattice to estimate on.
+ *
+ * A dataset with a registered volume estimates on that volume's own box, so the
+ * field lands exactly on the anatomy it will be drawn inside — `stride` coarsens
+ * it (density is smooth by construction, and an eighth of the voxels is an eighth
+ * of the work) while keeping the physical extent identical, so the two still
+ * align. Without a volume the box comes from the observations' own bounds.
+ */
+export declare function densityGrid(dataset: SpatialDataset, stride?: number, targetLongAxis?: number, zStride?: number): DensityGrid | null;
+/**
+ * In-place separable Gaussian along one axis of a w x h x d field.
+ *
+ * Exported because the gene-map volume estimates a different quantity on the same
+ * lattice with the same kernel (see `spatial-expression.ts`): two copies of a
+ * separable blur would be two chances to smooth the estimate and its normaliser
+ * differently, which is the one thing a Nadaraya-Watson field cannot survive.
+ */
+export declare function blurVolumeAxis(field: Float32Array, w: number, h: number, d: number, axis: 0 | 1 | 2, sigmaVox: number): void;
+/**
+ * Rasterise observations into a uint8 density field on `grid`.
+ *
+ * Returned as uint8 scaled to its own maximum: a `VolumeLayer` renders 0..255, and
+ * the absolute cell count per voxel is not the readable quantity anyway — where
+ * the cluster is dense RELATIVE to itself is. Null when nothing lands on the grid,
+ * so the caller draws no layer rather than an empty box.
+ */
+export declare function rasterizeDensity(obs: SpatialObservations, grid: DensityGrid, opts: DensityOptions): Uint8Array | null;
+/**
+ * Default kernel for a grid: in-plane tight, along z at least the section
+ * spacing.
+ *
+ * The z term is the load-bearing one — 1.5 voxels of a grid whose depth voxel IS
+ * the section spacing puts σ just above one section gap, which is the smallest
+ * bandwidth that can bridge one without leaving a disc per plane. `smoothing`
+ * scales all three for the user control.
+ */
+export declare function defaultSigma(grid: DensityGrid, smoothing?: number): [number, number, number];

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

@@ -0,0 +1,155 @@
+import { Rgb } from '../contracts/colormap-lut';
+import { CategoricalColumnMeta, SpatialObservations } from '../contracts/spatial-dataset.contract';
+import { ColormapValue } from '../contracts/display-types';
+/**
+ * Turning spatial-omics columns into per-point visual attributes.
+ *
+ * Pure — no Angular, no RxJS, no renderer — like `plotly-trace-builders.ts`, so
+ * the encodings are testable on their own and shared by any backend that grows
+ * a spatial mode.
+ *
+ * The rules here are the ones the CosMx analysis guidance prescribes, made
+ * explicit rather than left to each call site:
+ *  - count-like columns read on a **log** scale (linear collapses them against a
+ *    few bright outliers);
+ *  - contrast windows come from **percentiles**, not min/max, so a single
+ *    saturated spot doesn't flatten everything else;
+ *  - context is kept by **muting** rather than hiding — background points stay
+ *    visible at low alpha so the tissue shape survives.
+ *
+ * COLOUR REPRESENTATION
+ * ---------------------
+ * Internally everything is a flat `Float32Array` of `[r,g,b,a, …]` in 0..1 —
+ * one allocation for N points, GPU-upload shaped. napari-js 0.12.0's
+ * `PointsLayer.faceColor` takes `RGBA[]` (an array of 4-tuples) instead, so
+ * {@link toRgbaTuples} adapts at the boundary; when the layer accepts a typed
+ * array the adapter goes away and the flat buffer is passed straight through.
+ */
+/** napari-js per-point colour tuple: r, g, b, a in 0..1. */
+export type RGBA = [number, number, number, number];
+/** Neutral grey for observations with no value (NaN, or {@link NO_CATEGORY}). */
+export declare const MISSING_COLOR: Rgb;
+/** Default alpha for muted (background / unselected) points — CosMx-style context. */
+export declare const DEFAULT_MUTED_OPACITY = 0.15;
+/**
+ * Largest number of CATEGORIES whose colours survive the 3D points layer's LUT
+ * intact.
+ *
+ * That layer has no per-point RGBA — it maps a per-point SCALAR through a
+ * 256-entry colormap LUT — so a categorical palette is encoded as one contiguous
+ * block of LUT entries per value. Measured against napari-js, every K in 2..96
+ * blocks round-trips exactly and K=97 is the first that does not: 256 texels
+ * cannot keep more values apart than that.
+ *
+ * One of those 96 blocks is spent on {@link NO_CATEGORY}, which every column can
+ * contain, so what fits is **95 categories** — the number published here. It was
+ * 96 while the encoder rejected at 96, which meant a 96-category column drew flat
+ * with the panel showing no warning: the one failure this ceiling exists to
+ * prevent, arrived at from the other direction.
+ *
+ * Above it the cloud draws FLAT rather than draw a lie, because subtly wrong
+ * category colours under a confident legend is the failure nobody catches.
+ *
+ * A limit of that one layer, and of nothing else: the 2D markers carry per-point
+ * RGBA, and a density volume is a scalar field per cluster. Shared here so the
+ * renderer that enforces it and the panel that explains it cannot drift apart.
+ */
+export declare const SPATIAL_3D_MAX_CATEGORIES = 95;
+/** LUT blocks the 3D layer can keep apart — {@link SPATIAL_3D_MAX_CATEGORIES}
+ *  plus the one reserved for a missing value. */
+export declare const SPATIAL_3D_LUT_BLOCKS: number;
+/**
+ * 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.
+ */
+export declare const DEFAULT_CATEGORICAL_PALETTE: string[];
+interface MuteOptions {
+    /** Alpha for points that are not muted. Default 1. */
+    opacity?: number;
+    /** Alpha for muted points. Default {@link DEFAULT_MUTED_OPACITY}. */
+    mutedOpacity?: number;
+    /** `1` at index i mutes observation i. Absent ⇒ nothing is muted. */
+    muted?: Uint8Array | null;
+}
+export interface CategoricalEncodingOptions extends MuteOptions {
+    /** Per-category `#rrggbb`, index-aligned with the column's categories. */
+    colors: string[];
+    /** Colour for {@link NO_CATEGORY}. Default {@link MISSING_COLOR}. */
+    missingColor?: Rgb;
+}
+export interface ContinuousEncodingOptions extends MuteOptions {
+    /** 256-entry RGB table from {@link buildColormapLut}. */
+    lut: Rgb[];
+    /** Contrast window in VALUE units (pre-log). */
+    min: number;
+    max: number;
+    /** Apply `log1p` to the value and the window before normalising. */
+    log?: boolean;
+    /** Colour for `NaN`. Default {@link MISSING_COLOR}. */
+    missingColor?: Rgb;
+}
+/** Parse `#rgb` / `#rrggbb` to 0–255 RGB; unparseable input falls back to grey.
+ *  Exported so the 3D LUT path parses palettes exactly as the 2D path does. */
+export declare function parseHex(hex: string): Rgb;
+/**
+ * Per-category colours: the column's authored `colors` where present (so the
+ * viewer matches the figures the same analysis produced elsewhere), otherwise
+ * the palette by position, wrapping through a name-hash past its end so a
+ * 40-cluster column still gets stable, distinct-ish colours.
+ */
+export declare function resolveCategoryColors(meta: CategoricalColumnMeta, palette?: string[]): 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. */
+export declare function encodeContinuous(values: Float32Array, opts: ContinuousEncodingOptions): Float32Array;
+/**
+ * Contrast window from percentiles of the finite values — the CosMx
+ * "cap outliers at percentiles to improve contrast" rule. `lo`/`hi` are
+ * fractions (0.01 / 0.99 clips the extreme 1% at each end).
+ *
+ * Returns `[0, 1]` for an empty or all-missing vector so callers always get a
+ * usable window.
+ */
+export declare function contrastWindow(values: Float32Array, lo?: number, hi?: number): [number, number];
+/**
+ * Marker sizes for the points layer. napari-js `PointsLayer.size` is a
+ * **diameter** in data units while `SpatialObservations.radius` is a radius —
+ * the doubling lives here so no call site has to remember it.
+ *
+ * `fallbackRadius` covers a dataset that declares no radius (segmented cells
+ * often don't); it is in image pixels, like everything else in this space.
+ */
+export declare function markerDiameters(observations: SpatialObservations, fallbackRadius?: number): number | Float32Array;
+/**
+ * Adapt a flat RGBA buffer to the `RGBA[]` shape napari-js 0.12.0's
+ * `PointsLayer.faceColor` accepts. One 4-element array per point — the reason
+ * this is a named boundary rather than inlined: it is the one place the model
+ * stops being typed-array shaped, and it is what a future napari-js taking a
+ * `Float32Array` would delete.
+ */
+export declare function toRgbaTuples(flat: Float32Array): RGBA[];
+/** Convenience: a 256-entry LUT for a colormap value, falling back to Viridis. */
+export declare function lutFor(colormapValue: unknown, reverse?: boolean): Rgb[];
+/** True when every entry of a LUT is a neutral grey. Tested on the VALUES rather
+ *  than the colormap's name, so a reversed or renamed grey ramp still counts. */
+export declare function isGrayscaleLut(lut: readonly Rgb[]): boolean;
+/**
+ * LUT for a spatial CONTINUOUS encoding — a gene, a numeric column.
+ *
+ * `override` is the caller's explicit choice and wins outright, grey included: a
+ * grey ramp picked FOR the data is a decision, not the image's colormap leaking
+ * in.
+ *
+ * Without one, the display colormap — unless that colormap is grayscale. The
+ * tissue underneath is grayscale, so a grey overlay of a measurement is
+ * indistinguishable from the anatomy it is drawn over, and the reader cannot tell
+ * which channel a bright pixel belongs to. Viridis is then the fallback, which is
+ * what the CosMx guidance prescribes for continuous values anyway.
+ *
+ * Shared by the markers, both gene maps and the panel's colour bar, so none of
+ * 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[];
+export {};

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

@@ -0,0 +1,144 @@
+import { SpatialImageRef, SpatialObservations } from '../contracts/spatial-dataset.contract';
+import { DensityGrid } from './spatial-density';
+/**
+ * Turning per-cell expression into a **gene map** — a continuous field over the
+ * tissue, drawn under the cells rather than instead of them.
+ *
+ * A scatter coloured by a gene answers "which cells express it"; it does not answer
+ * "where is it expressed", because the eye cannot integrate thousands of small dots
+ * into a territory. A field can be estimated between the cells and read as a
+ * region, which is what the CosMx guidance and Spatial-Live's heat layer both do.
+ *
+ * The quantity is the kernel-weighted **MEAN per cell**, not a sum:
+ *
+ * ```
+ *   mean(p) = Σᵢ w(p, xᵢ)·eᵢ  /  Σᵢ w(p, xᵢ)
+ * ```
+ *
+ * A sum would conflate "many cells here" with "high expression here" — a dense
+ * region would glow whatever its cells were doing, which is the single easiest way
+ * to read a gene map wrongly. The denominator is also what makes emptiness
+ * expressible: where no cell was measured the mean is *undefined*, not zero, so the
+ * caller gets a `support` channel and can draw nothing there instead of drawing the
+ * colormap's low end over unmeasured tissue.
+ *
+ * Pure — no Angular, no GPU, no colour — like `spatial-density.ts`, and tested the
+ * same way.
+ */
+export interface ExpressionFieldOptions {
+    /** Data→image affine, so the field lands in the displayed image's pixels. */
+    ref?: SpatialImageRef;
+    /** Raster size in field pixels. */
+    width: number;
+    height: number;
+    /** Image pixels per field pixel — the field is coarser than the slide it covers. */
+    step: number;
+    /** Kernel σ in FIELD pixels. */
+    sigma: number;
+    /** One expression value per observation. */
+    values: Float32Array;
+    /** Observations to include; every one when absent (a plane, a selection). */
+    indices?: Uint32Array;
+}
+export interface ExpressionField {
+    width: number;
+    height: number;
+    /** Kernel-weighted mean expression, valid only where `support > 0`. */
+    mean: Float32Array;
+    /** Kernel-weighted cell count per field pixel — 0 where nothing was measured. */
+    support: Float32Array;
+    /** Median positive support: the scale at which a pixel is "properly sampled",
+     *  and a data-driven saturation point for an opacity ramp. */
+    supportScale: number;
+    /** Finite range of `mean` over the supported pixels, for a contrast window. */
+    range: [number, number];
+}
+/**
+ * Estimate a gene's expression field over the image the observations sit in.
+ *
+ * Null when nothing lands on the raster — the caller then draws no layer, rather
+ * than an empty one the reader has to interpret.
+ */
+export declare function expressionField(obs: SpatialObservations, opts: ExpressionFieldOptions): ExpressionField | null;
+/**
+ * Colour a field into RGBA8 for a `channels: 4` image source.
+ *
+ * Alpha comes from the SUPPORT, ramped to the field's own median support rather
+ * than a constant: a pixel backed by one distant cell is faint, a properly sampled
+ * one is solid, and unmeasured tissue is fully transparent — so the map never
+ * asserts a measurement where there was none. `opacity` scales the whole layer on
+ * top of that.
+ */
+export declare function colorExpressionField(field: ExpressionField, lut: readonly (readonly [number, number, number])[], window: [number, number], opts?: {
+    log?: boolean;
+    opacity?: number;
+}): Uint8Array;
+/**
+ * The same estimator in 3D: a gene's expression over a serially sectioned
+ * specimen, on a {@link DensityGrid} lattice.
+ *
+ * Two modes, and the difference between them is the difference between a
+ * measurement and an estimate:
+ *
+ *  - **sheets** (`interpolate` unset) blurs in-plane only, so exactly the z planes
+ *    that hold cells are filled and the gaps between sections stay empty. This is
+ *    the measured sections, stacked — the 2D gene map of each slide, at its own z.
+ *  - **volume** (`interpolate` set) also smooths along z, so the planes between
+ *    the sections carry an interpolated value. Smoothing the numerator and the
+ *    denominator together is what makes that honest: it is Nadaraya-Watson, so an
+ *    unimaged plane inherits its neighbours' MEAN rather than their sum thinned
+ *    over a gap nobody sampled. Outside the sampled range the field is zeroed —
+ *    "smoothed between the imaged sections" must not put expression in front of
+ *    the first section or behind the last.
+ *
+ * Individual cells are still never interpolated: consecutive sections sample
+ * different cells, so there is nothing to interpolate along. What is interpolated
+ * is a field, which is legitimately defined between the planes.
+ */
+export interface ExpressionVolumeOptions {
+    /** Kernel σ per axis, in the observations' own units. The z term is used only
+     *  when {@link interpolate} is set. */
+    sigma: [number, number, number];
+    /** One expression value per observation. */
+    values: Float32Array;
+    /** Observations to include; every one when absent — one section, or a selection. */
+    indices?: Uint32Array;
+    /** Smooth along z into a continuous estimate rather than leaving the measured
+     *  sheets isolated at their own planes. */
+    interpolate?: boolean;
+}
+export interface ExpressionVolumeField {
+    width: number;
+    height: number;
+    depth: number;
+    /** Kernel-weighted mean expression, valid only where `support > 0`. */
+    mean: Float32Array;
+    /** Kernel-weighted cell count per voxel — 0 where nothing was measured. */
+    support: Float32Array;
+    /** Finite range of `mean` over the supported voxels, for a contrast window. */
+    range: [number, number];
+}
+export declare function expressionVolume(obs: SpatialObservations, grid: DensityGrid, opts: ExpressionVolumeOptions): ExpressionVolumeField | null;
+/**
+ * Encode a field into the uint8 scalar a `VolumeLayer` renders, windowed the same
+ * way the 2D map and the markers are so the three cannot disagree.
+ *
+ * `floor` lifts every MEASURED voxel to at least this fraction of full scale, so
+ * that "the gene is not here" can be told from "nobody sectioned here" — the
+ * distinction the 2D map keeps with its separate support channel, which a scalar
+ * volume cannot express because its raymarch takes alpha from the same number it
+ * takes colour from.
+ *
+ * It defaults to OFF, because in a volume that trade does not pay. A ray crosses
+ * tens of measured planes and the DVR composites every one of them, so a floor
+ * large enough to see on a single plane saturates to an opaque shell over the
+ * whole specimen and buries the signal it was meant to contextualise, while one
+ * small enough to stay faint is already invisible per plane. The measured envelope
+ * is better read from the anatomy layer and the observations, which are drawn in
+ * the same scene — and the surrounding density volumes take the same no-floor
+ * approach, so the scene stays internally consistent.
+ */
+export declare function encodeExpressionVolume(field: ExpressionVolumeField, window: [number, number], opts?: {
+    log?: boolean;
+    floor?: number;
+}): Uint8Array;

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

@@ -0,0 +1,37 @@
+/**
+ * Framing a 2D scatter on its own coordinates.
+ *
+ * The 2D spatial camera is normally fitted to the IMAGE, because the observations are recorded in
+ * that image's pixel space — frame the image and they come with it. A dataset with no reference
+ * image has coordinates in whatever units its source used: seqFISH's span about 5 x 7. Left with
+ * the previous image's framing, such a dataset lands as a handful of pixels far off-centre, which
+ * looks exactly like nothing having loaded rather than like a framing problem.
+ *
+ * Pure, like `spatial-density.ts` and the rest of this directory — the renderer applies the result.
+ */
+/** Fraction of the viewport the coordinates are fitted into, so the outermost markers are not
+ *  flush against the edge. Matches napari-js's own fit margin. */
+export declare const SPATIAL_FIT_MARGIN = 0.95;
+export interface SpatialFraming {
+    /** World point to put at the centre of the viewport. */
+    center: [number, number];
+    /** World units per pixel, inverted — the camera's `zoom`. */
+    zoom: number;
+}
+/**
+ * Camera centre and zoom that fit `positions` into a `viewportW` x `viewportH` box.
+ *
+ * `positions` is interleaved `[x0, y0, x1, y1, …]`, the layout the points layer takes.
+ *
+ * Null when there is nothing to fit — no points, a viewport with no area, or coordinates that are
+ * entirely non-finite. Null means LEAVE THE CAMERA ALONE: a caller that substituted a default
+ * would move the view for a dataset it cannot frame, which is worse than not moving it.
+ *
+ * A degenerate extent — one point, or every point on a line — yields a centre but no zoom, since
+ * there is no span to divide by. The caller keeps its current zoom and just recentres, rather than
+ * dividing by zero into an infinite one.
+ */
+export declare function framePositions(positions: Float32Array, viewportW: number, viewportH: number, margin?: number): SpatialFraming | {
+    center: [number, number];
+    zoom: null;
+} | null;

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

@@ -0,0 +1,111 @@
+/**
+ * Mean expression per group, for the gene × class heatmap.
+ *
+ * A scatter coloured by one gene answers "where is this gene". It cannot answer
+ * "which classes express which genes", which is the question a marker panel is
+ * actually read for — and the standard object for that is the mean-expression
+ * matrix per cluster (scanpy's `matrixplot`/`dotplot`), genes against classes.
+ *
+ * Deliberately NOT cells × genes at the full dataset: 374k columns is not a
+ * heatmap. Cells become columns only inside a selection, where a few thousand
+ * of them render and the question changes to "what is in this region".
+ *
+ * Two things this has to get right to be readable:
+ *
+ *  - A cell with no measurement for a gene (`NaN`) is SKIPPED, not counted as
+ *    zero. Counting it would drag a group's mean towards absence for a reason
+ *    that has nothing to do with the biology.
+ *  - Z-scoring is per GENE, across groups. Without it a gene expressed an order
+ *    of magnitude above the others saturates the colour scale and the rest of
+ *    the panel reads as uniformly blank — the matrix would show which gene is
+ *    loudest rather than which class expresses what.
+ *
+ * Pure — no Angular, no Plotly, no renderer — like `spatial-density.ts`, and
+ * tested the same way.
+ */
+/** One gene's values, with the name to label its row. */
+export interface HeatmapGene {
+    name: string;
+    /** One value per observation; `NaN` where the gene was not measured. */
+    values: Float32Array;
+}
+/** The columns to aggregate into: a categorical column's categories. */
+export interface HeatmapGroups {
+    /** Per-observation category index, or {@link NO_CATEGORY}. */
+    codes: Uint16Array;
+    categories: readonly string[];
+}
+export interface HeatmapMatrixOptions {
+    /** Observations to include; every one when absent (an ROI selection). */
+    indices?: Uint32Array;
+    /**
+     * Z-score each gene across the groups, so one loud gene cannot flatten the
+     * panel. On by default — the raw means are only readable when every gene is
+     * on a comparable scale.
+     */
+    zScore?: boolean;
+    /** Drop groups with fewer than this many measured cells. A mean over one or
+     *  two cells is noise presented with the same weight as a real one. */
+    minCells?: number;
+    /**
+     * Keep at most this many columns, chosen by the STRONGEST signal any picked
+     * gene shows in them.
+     *
+     * `subclass` has 338 categories. Drawn in full that is a texture rather than a
+     * panel — every column a couple of pixels wide, every label unreadable — and
+     * the question being asked ("which groups express my genes") is answered by
+     * the handful of groups where a gene actually stands out. Ranking by
+     * max |value| across the rows surfaces exactly those; ranking by cell count
+     * would instead surface the biggest groups, which is a different question.
+     *
+     * Unset keeps every column that cleared `minCells`.
+     */
+    maxCols?: number;
+}
+export interface HeatmapMatrix {
+    /** Gene names, one per row, in the order given. */
+    rows: string[];
+    /** Columns dropped by `maxCols`, so the caller can say how many are hidden
+     *  rather than silently showing a subset as if it were everything. */
+    hiddenCols: number;
+    /** Group labels, one per column — only the groups that survived `minCells`. */
+    cols: string[];
+    /**
+     * `rows.length × cols.length`, row-major: `values[r * cols.length + c]`.
+     * `NaN` where a group had nothing measured for that gene, which the caller
+     * draws as a gap rather than as a zero.
+     */
+    values: Float32Array;
+    /** Measured cells behind each column, index-aligned with {@link cols}. */
+    counts: Uint32Array;
+    /** Finite range of `values`, for a symmetric or absolute colour scale. */
+    range: [number, number];
+}
+/** Default floor for a group to earn a column. */
+export declare const HEATMAP_MIN_CELLS = 3;
+/**
+ * Mean expression of each gene in each group.
+ *
+ * Null when nothing survives — no genes, no groups, or every group filtered
+ * out — so the caller draws no chart rather than an empty grid.
+ */
+export declare function heatmapMatrix(genes: readonly HeatmapGene[], groups: HeatmapGroups, opts?: HeatmapMatrixOptions): HeatmapMatrix | null;
+/**
+ * Groups standing in for individual cells, for the in-selection view.
+ *
+ * Inside an ROI, "which classes express what" is often the wrong question and
+ * "what is in front of me" is the right one — so each cell becomes its own
+ * column. Capped: past a few hundred columns a heatmap is a texture, not a
+ * readable panel, and the cap is applied by even thinning so the selection is
+ * still represented across its whole extent rather than truncated to its first
+ * cells.
+ *
+ * NOTE: every column here holds exactly ONE cell, so the caller must pass
+ * `minCells: 1` to {@link heatmapMatrix}. The default floor of
+ * {@link HEATMAP_MIN_CELLS} exists to suppress noisy group means and would
+ * filter out every column of this view, returning null.
+ */
+export declare function cellsAsGroups(indices: Uint32Array, observationCount: number, max?: number): {
+    groups: HeatmapGroups;
+    indices: Uint32Array;
+};

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

@@ -0,0 +1,49 @@
+/**
+ * What is under the cursor, and what to say about it.
+ *
+ * A coloured cloud answers "how is this annotation distributed"; it cannot answer
+ * "which class is THAT" — the legend has 34 entries, several of them similar
+ * colours, and matching a dot to a swatch by eye is exactly the task a tooltip
+ * exists to remove.
+ *
+ * Pure — no DOM, no camera, no data access. The renderer supplies screen
+ * positions (it owns the projection) and the active colour source; everything
+ * here is arithmetic and string formatting, so it is tested directly.
+ */
+/** The colour source a tooltip describes, as the renderer already has it. */
+export type HoverSource = {
+    kind: 'categorical';
+    /** Column name, for the tooltip's first line. */
+    name: string;
+    categories: readonly string[];
+    /** Per-observation category index, or `NO_CATEGORY`. */
+    codes: Uint16Array;
+} | {
+    kind: 'continuous';
+    /** Column or gene name. */
+    name: string;
+    values: Float32Array;
+    /** Unit for the value, when the dataset declares one. */
+    unit?: string;
+};
+/**
+ * Index of the drawn observation nearest `(x, y)` within `maxDist` screen pixels,
+ * or -1.
+ *
+ * `screen` is `[x0, y0, x1, y1, …]` indexed BY OBSERVATION, with NaN for anything
+ * not currently drawn — off screen, behind the eye, or on a hidden section. NaN
+ * fails every comparison, so those are skipped without a special case.
+ *
+ * Ties go to the LATER observation, which is the one drawn on top and therefore
+ * the one the user believes they are pointing at.
+ */
+export declare function nearestObservation(screen: Float32Array, x: number, y: number, maxDist: number): number;
+/**
+ * The tooltip's lines for one observation: what it is, then which column said so.
+ *
+ * Null when the source cannot describe this observation — a code outside the
+ * category list, or a value that was never measured. Saying nothing is better
+ * than a tooltip that reads "undefined", and better than inventing a label for a
+ * cell whose annotation is genuinely missing.
+ */
+export declare function hoverText(source: HoverSource | null, index: number): string[] | null;

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

@@ -0,0 +1,59 @@
+import { SpatialObservations } from '../contracts/spatial-dataset.contract';
+/**
+ * The planes a **serially sectioned** dataset was actually imaged at.
+ *
+ * A 3D spatial-omics dataset of this kind is not a cloud that happens to have a z:
+ * it is a stack of thin sections, hundreds of microns apart, each one a separate
+ * slide. Every observation on a given slide shares that slide's registered z
+ * exactly, so the distinct z values ARE the sections — no binning, no tolerance,
+ * and no need for a dataset-specific section-label column.
+ *
+ * That matters for the 3D view, where the cloud reads as a stack of discs and the
+ * discs hide the density volumes drawn between them. Being able to show one
+ * section's cells against the estimated field is how you check the estimate against
+ * the measurement; being able to hide them is how you see the field at all.
+ *
+ * Deliberately NOT a binning of a continuous z (that is
+ * `observationsInSlice`'s job, against a volume's voxel planes). If the z is
+ * continuous rather than sectioned there are no sections to offer, and
+ * {@link sampledSections} says so by returning null rather than inventing some.
+ *
+ * Pure — no Angular, no GPU — like `spatial-density.ts`, and tested the same way.
+ */
+/**
+ * Distinct z values beyond which the data is treated as continuous rather than
+ * sectioned. Serial sectioning runs to tens or low hundreds of slides (53 for the
+ * ABC whole-brain MERFISH atlas); a z that keeps producing new values is a
+ * measurement axis, and a "pick one section" control over it would be a lie.
+ */
+export declare const MAX_SAMPLED_SECTIONS = 512;
+/**
+ * The dataset's sampled section positions, ascending — or null when it has no z,
+ * no observations, or a z too finely divided to be sections at all.
+ *
+ * Bails out as soon as the distinct count passes `max`, so a continuous z costs one
+ * partial pass rather than a set with one entry per observation.
+ */
+export declare function sampledSections(obs: SpatialObservations, max?: number): Float32Array | null;
+/**
+ * Indices of the observations lying on one sampled section.
+ *
+ * Exact equality on purpose: `z` comes from {@link sampledSections}, which read the
+ * values out of this same array, so the comparison cannot drift. Passing a z that
+ * is not one of the sampled positions yields nothing, which is the honest answer.
+ */
+export declare function observationsInSection(obs: SpatialObservations, z: number): Uint32Array;
+/**
+ * {@link sampledSections} for a dataset's observations, computed once.
+ *
+ * Both the renderer (which filters the cloud's geometry to one section) and the
+ * control panel (which offers the sections to pick from) need this list, and the
+ * scan reads the z of up to 3.7M observations — so it is memoized on the
+ * observations object itself rather than each caller keeping its own copy keyed by
+ * a dataset id it has to remember to invalidate. Still referentially transparent:
+ * the same observations always give the same sections.
+ *
+ * Default `max` only; a caller wanting a different cap should call
+ * {@link sampledSections} directly and cache it itself.
+ */
+export declare function sectionsOf(obs: SpatialObservations): Float32Array | null;