@jax-data-science/sci-image-visualizer 0.3.3 → 0.5.0

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

@@ -6,7 +6,10 @@ import { ClassPreset, PresetSet } from './models/class-preset';
 import { PlotlyService } from './implementations/plotly/plotly.service';
 import { OpenSeadragonVisualizerService } from './implementations/osd/openseadragon-visualizer.service';
 import { PlotType, PlotTypeDescriptor } from './contracts/plot-type';
-import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from './contracts/visualizer.contract';
+import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls, ISpatialControls } from './contracts/visualizer.contract';
+import { SpatialDataPort } from './contracts/ports/spatial-data.port';
+import { RegionStore } from './store/region-store.service';
+import { SpatialSelectionStore } from './store/spatial-selection.service';
 import { ViewerCapabilities } from './contracts/capabilities.contract';
 import { IRegionOverlay } from './contracts/region-overlay.contract';
 import { IRegionEditorApi } from './contracts/region-editor-api.contract';
@@ -14,6 +17,7 @@ import { IChannelHistogramApi, IChannelState, IHistogram } from './contracts/cha
 import { VisualizerStore } from './store/visualizer-store.service';
 import { NapariVisualizerService } from './implementations/napari-js/napari-visualizer.service';
 import { VizConfig } from './contracts/viz-config';
