@jax-data-science/sci-image-visualizer 0.8.3 → 0.10.0

package/lib/section-pane/section-pane.component.d.ts

@@ -0,0 +1,47 @@
+import { AfterViewInit, EventEmitter, NgZone, OnChanges, OnDestroy } from '@angular/core';
+import type { SectionAxis, SectionView } from '../contracts/section-view.contract';
+import * as i0 from "@angular/core";
+export declare class SectionPaneComponent implements AfterViewInit, OnChanges, OnDestroy {
+    private readonly zone;
+    axis: SectionAxis;
+    view: SectionView | null;
+    /** A point clicked, in section coordinates (u across, v down). */
+    readonly pick: EventEmitter<{
+        u: number;
+        v: number;
+    }>;
+    private canvasRef;
+    private zoom;
+    private pan;
+    private press;
+    private image;
+    private resize?;
+    private frame;
+    constructor(zone: NgZone);
+    protected get axisColor(): string;
+    protected get label(): string;
+    ngAfterViewInit(): void;
+    ngOnChanges(): void;
+    ngOnDestroy(): void;
+    /** Back to the whole section, centred. */
+    fit(): void;
+    protected onWheel(e: WheelEvent): void;
+    protected onDown(e: PointerEvent): void;
+    protected onMove(e: PointerEvent): void;
+    protected onUp(e: PointerEvent): void;
+    private local;
+    /** Section units → CSS px in the pane: scale per unit across and down, and the origin. */
+    private transform;
+    private toSection;
+    /** Redraw on the next frame (outside Angular: a canvas paint needs no change detection). */
+    private draw;
+    private paint;
+    /** Each class's cut: its outlines filled and stroked, its lines drawn (a dot for one point). */
+    private paintRegions;
+    /** The other planes: across (u) and down (v), dashed in their axis colours. */
+    private paintCrosshair;
+    /** The section's image on a canvas of its own size (made again only for a new image). */
+    private imageCanvas;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SectionPaneComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SectionPaneComponent, "viz-section-pane", never, { "axis": { "alias": "axis"; "required": true; }; "view": { "alias": "view"; "required": false; }; }, { "pick": "pick"; }, never, never, true, never>;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * The transcript-density raster's window. Its default colour scale is matplotlib's
+ * inferno (`INFERNO_LUT` from napari-js/colormaps), as in Xenium Explorer.
+ */
+/** A density window from the non-empty bins: 1st to 99th percentile. */
+export declare function densityAutoRange(values: ArrayLike<number>): [number, number];

package/lib/spatial/embedding-compute-coordinator.d.ts

@@ -0,0 +1,123 @@
+import { BehaviorSubject } from 'rxjs';
+import type { SpatialEmbedding, SpatialEmbeddingMeta } from '../contracts/spatial-dataset.contract';
+/** Where a browser-side embedding computation stands, for the progress bar and messages. */
+export interface EmbeddingComputeState {
+    /** True while a run is going. */
+    running: boolean;
+    /** 0..1 while running, or null before the first report. */
+    fraction: number | null;
+    /** Which backend the worker got — 'webgpu', 'wasm' or 'cpu'. */
+    backend: string | null;
+    message: string | null;
+    error: string | null;
+}
+/** Where the PCA scores come from: a port that serves embeddings by name. */
+export type EmbeddingSource = (name: string) => Promise<SpatialEmbedding>;
+/**
+ * Largest dataset a t-SNE is offered for in the browser.
+ *
+ * t-SNE is O(N²) per iteration — vectorised on the GPU, but not approximated — so the cost
+ * is quadratic in observations. Measured end to end in Firefox on WebGPU: 2,688 points took
+ * 95 s. That scales to roughly five and a half minutes at this threshold, and to about 76
+ * minutes at seqFISH's 19,416, which was also measured offline.
+ *
+ * Past this the option is WITHDRAWN rather than offered with a warning. An hour-long job
+ * started from a button is not a choice a reader can meaningfully consent to in a dialog,
+ * and a t-SNE that large belongs in the offline pipeline, where it can run once and be
+ * served to everyone.
+ */
+export declare const BROWSER_TSNE_MAX_OBSERVATIONS = 5000;
+/**
+ * A t-SNE the dataset does not publish, offered so it can be computed here.
+ *
+ * A dropped-in `.h5ad` typically carries one UMAP and a PCA, and no t-SNE — the two views
+ * answer different questions, so having only one is a real gap. Computing it needs no
+ * expression data: t-SNE runs on the PCA scores, which is why this can happen in the
+ * browser at all while PCA cannot.
+ */
+export declare const COMPUTABLE_EMBEDDINGS: readonly SpatialEmbeddingMeta[];
+/** Roughly how long a t-SNE of `n` observations takes, in seconds, from the measured anchor. */
+export declare function tsneEstimateSeconds(n: number): number;
+/** A duration as something to put on a button: `~42s`, `~6 min`. */
+export declare function estimateLabel(seconds: number): string;
+/**
+ * The browser-side embedding computation behind the charts' Embedding tab: which
+ * embeddings to offer for a dataset, the t-SNE run itself (PCA scores from the port, then a
+ * worker), its progress, and the results computed this session.
+ *
+ * A run is several awaits long — the PCA scores arrive over HTTP, then the worker takes a
+ * minute or more — and the dataset can change at any of them, including before the run
+ * exists to be terminated. Every await is checked against a {@link Supersede} that a
+ * dataset switch ({@link setDataset}) or teardown ({@link abandon}) cancels, so the scores
+ * fetched for one dataset are never embedded and drawn over another's observations.
+ *
+ * Plain class: the owner renders {@link state} (or {@link state$}).
+ */
+export declare class EmbeddingComputeCoordinator {
+    readonly state$: BehaviorSubject<EmbeddingComputeState>;
+    /** True when a t-SNE is missing but the dataset is too big to embed here. */
+    tooLarge: boolean;
+    /** Observations in the live dataset, kept for the cost estimate. */
+    observationCount: number;
+    /** Coordinates computed in this browser, by name. Not persisted: a reload recomputes. */
+    private readonly computed;
+    /** The live run, when one is going. */
+    private run;
+    private readonly load;
+    get state(): EmbeddingComputeState;
+    get running(): boolean;
+    /**
+     * A new dataset: drop everything computed or computing for the previous one, and return
+     * the embeddings to offer — the published ones, plus a t-SNE to compute where the dataset
+     * has a PCA to embed, no t-SNE of its own, and is small enough. Otherwise the menu would
+     * advertise work that cannot start, or duplicate what is already served.
+     */
+    setDataset(published: readonly SpatialEmbeddingMeta[], observationCount: number): SpatialEmbeddingMeta[];
+    /** Whether `meta` is one this browser would have to compute. */
+    isComputable(meta: SpatialEmbeddingMeta | null): boolean;
+    /** Whether `meta` has already been computed this session. */
+    isComputed(meta: SpatialEmbeddingMeta | null): boolean;
+    /** The coordinates computed for `name`, if any. */
+    result(name: string): SpatialEmbedding | undefined;
+    /** Roughly how long a run would take here, in seconds. Shown before the click: a progress
+     *  bar tells you a job is going; only an estimate tells you whether to start it. */
+    get estimateSeconds(): number;
+    /** {@link estimateSeconds} as something to put on a button. */
+    get estimateLabel(): string;
+    /** Why the option is absent, when a dataset is past the threshold. */
+    get tooLargeNote(): string;
+    /**
+     * Compute `meta` here, in a worker, from the dataset's PCA among `embeddings`.
+     *
+     * The PCA scores come from the port as an ordinary embedding — the server derives them,
+     * because PCA needs the whole expression matrix (185 MB for a Visium dataset) while
+     * t-SNE needs only the scores (0.51 MB). Sending the matrix to the browser to save a few
+     * seconds of arithmetic would be a far slower answer.
+     *
+     * @returns the coordinates, to draw — or null when there is nothing to draw: cancelled,
+     *   abandoned, failed (see {@link state}), or already running.
+     */
+    start(meta: SpatialEmbeddingMeta, embeddings: readonly SpatialEmbeddingMeta[], getEmbedding: EmbeddingSource): Promise<SpatialEmbedding | null>;
+    /** The user's Cancel: ask the worker to stop. The run settles shortly after, with nothing. */
+    cancel(): void;
+    /**
+     * Drop any computation in progress, because what it is computing no longer applies.
+     *
+     * Distinct from {@link cancel}: this does not wait — the run is settled and the worker
+     * killed, so a dataset switch or a teardown cannot leave a t-SNE grinding on in the
+     * background over observations nothing is showing any more.
+     */
+    abandon(): void;
+    private patch;
+}
+/**
+ * The dataset's PCA, as row-major scores.
+ *
+ * Assembled from whichever PCA the source offers, widest first — a 3-D one gives t-SNE
+ * three components instead of two for the same request.
+ */
+export declare function loadPcaScores(embeddings: readonly SpatialEmbeddingMeta[], getEmbedding: EmbeddingSource): Promise<{
+    scores: Float32Array;
+    nObs: number;
+    nDims: number;
+} | null>;

package/lib/spatial/embedding-compute.d.ts

@@ -18,6 +18,7 @@ export interface ComputeProgress {
     backend: string | null;
     message: string | null;
 }
+/** One t-SNE to compute: the PCA scores to embed and the run's parameters. */
 export interface ComputeRequest {
     /** PCA scores, row-major `nObs x nDims`. */
     scores: Float32Array;
@@ -28,12 +29,30 @@ export interface ComputeRequest {
     iterations?: number;
     seed?: number;
 }
-/** Factory, so a test can supply a worker without a bundler. */
-export type WorkerFactory = () => Worker;
+/**
+ * Factory, so a test can supply a worker without a bundler. May be asynchronous, as the
+ * default one is: it imports the worker module on demand.
+ */
+export type WorkerFactory = () => Worker | Promise<Worker>;
+/**
+ * One t-SNE run in its own worker: start it, follow its progress, cancel it. Single use —
+ * a new computation takes a new run.
+ */
 export declare class EmbeddingComputeRun {
     private readonly factory?;
     private worker;
     private settled;
+    /**
+     * Between `run()` being called and the worker existing.
+     *
+     * The default factory imports the worker module first, and a dataset switch or a
+     * teardown can call {@link terminate} in that window. With no worker yet there is
+     * nothing to kill, so terminating bumps {@link generation} instead and the run stops
+     * itself the moment the worker arrives, before posting it any work.
+     */
+    private starting;
+    /** Bumped by {@link terminate}; a run that finds it changed across its await gives up. */
+    private generation;
     /**
      * Settles a run that is still waiting, set for as long as one is.
      *

package/lib/spatial/glyphs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Transcript "icon" mode: the marker shapes, and their outlines for the panel's previews.
+ * The napari view draws them as napari-js point symbols (`GLYPH_SYMBOLS` in
+ * `spatial-tiles/transcript-layers.ts`), with these outlines' proportions.
+ */
+/** Marker shapes for the transcript "icon" mode. */
+export declare const TRANSCRIPT_GLYPHS: readonly ["circle", "star", "triangle", "square", "diamond", "cross", "hexagon", "triangle-down", "pentagon", "x"];
+/** One of the marker shapes in {@link TRANSCRIPT_GLYPHS}. */
+export type TranscriptGlyph = (typeof TRANSCRIPT_GLYPHS)[number];
+/**
+ * Unit outline of a glyph, radius ≈ 1, centred on the origin, as `[x0, y0, x1, y1, …]` — the
+ * panel's preview of the point symbol the canvas draws.
+ */
+export declare function glyphOutline(glyph: TranscriptGlyph): Float32Array;
+/** The glyph a gene gets by default: by its position in the selected list. */
+export declare function defaultGlyphFor(slot: number): TranscriptGlyph;

package/lib/spatial/lod.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Level-of-detail planning for tiled spatial geometry — cell outlines and transcripts.
+ *
+ * The renderer knows its camera (a world-space centre, a zoom in canvas pixels per world
+ * unit, a canvas size); a tiled dataset knows its grids (one per level, in observation
+ * units). This module is the bridge: which level the zoom calls for and which tiles are on
+ * screen. Everything here is pure, so the policy — the part that decides whether the view
+ * is fast and legible — is testable without a GPU.
+ *
+ * Observation units map onto world units through the dataset's `imageRef` affine
+ * (`world = data · scale + translate`), so "pixels per observation unit" is
+ * `zoom · scale`. For a Xenium bundle the data unit is the micron and the world unit the
+ * morphology pixel.
+ */
+import type { SpatialBounds, SpatialDataset, SpatialImageRef, SpatialTileLevel } from '../contracts/spatial-dataset.contract';
+import type { SpatialViewState } from '../contracts/display-types';
+/** A rectangle in observation coordinates. */
+export interface DataRect {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** Tile address. */
+export interface TileKey {
+    level: number;
+    gx: number;
+    gy: number;
+}
+/** Whether cell outlines are drawn: the user's choice, else on when the dataset has any. */
+export declare function cellsShown(dataset: Pick<SpatialDataset, 'polygonTiles' | 'polygons'> | null, view: Pick<SpatialViewState, 'showCells'>): boolean;
+/** A column holding a hand-curated cell-type annotation, by naming convention. */
+export declare function isCuratedColumn(name: string): boolean;
+/**
+ * The categorical column that names each cell's type: the view's choice when it is a
+ * column of this dataset, else the first categorical column that is not a curated
+ * annotation (a pipeline's clustering is the default; curation is opted into), else
+ * any categorical column.
+ */
+export declare function cellTypeColumnFor(dataset: SpatialDataset, view: Pick<SpatialViewState, 'cellTypeColumn'>): string | null;
+/** A stable string id for a tile key, `level/gx/gy` — usable as a Map key. */
+export declare function tileId(k: TileKey): string;
+/** Canvas pixels per observation unit along x, for a camera zoom and a data→world affine. */
+export declare function pixelsPerDataUnit(zoom: number, ref?: SpatialImageRef | null): number;
+/**
+ * The part of observation space the camera shows, padded by `margin` (a fraction of the
+ * viewport) so tiles just off screen are already there when a pan brings them in: napari-js's
+ * `worldViewport`, mapped back through the inverse of the data→world affine.
+ */
+export declare function visibleDataRect(center: readonly [number, number], zoom: number, canvasW: number, canvasH: number, ref?: SpatialImageRef | null, margin?: number): DataRect | null;
+/**
+ * Tiles of one level intersecting `rect`, clipped to the dataset's `bounds` (so zooming
+ * out over empty canvas does not ask for tiles that cannot exist). Ordered from the
+ * rectangle's centre outward, so the middle of the screen fills in first.
+ *
+ * Tile `g` covers `[g·s, (g+1)·s)`. The view's far edge is open — a tile starting exactly
+ * at `rect.x1` shows nothing — but the bounds' far edge is closed: the bounds are the
+ * extreme observations' coordinates, so one sits exactly on `bounds[2]`, in the tile
+ * starting there.
+ */
+export declare function tilesInRect(rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
+/** {@link tilesInRect} for a grid whose tile (0, 0) starts at `origin`. */
+export declare function tilesInRectFrom(origin: readonly [number, number], rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
+/** Area of `rect` inside `bounds` (the whole rect when there are none). */
+export declare function visibleArea(rect: DataRect, bounds?: SpatialBounds | null): number;
+/**
+ * Typical cell diameter, in observation units, used to judge how large cells appear.
+ * Derived from the per-observation radius when there is one; 12 µm otherwise.
+ */
+export declare function typicalCellDiameter(radius: Float32Array | number | undefined, fallback?: number): number;
+/**
+ * On-screen cell diameter (px) at or above which each polygon level is used. A level
+ * halves the vertices of the one below, so each should take over when the cell is about
+ * half as large on screen. Below the last finite threshold outlines are not drawn at
+ * all — a cell a few pixels wide is a dot, and the observation markers already draw it
+ * as one.
+ *
+ * Xenium's fourth level (3 vertices per cell) is deliberately never used: seen on
+ * screen it is a field of triangles, which reads as an artefact rather than as cells.
+ * The dots below 8 px say the same thing more honestly.
+ */
+export declare const POLYGON_LEVEL_MIN_CELL_PX: number[];
+/**
+ * Which polygon level suits this zoom, or -1 for "too small to outline".
+ * `detail` > 1 prefers finer levels (sharper, slower); < 1 coarser.
+ */
+export declare function polygonLevelFor(pxPerUnit: number, cellDiameter: number, levelCount: number, detail?: number): number;
+/**
+ * Which transcript level suits this zoom: the one whose tiles come out closest to
+ * `targetTilePx` on screen. Coarser levels aggregate more, so this keeps the number of
+ * markers per screen roughly constant however far out the camera is — the property that
+ * keeps the view fast.
+ */
+export declare function transcriptLevelFor(pxPerUnit: number, levels: readonly SpatialTileLevel[], targetTilePx?: number): number;

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

@@ -0,0 +1,64 @@
+import { Observable } from 'rxjs';
+import { PlotType } from '../contracts/plot-type';
+import { SpatialDataPort } from '../contracts/ports/spatial-data.port';
+import { SpatialObservations } from '../contracts/spatial-dataset.contract';
+import { ISpatialControls } from '../contracts/visualizer.contract';
+import { RegionStore } from '../store/region-store.service';
+import { SpatialSelectionStore } from '../store/spatial-selection.service';
+import { VisualizerStore } from '../store/visualizer-store.service';
+/** The renderer-side spatial readouts the controls surface (the napari-js backend). */
+export interface SpatialRendererFeeds {
+    readonly transcriptEstimate$: {
+        asObservable(): Observable<{
+            points: number;
+            max: number;
+        } | null>;
+    };
+    readonly geneCountsInView$: {
+        asObservable(): Observable<Record<string, number> | null>;
+    };
+    readonly densityStats$: {
+        asObservable(): Observable<{
+            lo: number;
+            hi: number;
+            max: number;
+        } | null>;
+    };
+    /** Observations projected to canvas pixels by the 3D camera, or null when the cloud is not mounted. */
+    getSpatialScreenProjection(obs: SpatialObservations): Float32Array | null;
+}
+/** What the facade works over: the shared stores, the renderer feeds and the router's view state. */
+export interface SpatialControlsContext {
+    readonly store: VisualizerStore;
+    readonly regionStore: RegionStore;
+    readonly selectionStore: SpatialSelectionStore;
+    readonly napari: SpatialRendererFeeds;
+    /** The plot type on screen (the 3D cloud selects in screen space). */
+    plotType(): PlotType;
+    /** The displayed slice (a volume-backed dataset selects within one section). */
+    zIndex(): number;
+}
+/**
+ * The spatial-omics controls (`ISpatialControls`) over a host's `SPATIAL_DATA_PORT`.
+ *
+ * Backend-neutral: the view state lives in the shared `VisualizerStore` (like the
+ * colormap) and the selection in the `SpatialSelectionStore`, so the controls keep
+ * working across a plot-type switch and a host can drive them before any backend has
+ * mounted. Owns its mirror of the port's dataset — dropping a stale selection and an
+ * unsatisfiable colour source when the dataset changes — and the subscription behind
+ * it, released by {@link dispose} (review CORE-30).
+ */
+export declare class SpatialControlsFacade {
+    private readonly port;
+    private readonly ctx;
+    /** The controls; one object for the facade's life, so consumers can hold it. */
+    readonly controls: ISpatialControls;
+    /** Latest dataset, mirrored so `selectFromRegions()` can answer synchronously — it
+     *  runs from a button click and must not await a round-trip. */
+    private dataset;
+    private readonly sub;
+    constructor(port: SpatialDataPort, ctx: SpatialControlsContext);
+    /** Release the port subscription (the router's injector is being destroyed). */
+    dispose(): void;
+    private build;
+}

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

@@ -27,6 +27,7 @@ export interface DensityGrid {
     /** World size of one voxel per axis, in the observations' units. */
     voxelSize: [number, number, number];
 }
+/** Kernel and observation subset for a density estimate. */
 export interface DensityOptions {
     /** Kernel σ per axis, in the observations' units. */
     sigma: [number, number, number];
@@ -44,12 +45,21 @@ export interface DensityOptions {
  */
 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.
+ * A normalised 1-D Gaussian kernel of radius `ceil(3σ)` (at least 1), centre at
+ * index `radius`.
+ */
+export declare function gaussianKernel(sigma: number): {
+    kernel: Float32Array;
+    radius: number;
+};
+/**
+ * In-place separable Gaussian along one axis of a w x h x d field. A 2-D field is
+ * the `d = 1` case.
  *
- * 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.
+ * The ONE blur for every field in this folder: the 2-D gene map, the gene-map
+ * volume and the density volumes all smooth through it. Two copies of a separable
+ * blur would be two chances to smooth an 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;
 /**

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

@@ -19,45 +19,16 @@ import { ColormapValue } from '../contracts/display-types';
  *
  * 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.
+ * Everything is a flat `Float32Array` of `[r,g,b,a, …]` in 0..1 — one
+ * allocation for N points, GPU-upload shaped. napari-js (≥ 0.15)
+ * `PointsLayer.faceColor` and `Points3DLayer.colors` take it as is.
  */
-/** napari-js per-point colour tuple: r, g, b, a in 0..1. */
+/** One RGBA colour, r, g, b, a in 0..1 (napari-js's broadcast colour). */
 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
@@ -73,12 +44,14 @@ interface MuteOptions {
     /** `1` at index i mutes observation i. Absent ⇒ nothing is muted. */
     muted?: Uint8Array | null;
 }
+/** Options for {@link encodeCategorical}: a colour per category, plus muting. */
 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;
 }
+/** Options for {@link encodeContinuous}: a colormap, a contrast window and scaling, plus muting. */
 export interface ContinuousEncodingOptions extends MuteOptions {
     /** 256-entry RGB table from {@link buildColormapLut}. */
     lut: Rgb[];
@@ -90,8 +63,8 @@ export interface ContinuousEncodingOptions extends MuteOptions {
     /** 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. */
+/** Parse a CSS colour (`#rgb` / `#rrggbb`, see {@link parseCssColor}) to 0–255 RGB; unparseable
+ *  input falls back to grey. Exported so the tile layers parse palettes exactly as the markers do. */
 export declare function parseHex(hex: string): Rgb;
 /**
  * Per-category colours: the column's authored `colors` where present (so the
@@ -110,7 +83,9 @@ export declare function encodeContinuous(values: Float32Array, opts: ContinuousE
  * 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.
+ * usable window. A large vector is windowed from an even sample of it — see
+ * `spatial/stats.ts` — because this runs on every recolour, and sorting millions
+ * of values each time cost most of a second.
  */
 export declare function contrastWindow(values: Float32Array, lo?: number, hi?: number): [number, number];
 /**
@@ -122,14 +97,6 @@ export declare function contrastWindow(values: Float32Array, lo?: number, hi?: n
  * 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

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

@@ -40,6 +40,10 @@ export interface ExpressionFieldOptions {
     /** Observations to include; every one when absent (a plane, a selection). */
     indices?: Uint32Array;
 }
+/**
+ * A 2D field of kernel-weighted mean expression on a `width × height` grid, with the
+ * support that says where it was actually measured.
+ */
 export interface ExpressionField {
     width: number;
     height: number;
@@ -60,6 +64,15 @@ export interface ExpressionField {
  * than an empty one the reader has to interpret.
  */
 export declare function expressionField(obs: SpatialObservations, opts: ExpressionFieldOptions): ExpressionField | null;
+/**
+ * Contrast window of a gene map (2-D or 3-D), from percentiles of the MEASURED pixels.
+ *
+ * `mean` is 0 wherever `support` is 0, and those zeros are not data: windowing the whole
+ * array pins the low percentile at 0 and slides the high one upward on any section the
+ * tissue does not fill, so the colours stop describing what was measured. `lo`/`hi` are
+ * fractions, as for `contrastWindow`; `[0, 1]` when nothing was measured.
+ */
+export declare function fieldContrastWindow(field: Pick<ExpressionField | ExpressionVolumeField, 'mean' | 'support'>, lo?: number, hi?: number): [number, number];
 /**
  * Colour a field into RGBA8 for a `channels: 4` image source.
  *
@@ -73,28 +86,7 @@ export declare function colorExpressionField(field: ExpressionField, lut: readon
     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.
- */
+/** Options for {@link expressionVolume}. */
 export interface ExpressionVolumeOptions {
     /** Kernel σ per axis, in the observations' own units. The z term is used only
      *  when {@link interpolate} is set. */
@@ -107,6 +99,10 @@ export interface ExpressionVolumeOptions {
      *  sheets isolated at their own planes. */
     interpolate?: boolean;
 }
+/**
+ * The 3D counterpart of {@link ExpressionField}: kernel-weighted mean expression on a
+ * `width × height × depth` voxel grid, with its support.
+ */
 export interface ExpressionVolumeField {
     width: number;
     height: number;
@@ -118,6 +114,28 @@ export interface ExpressionVolumeField {
     /** Finite range of `mean` over the supported voxels, for a contrast window. */
     range: [number, number];
 }
+/**
+ * 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 declare function expressionVolume(obs: SpatialObservations, grid: DensityGrid, opts: ExpressionVolumeOptions): ExpressionVolumeField | null;
 /**
  * Encode a field into the uint8 scalar a `VolumeLayer` renders, windowed the same

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

@@ -12,6 +12,7 @@
 /** 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;
+/** A 2D camera framing: where to centre, and how far to zoom. */
 export interface SpatialFraming {
     /** World point to put at the centre of the viewport. */
     center: [number, number];

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

@@ -35,6 +35,7 @@ export interface HeatmapGroups {
     codes: Uint16Array;
     categories: readonly string[];
 }
+/** Options for {@link heatmapMatrix}: the observations, scaling and size limits. */
 export interface HeatmapMatrixOptions {
     /** Observations to include; every one when absent (an ROI selection). */
     indices?: Uint32Array;
@@ -62,6 +63,7 @@ export interface HeatmapMatrixOptions {
      */
     maxCols?: number;
 }
+/** Mean expression of genes (rows) per group (columns), ready for a heatmap trace. */
 export interface HeatmapMatrix {
     /** Gene names, one per row, in the order given. */
     rows: string[];