+import { PlotModeViewport } from './contracts/plot-type-contribution.contract';
 import * as i0 from "@angular/core";
 export declare class RoutingVisualizerService implements IVisualizer, IRegionEditorApi, IChannelHistogramApi {
     private plotly;
@@ -21,6 +25,9 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     private napari;
     private store;
     private config;
+    private regionStore;
+    private selectionStore;
+    private spatialData;
     private currentPlotType;
     private lastRendered;
     /** OSD failed for the *current* render cycle (e.g. a fresh file still caching
@@ -32,12 +39,18 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** napari-js failed for the current render cycle → fall back to OSD (then Plotly).
      *  Reset by reset() at the start of every cycle, like {@link osdFellBack}. */
     private napariFellBack;
-    constructor(plotly: PlotlyService, osd: OpenSeadragonVisualizerService, napari: NapariVisualizerService, store: VisualizerStore, config: VizConfig);
+    constructor(plotly: PlotlyService, osd: OpenSeadragonVisualizerService, napari: NapariVisualizerService, store: VisualizerStore, config: VizConfig, regionStore: RegionStore, selectionStore: SpatialSelectionStore, spatialData?: SpatialDataPort | null);
     private isImageType;
-    /** The 2D napari types (image + region-centroid scatter) — a 2D fallback chain (OSD, then Plotly). */
+    /** The 2D napari types (image, region-centroid scatter, spatial omics) — a 2D fallback chain
+     *  (OSD, then Plotly).
+     *
+     *  NOTE for SPATIAL_OMICS: only napari-js draws the observation markers. If it fails (no WebGPU,
+     *  device loss) the fallback renders the tissue image ALONE — the spatial layer is absent, not
+     *  degraded. That is deliberate for now: showing the slide beats showing nothing, and a Plotly
+     *  `scattergl` spatial mode is the planned real fallback (see the plot-mode design doc). */
     private isNapariImageType;
-    /** The 3D napari types (volume/isosurface, either resolution) — no 2D fallback exists (OSD is
-     *  image-only), so they fall straight to Plotly. */
+    /** The 3D napari types (volume/isosurface/surface/scatter, plus the 3D spatial cloud) — no 2D
+     *  fallback exists (OSD is image-only), so they fall straight to Plotly. */
     private isNapari3dType;
     /**
      * Backend to attempt for the current plot type this render. The fallback chains below are
@@ -86,6 +99,9 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     resetSurfaceCamera(): void;
     setResolutionScale(scale: number): void;
     getResolutionScale(): number;
+    /** The viewport of the backend on screen, for a contributed plot mode. Null
+     *  when that backend cannot provide one (e.g. OSD fell back to Plotly). */
+    getPlotModeViewport(): PlotModeViewport | null;
     getPlotTypeDescriptors(): PlotTypeDescriptor[];
     setStackLoading(b: boolean): void;
     cancelLoading(): void;
@@ -207,6 +223,33 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** Intensity (line-ROI) controls — always Plotly's, since the line profiles
      *  render their inset on Plotly regardless of which backend draws the image. */
     getIntensityControls(): IIntensityControls | null;
+    /**
+     * Spatial-omics controls, or null when no `SPATIAL_DATA_PORT` is bound.
+     *
+     * Implemented HERE rather than on a backend because the state is
+     * backend-neutral: the view state lives in the shared `VisualizerStore` (like
+     * the colormap), so the controls keep working across a plot-type switch and a
+     * host can drive them before any backend has mounted.
+     */
+    getSpatialControls(): ISpatialControls | null;
+    /**
+     * Whether `dataset` can answer this colour source.
+     *
+     * A column is checkable against the declared list. A gene is checkable only when
+     * the dataset inlines its feature names — a dataset too wide to inline them
+     * (typeahead-only) keeps the source, and a name that turns out not to exist
+     * surfaces as the chart's "could not be charted" rather than as a silent reset.
+     */
+    private canColorBy;
+    /** Memoised so consumers can hold the object across calls. */
+    private spatialControls;
+    /** Latest dataset, mirrored so `selectFromRegions()` can answer synchronously
+     *  — it runs from a button click and must not await a round-trip. */
+    private currentSpatialDataset;
+    /** 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;
+    private spatialDatasetSub;
     /** Load pixel frames for intensity sampling when OpenSeadragon owns the image
      *  (it doesn't feed Plotly's frame cache). No-op needed when Plotly renders. */
     ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
@@ -223,6 +266,6 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
      *  ROI at display resolution (sampling always lives in Plotly). */
     refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
     unsubscribe(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<RoutingVisualizerService, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RoutingVisualizerService, [null, null, null, null, null, null, null, { optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<RoutingVisualizerService>;
 }

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

@@ -0,0 +1,73 @@
+import { SpatialEmbedding, SpatialEmbeddingMeta } from '../contracts/spatial-dataset.contract';
+/**
+ * Run a t-SNE in a Web Worker and report progress.
+ *
+ * The panel offers this for a dataset that publishes no t-SNE — a dropped-in `.h5ad`
+ * typically carries one UMAP and nothing else. The server reduces to PCA (it needs the
+ * whole expression matrix, which the browser should not download); this takes those
+ * scores and embeds them here, where the GPU is.
+ *
+ * A thin wrapper on purpose: no Angular, no store. It owns one worker and one run, so a
+ * component can hold it, show a progress bar, and cancel — and so the whole thing can be
+ * tested by substituting a worker.
+ */
+export interface ComputeProgress {
+    /** 0..1, or null before the first report — a run starts with kNN and P, not iterations. */
+    fraction: number | null;
+    /** 'webgpu', 'wasm' or 'cpu' once known: it changes what a long wait means. */
+    backend: string | null;
+    message: string | null;
+}
+export interface ComputeRequest {
+    /** PCA scores, row-major `nObs x nDims`. */
+    scores: Float32Array;
+    nObs: number;
+    nDims: number;
+    dims: 2 | 3;
+    perplexity?: number;
+    iterations?: number;
+    seed?: number;
+}
+/** Factory, so a test can supply a worker without a bundler. */
+export type WorkerFactory = () => Worker;
+export declare class EmbeddingComputeRun {
+    private readonly factory?;
+    private worker;
+    private settled;
+    /**
+     * Settles a run that is still waiting, set for as long as one is.
+     *
+     * `terminate()` is called from outside — a dataset switch, a component being destroyed —
+     * and killing the worker on its own leaves the promise `run()` returned pending FOR
+     * EVER, because the settlement it was waiting for arrives as a worker message. The
+     * awaiting closure, and everything it captured, is retained with it. So termination
+     * settles the run itself.
+     */
+    private abandon;
+    /**
+     * `factory` is optional: without one the real worker module is imported on demand.
+     *
+     * Dynamically, and that is not laziness for its own sake — the module holds an
+     * `import.meta.url`, which ts-jest's CommonJS compile rejects outright, so a static
+     * import here would break every spec that touches this file.
+     */
+    constructor(factory?: WorkerFactory | undefined);
+    /**
+     * Start a run. Resolves with the coordinates, or null if cancelled.
+     *
+     * Rejects only on a real failure. Cancellation is a NULL rather than a rejection: a user
+     * pressing Cancel is not an error, and making callers tell the two apart in a catch
+     * block is how a cancelled run ends up reported as a crash.
+     */
+    run(request: ComputeRequest, meta: SpatialEmbeddingMeta, onProgress: (progress: ComputeProgress) => void): Promise<SpatialEmbedding | null>;
+    /** Ask the run to stop. It resolves with null shortly after. */
+    cancel(): void;
+    /**
+     * Stop immediately, abandoning any result. Safe to call twice.
+     *
+     * Unlike {@link cancel}, this does not wait for the worker to acknowledge — the run is
+     * settled here, with null, because nothing is left to deliver the answer.
+     */
+    terminate(): void;
+    get running(): boolean;
+}

package/lib/spatial/gene-search.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Narrowing a gene list to the handful a picker should actually render.
+ *
+ * A targeted panel has a few hundred genes and can simply be listed. A
+ * whole-transcriptome assay has ~18k-31k, and handing that many options to a dropdown
+ * costs a visible freeze on every keystroke — the control rebuilds and re-filters the
+ * whole array, and the browser lays out what the virtual scroller has not yet clipped.
+ * Measured on the Visium H&E bundle: 18,078 names.
+ *
+ * The names themselves are cheap to hold — strings already parsed from the manifest — so
+ * this does not fetch anything. What it caps is how many OPTION OBJECTS are ever
+ * materialised for the view. The rest of the corpus stays a plain array, searched per
+ * keystroke, which is the work a dropdown was doing anyway; the saving is in not asking
+ * a component to render, diff and re-filter thousands of rows it will never show.
+ *
+ * Ranking is PREFIX FIRST, then substring. Typing "Mb" should surface `Mbp` above
+ * `Adam1b`, which a plain `includes` would not do. It deliberately mirrors the example
+ * server's `/spatial/:id/features?q=` (see `lib/spatial.mjs`) so a dataset that inlines
+ * its names and one that does not order their suggestions the same way — the picker must
+ * not appear to rank differently depending on how the data happens to be served.
+ *
+ * Pure — no Angular, no port, no DOM — like `spatial-heatmap.ts`, and tested the same way.
+ */
+/**
+ * How many options a picker will materialise at once.
+ *
+ * Above the virtual-scroll threshold, so a capped list is still scrolled rather than laid
+ * out in full, and far below the point where rebuilding the array is perceptible.
+ */
+export declare const GENE_OPTIONS_MAX = 500;
+/**
+ * The best `limit` matches for `query`, prefix matches first.
+ *
+ * An empty query returns the head of the list rather than nothing: the dropdown opens
+ * before anything is typed, and an empty menu reads as "no genes" rather than "start
+ * typing". Matching is case-insensitive, because gene symbols are capitalised by
+ * convention and nobody types `Slc17a7` exactly.
+ */
+export declare function searchGeneNames(names: readonly string[], query: string, limit?: number): string[];
+/**
+ * The options a picker should show: the best matches, plus anything already chosen.
+ *
+ * A multi-select whose option list is capped must still carry its SELECTED values, or the
+ * control cannot resolve them — the chips lose their labels and, worse, a value absent
+ * from the options can be dropped from the model on the next change. Selections come
+ * first so they stay visible while a search narrows everything else.
+ */
+export declare function geneOptionsFor(names: readonly string[], query: string, selected?: readonly string[], limit?: number): string[];

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;