@jax-data-science/sci-image-visualizer 0.8.2 → 0.9.0

package/lib/implementations/napari-js/napari-spatial-3d-scene.d.ts

@@ -0,0 +1,212 @@
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { SpatialDataset, SpatialObservations } from '../../contracts/spatial-dataset.contract';
+import { SpatialViewState } from '../../contracts/display-types';
+import { SpatialSelectionMask } from '../../spatial/spatial-selection';
+import { Spatial3dScalars } from './napari-spatial-encoding';
+import { SpatialSceneBase, SpatialSession } from './napari-spatial-scene';
+import type { NapariScene, SceneContext } from './napari-scene';
+/**
+ * SPATIAL_OMICS_3D (review Appendix B, cluster K): observations as a 3D point cloud under the
+ * orbit camera, with the dataset's reference volume around it, per-cluster density volumes and the
+ * 3D gene map.
+ *
+ * Thinner than the 2D scene: there is no tissue image to render (a registered volume like the
+ * Allen CCF has no single reference plane), so no readback and no navigator; the 3D scale bar
+ * follows the dataset (see {@link installScaleBar}). The region tools work in SCREEN space through
+ * the tool bridge's 3D interaction — a lasso selects the cells under it, and an orbit clears the
+ * shape while keeping the selection. The first 3D layer added frames the camera (`fit3d: 'once'`).
+ */
+export declare class Spatial3dScene extends SpatialSceneBase implements NapariScene {
+    /** The 3D point cloud. One layer: selection is a per-point alpha on it, not a second. */
+    private points;
+    private layerKey;
+    /** Interleaved x,y,z, cached so a colour change does not re-walk 3.7M observations. */
+    private positions;
+    /** Identity of the scalars currently uploaded — see {@link rebuild}. */
+    private scalarKey;
+    /** Observation indices the cached positions belong to, in the same order; null when every
+     *  observation is drawn. Without it a projection built from the positions is indexed by DRAWN
+     *  order and silently attributes each point to the wrong observation as soon as a section is
+     *  isolated. */
+    private drawn;
+    /** The anatomical volume the cloud sits inside, when the dataset has one. */
+    private volume;
+    private volumeKey;
+    /** Per-cluster density volumes drawn alongside the cloud, and what they were
+     *  built from — rasterising is seconds of work, so it must not repeat for a
+     *  change that cannot affect the field. */
+    private densityLayers;
+    private densityKey;
+    /** The 3D gene map's volume layer and the inputs it was coloured for (its field is cached in
+     *  the session, on a clock of its own). */
+    private geneMapLayer;
+    private geneMapKey;
+    /** Offset applied to observation coordinates to sit them in the volume's box. */
+    private origin;
+    /**
+     * napari-js's depth-aware pick over the cloud, and the projection the ROI selection reads. It
+     * owns the caching policy: re-project lazily, on the first pick after the camera, the canvas or
+     * the cloud's data moved (never on the camera event, so an orbit drag pays nothing), into
+     * reused buffers, with a screen index once the cloud is large enough.
+     */
+    private picker;
+    private scaleBar;
+    /** Dataset the scale bar was built for. */
+    private scaleBarKey;
+    /** The density rasterisation and the 3D gene-map estimate in flight (off the main thread
+     *  past the worker threshold, SPATIAL-19): a new key supersedes — and aborts — the previous
+     *  one; a rebuild that leaves the key alone lets it finish. */
+    private readonly densityLoads;
+    private readonly geneMapLoads;
+    /** The store's invert setting, which the density volumes follow (no other subscription of
+     *  this scene carries it). */
+    private invertSub;
+    constructor(ctx: SceneContext, session: SpatialSession);
+    mount(): Promise<void>;
+    /** The observations' own z is on screen: there is no plane to step. */
+    setZ(): void;
+    /** A cloud has no intensity distribution for the histogram pane. */
+    histogram(): IHistogram | null;
+    /**
+     * Every observation's position on the canvas under the current 3D camera (for the ROI
+     * selection), indexed by observation with NaN for anything not drawn. Null before the cloud
+     * is built.
+     *
+     * The projection is the picker's (see {@link picker}); what is left is the part that is
+     * genuinely this adapter's: SCATTERING the drawn subset back into observation order. The cloud
+     * holds only the points of the displayed section, in its own packing; every consumer indexes by
+     * observation. NaN stands for "not on screen", which is also the right answer for an
+     * observation whose section is hidden.
+     */
+    screenProjection(obs: SpatialObservations): Float32Array | null;
+    dispose(): void;
+    /**
+     * The observation under a client position: the FRONT-most marker within `slackPx` of the
+     * pointer (ties by distance), as napari-js's {@link PointPicker} picks it. That matters more
+     * than it sounds: the renderer depth-tests the billboards, and in a 3.7M-point cloud the cursor
+     * covers many of them — picking the one nearest the cursor's centre regularly names a cell that
+     * something else is drawn over. The picker also takes each point's radius from the layer's
+     * per-point `sizes`, so a selected marker, drawn larger, is as large to the pointer.
+     */
+    protected pickObservation(clientX: number, clientY: number, slackPx: number): number;
+    /** Replace the cloud's picker (null: no cloud), releasing the old one's camera listener. */
+    private setPicker;
+    /**
+     * Scale bar for the cloud, measured at the ORBIT PIVOT.
+     *
+     * A perspective camera has no single scale — things farther away are smaller — so a bar can
+     * only be true at one depth. The pivot is the honest choice: it is what the camera is framing,
+     * what a zoom moves towards, and where the eye is anyway. napari's own 3D scale bar works the
+     * same way.
+     *
+     * napari-js's `ScaleBarOverlay` in `'3d'` mode measures there: CSS px per world unit is the
+     * reciprocal of `Camera3D.worldPerPixel` — the scale `Camera3D.pan` uses to track the cursor.
+     * The bar then converts through `micronsPerUnit`, and draws nothing at all when the dataset does
+     * not declare one, because a bar labelled in microns over unknown units would read as a
+     * measurement.
+     */
+    private installScaleBar;
+    /** (Re)build the 3D point cloud for the current dataset + view state. */
+    protected rebuild(dataset: SpatialDataset | null, view: SpatialViewState, selection?: SpatialSelectionMask): Promise<void>;
+    /**
+     * Draw the point cloud: a new layer for new geometry (a dataset or a section), the colour
+     * source swapped in place otherwise; then the selection and the visibility.
+     */
+    private drawCloud;
+    /** Interleaved x,y,z of the `shown` observations (null: all of them), offset by {@link origin}. */
+    private cloudPositions;
+    /**
+     * Selection is a PER-POINT alpha, in the one layer.
+     *
+     * It used to be a second layer: with a single opacity for the whole cloud, the only way
+     * to highlight a subset was to draw it again on top at full opacity while the parent
+     * dropped to the muted level. That second layer had to be kept in step through every
+     * colormap, window and size change, and the two then depth-sorted against each other as
+     * separate draws. Per-point alphas and sizes give the same reading — muted cloud, bright
+     * selection, slightly larger so a small one is findable inside 3.7M points — in one.
+     *
+     * `shown` is the drawn subset (null: every one of the `total` observations), so the alphas
+     * follow the drawn order.
+     */
+    private applySelection;
+    /**
+     * The **3D gene map**: the active gene's expression over the whole sectioned
+     * specimen, as one raymarched volume.
+     *
+     * Two things it can be, and the panel's `Volume rendering` toggle picks which:
+     *
+     *  - **sheets** — exactly the planes that were imaged, each carrying that
+     *    slide's own 2D gene map, with the gaps between sections empty. A stack of
+     *    measured fields, at their true z.
+     *  - **volume** — the same fields smoothed along z, so the planes between the
+     *    sections carry an interpolated value. An estimate, and drawn as a
+     *    translucent cloud for the same reason the density volumes are.
+     *
+     * One `VolumeLayer` rather than a textured quad per section: an `ImageLayer`
+     * renders only at `ndisplay === 2`, so 53 sheets in the orbit view would need a
+     * new layer type upstream — while a scalar volume whose z sampling already IS
+     * the section spacing expresses the sheets exactly, and the same lattice then
+     * gives the interpolated version for free.
+     *
+     * Estimated on the reference volume's own lattice (`densityGrid` at stride 1),
+     * so the field lands voxel-for-voxel on the anatomy and needs no offset — a
+     * `VolumeLayer` has no translate, and napari centres both boxes on the world
+     * origin.
+     */
+    private ensureGeneMap;
+    /**
+     * Cluster density volumes: each cluster rasterised into a smooth scalar field and
+     * raymarched alongside the cloud, tinted with the cluster's own legend colour.
+     *
+     * This is what makes a serially sectioned dataset readable as an anatomical
+     * distribution. The cloud shows measured cells and nothing else — but at 200 µm
+     * section spacing the eye cannot integrate a stack of discs into a shape, and
+     * every gap reads as absence. A density field is a different object from a cell:
+     * an estimate, defined between the imaged planes, drawn as a translucent cloud so
+     * it cannot be mistaken for measurement. Individual cells are never interpolated —
+     * consecutive sections sample different cells, so there is nothing to interpolate
+     * along.
+     *
+     * One volume per cluster rather than one for everything: additive blending is what
+     * makes two clusters' territories comparable, and a single blended field would
+     * answer no question anyone asks of a taxonomy. Capped at `DENSITY_MAX_CLUSTERS` by cell
+     * count.
+     *
+     * Keyed so it rebuilds only when the field would actually differ — the dataset,
+     * the colour column, the bandwidth, or the selection.
+     */
+    private ensureDensityVolumes;
+    /**
+     * The clusters to rasterise: the categories of the active categorical colouring,
+     * biggest first and capped, each with its legend colour, restricted to the current selection
+     * when there is one. With no categorical colouring there is one group — total cell density,
+     * which is a real question on its own ("where is the tissue dense?") and the honest thing to
+     * show when the view is not encoding a taxonomy.
+     */
+    private densityGroups;
+    /**
+     * Add (or keep) the dataset's reference volume, and derive the offset that sits the
+     * observations inside it.
+     *
+     * `VolumeLayer` has no translate: napari-js maps the volume's unit cube to a world box
+     * **centred on the origin**, sized `dims x voxelSize`. The observations, by contract, are in
+     * the volume's own frame with its near corner at the coordinate origin. So the two only line
+     * up if the POINTS move — by half the box — which is what {@link origin} is.
+     *
+     * A failed or absent volume is not fatal: the cloud renders on its own, at its own
+     * coordinates, and the camera frames the points instead.
+     */
+    private ensureVolume;
+    /** Drop every layer of the cloud (the dataset went away, or has no z). */
+    private removeLayers;
+    /**
+     * What colours the cloud.
+     *
+     * Continuous data goes through the active colormap with the same percentile window the 2D path
+     * uses. Categorical data is one RGBA per point from the column's palette, so any number of
+     * categories keeps its own colour — see `encodeSpatial3dCategorical`.
+     */
+    private scalarEncoding;
+    /** Continuous values → the active colormap over a percentile-clipped window. */
+    encodeContinuous(source: Float32Array, view: SpatialViewState): Spatial3dScalars;
+}

package/lib/implementations/napari-js/napari-spatial-encoding.d.ts

@@ -0,0 +1,114 @@
+import type { Colormap } from 'napari-js';
+import { Rgb } from '../../contracts/colormap-lut';
+import { CategoricalColumn } from '../../contracts/spatial-dataset.contract';
+import { SpatialViewState } from '../../contracts/display-types';
+import { type RGBA } from '../../spatial/spatial-encoding';
+import { SpatialSelectionMask } from '../../spatial/spatial-selection';
+/**
+ * The spatial scenes' pure colour and grouping math: what the 2D markers, the 3D cloud and the
+ * density volumes are coloured with, as functions of the data, the view and a LUT. No viewer, no
+ * port, no store (review Appendix B, step 1).
+ */
+/** Marker radius (image px) for a dataset that declares none — segmented cells often don't. */
+export declare const SPATIAL_FALLBACK_RADIUS = 4;
+/** Smallest marker DIAMETER, in slice pixels, over a volume-backed dataset. A cell's real
+ *  size is honoured wherever it survives the grid: the ABC atlas serves 5 µm radii on a
+ *  40 µm/px template, so drawing them to scale would put every cell a fifth of a pixel wide
+ *  and the section would come up empty. The point-size control scales up from this floor. */
+export declare const SPATIAL_SLICE_MIN_DIAMETER_PX = 1.5;
+/** Longest side of the gene-map raster, in field pixels. A gene map is a smooth
+ *  field read as territory, so it gains nothing from matching a 2 Gpx slide's
+ *  resolution — and the estimate costs one pass over this many pixels. */
+export declare const GENE_MAP_MAX_SIDE = 512;
+/** Kernel σ in field pixels at smoothing 1: wide enough to read between cells,
+ *  tight enough to keep a nucleus-scale structure distinct. */
+export declare const GENE_MAP_SIGMA = 2.5;
+/**
+ * In-plane coarsening of the 3D gene map's lattice, relative to the reference
+ * volume. The field is smooth, so its detail is set by the kernel rather than the
+ * raster — and the estimate is a pair of separable blurs, which at the template's
+ * full resolution means seconds of work per toggle.
+ */
+export declare const GENE_MAP_VOLUME_STRIDE = 2;
+/** Clusters drawn as density volumes at once. Past a handful, additive translucent
+ *  clouds stop being separable by eye — and each one is a full rasterisation. */
+export declare const DENSITY_MAX_CLUSTERS = 6;
+/** How much larger a selected marker is drawn, so a small selection is findable inside a
+ *  3.7M-point cloud rather than merely brighter. */
+export declare const SPATIAL_SELECTED_SIZE_SCALE = 1.6;
+/** Base marker diameter for the 3D cloud, in SCREEN pixels (the layer's unit). */
+export declare const SPATIAL_3D_BASE_SIZE = 3;
+/** Colour for observations when nothing is selected to colour by: visible, neutral, and
+ *  obviously not encoding anything. */
+export declare const SPATIAL_NEUTRAL_COLOR: [number, number, number, number];
+/** {@link SPATIAL_NEUTRAL_COLOR} as a hex colour (alpha dropped), for the encoders and the
+ *  density-volume tint. */
+export declare const SPATIAL_NEUTRAL_HEX: string;
+/**
+ * Contrast windows memoised per (values array, lo, hi, log). `contrastWindow` sorts every value,
+ * and the spatial colouring re-runs it on each opacity, selection or colormap change while the
+ * coloured vector itself is unchanged (review SPATIAL-12). Keyed by the vector's identity, so a
+ * new column or gene vector is a miss and an old one is collected with its windows.
+ */
+export declare class ContrastWindowCache {
+    private readonly byVector;
+    get(values: Float32Array, lo: number, hi: number, log: boolean, compute: () => [number, number]): [number, number];
+}
+/**
+ * What the 3D points layer needs to colour a cloud: for continuous data, one scalar per point, a
+ * colormap and the window that maps scalars onto it; for categorical data, one packed RGBA per
+ * point (`Points3DLayer.colors`, which wins over the scalars).
+ */
+export type Spatial3dEncoding = Spatial3dScalars | Spatial3dColors;
+/** A cloud coloured through the colormap: scalars, colormap and window. */
+export interface Spatial3dScalars {
+    kind: 'scalars';
+    values: Float32Array;
+    colormap: Colormap;
+    contrastLimits: [number, number];
+}
+/** A cloud coloured point by point: packed RGBA, 4 floats per point. */
+export interface Spatial3dColors {
+    kind: 'colors';
+    colors: Float32Array;
+}
+/** A one-colour colormap, for the "nothing to colour by" state. */
+export declare function spatialFlatColormap(): Colormap;
+/**
+ * Category codes → one RGBA per point, for any number of categories.
+ *
+ * The 2D markers' encoding, with one difference: a point with no category stays opaque (grey),
+ * as it always has in the cloud, where the selection dims through the layer's per-point alphas
+ * instead. It used to be smuggled through the scalar channel as a stepped 256-entry LUT, which
+ * kept at most 95 categories apart (review SPATIAL-11, NAPARI-SVC-18).
+ */
+export declare function encodeSpatial3dCategorical(codes: Uint16Array, colors: string[]): Spatial3dColors;
+/** Continuous values → `lut` over a percentile-clipped window (log1p first when the view's log
+ *  scale is on), for the 3D cloud's scalar channel. */
+export declare function encodeSpatial3dContinuous(source: Float32Array, view: SpatialViewState, lut: Rgb[], windows: ContrastWindowCache): Spatial3dScalars;
+/** Continuous values → per-point RGBA through `lut` and a clipped window (log scale per the
+ *  view), for the 2D markers. */
+export declare function encodeSpatialContinuous(values: Float32Array, view: SpatialViewState, lut: Rgb[], windows: ContrastWindowCache, muted?: Uint8Array | null): Float32Array;
+/** Marker colours: packed per-point RGBA (4 floats per point, the shape napari-js copies straight
+ *  into its instance buffer), or one RGBA broadcast to every point. */
+export type PointColors = Float32Array | RGBA;
+/** Whether a colour input is one RGBA per point rather than one broadcast RGBA. */
+export declare function isPerPoint(colors: PointColors): colors is Float32Array;
+/** Per-point colours for the drawn subset. A broadcast tuple stays broadcast —
+ *  it is one colour for every point either way. */
+export declare function gatherColors(colors: PointColors, indices?: Uint32Array): PointColors;
+/** One density volume's observations: a cluster (or all cells), with its legend colour. */
+export interface DensityGroup {
+    name: string;
+    color: string;
+    indices?: Uint32Array;
+}
+/** The single group drawn when the colouring is not categorical: total cell density, within the
+ *  selection when there is one. */
+export declare function totalDensityGroup(selection: SpatialSelectionMask): DensityGroup;
+/**
+ * The clusters of a categorical column to rasterise, biggest first and capped at
+ * {@link DENSITY_MAX_CLUSTERS}, each with its legend colour — restricted to the selection when
+ * there is one, so "select a region, check the box" answers which clusters live there.
+ */
+export declare function rankDensityGroups(columnName: string, column: CategoricalColumn, count: number, selection: SpatialSelectionMask): DensityGroup[];

package/lib/implementations/napari-js/napari-spatial-hover.d.ts

@@ -0,0 +1,89 @@
+import type { Viewer } from 'napari-js';
+import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import { SpatialViewState } from '../../contracts/display-types';
+import { SpatialSelectionStore } from '../../store/spatial-selection.service';
+import { NapariSpatialTileLayers } from './napari-spatial-tiles';
+/** Pointer distance, in screen pixels, that still counts as "on" a marker.
+ *  Generous relative to a 1.5px disc: the cursor is a blunt instrument, and a
+ *  tooltip you have to hunt for is worse than none. */
+export declare const HOVER_RADIUS_PX = 10;
+/** What the hover reads from the spatial scene it serves. */
+export interface SpatialHoverHost {
+    /** The orbit view rather than the 2D view (no transcript markers to ask first). */
+    readonly is3d: boolean;
+    readonly viewer: Viewer;
+    readonly port: SpatialDataPort | null;
+    readonly selection: SpatialSelectionStore | null;
+    /** The dataset on screen, as the spatial subscription last saw it. */
+    dataset(): SpatialDataset | null;
+    /**
+     * The OBSERVATION drawn under a client position, or -1 — `slackPx` screen pixels of slack
+     * around the pointer. The scene owns the pick (napari-js's, on the layer it drew) and maps the
+     * drawn index back to the observation.
+     */
+    pick(clientX: number, clientY: number, slackPx: number): number;
+    /** The 2D transcript markers, which sit on top of everything and are asked first. */
+    tiles(): NapariSpatialTileLayers | null;
+    /** A region tool owns the pointer (placing a polygon vertex is also a still click). */
+    toolActive(): boolean;
+    outsideZone<T>(fn: () => T): T;
+    inZone<T>(fn: () => T): T;
+}
+/**
+ * Cursor tooltip and click-to-select for the spatial views (review Appendix B, cluster L): hover a
+ * marker, read its class; click it, select the class — the canvas equivalent of the panel's
+ * legend. The tooltip and the click share ONE hit-test, so a click selects the class the tooltip
+ * names (NAPARI-SVC-5).
+ *
+ * A 34-entry legend cannot be read back from a dot — several classes get similar colours, and
+ * matching one to a swatch by eye is exactly the task this removes. It reports whatever the cloud
+ * is CURRENTLY coloured by ({@link resolveSource}), so it and the legend can never say different
+ * things.
+ */
+export declare class SpatialHover {
+    private readonly host;
+    private tooltip;
+    /** What the markers are coloured by, resolved once per colour source rather than per hover. */
+    private hoverSource;
+    private hoverSourceKey;
+    /** Latest wins within the scene: the KEY is only committed once a resolution lands, so a
+     *  superseded fetch cannot leave the cache claiming to hold a source it never stored. */
+    private readonly resolutions;
+    private pointer;
+    private frame;
+    private off;
+    constructor(host: SpatialHoverHost);
+    /**
+     * Listen on `el` (the plot host) rather than the canvas, so it keeps working over the region
+     * overlay (an SVG covering the canvas, which would otherwise swallow every move), and throttle
+     * to one hit-test per animation frame: a pointermove can fire far more often than that, and
+     * the first test after an orbit re-projects the cloud.
+     */
+    install(el: HTMLElement): void;
+    /** Hide the tooltip (the navigator is being dragged, say). */
+    hide(): void;
+    /** Remove the listeners and the tooltip, and drop the colour source. */
+    dispose(): void;
+    /**
+     * What the tooltip says, resolved once per colour source rather than per hover.
+     *
+     * Fetched separately from the colouring on purpose: the reference port caches
+     * columns, but a host's need not, and re-fetching a 3.7M-element vector because
+     * the pointer moved would be indefensible either way.
+     */
+    resolveSource(dataset: SpatialDataset | null, view: SpatialViewState): Promise<void>;
+    /** Hit-test the last pointer position and show or hide the tooltip. */
+    private update;
+    /**
+     * Select the class of the marker at a client position — the canvas equivalent of
+     * clicking that class in the panel's legend, and the same selection object, so
+     * the two controls cannot produce different results.
+     *
+     * Clicking a class that is already the whole selection CLEARS it, which is what
+     * the legend does. Compared against the selection itself rather than against a
+     * remembered click, so selecting from the legend and then clicking the same
+     * class on the canvas still toggles.
+     */
+    private selectClassAt;
+}

package/lib/implementations/napari-js/napari-spatial-scene.d.ts

@@ -0,0 +1,118 @@
+import { Observable } from 'rxjs';
+import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import { SpatialViewState } from '../../contracts/display-types';
+import { ExpressionField, ExpressionVolumeField } from '../../spatial/spatial-expression';
+import { SpatialSelectionMask } from '../../spatial/spatial-selection';
+import { SpatialSelectionStore } from '../../store/spatial-selection.service';
+import { VisualizerStore } from '../../store/visualizer-store.service';
+import { Supersede } from '../../util/supersede';
+import { ContrastWindowCache } from './napari-spatial-encoding';
+import { SpatialHover } from './napari-spatial-hover';
+import { NapariSpatialTileLayers, TranscriptEstimate } from './napari-spatial-tiles';
+import { Rgb } from '../../contracts/colormap-lut';
+import type { SceneContext } from './napari-scene';
+/** What the spatial subscription last saw: the dataset, the view state and the selection. */
+export type SpatialLatest = [SpatialDataset | null, SpatialViewState, SpatialSelectionMask];
+/** Where the spatial tile layers' panel outputs go (the service's subjects and badge). */
+export interface SpatialTileSinks {
+    /** The continuous LUT the view is using (so cells coloured by a gene match the markers). */
+    continuousLut(view: SpatialViewState): Rgb[];
+    estimateChanged(estimate: TranscriptEstimate | null): void;
+    geneCountsChanged(counts: Record<string, number> | null): void;
+    densityChanged(stats: {
+        lo: number;
+        hi: number;
+        max: number;
+    }): void;
+    loadingChanged(layers: string[]): void;
+}
+/** The 2D scene the tile layers currently draw into. */
+export interface SpatialTileOwner {
+    canvasSize(): [number, number];
+    /** Outlines appeared or disappeared: the markers' visibility follows. */
+    polygonsShownChanged(): void;
+}
+/** An estimated field and the inputs it was estimated for. */
+export interface FieldCache<T> {
+    key: string | null;
+    field: T | null;
+}
+/**
+ * The spatial state that outlives a scene (review Appendix B): what the subscription last saw, the
+ * memoised percentile windows, the selection revision counter and the estimated gene-map FIELDS —
+ * viewer-independent and expensive, so a re-plot recolours the cached field instead of estimating
+ * it again. Everything that names a layer of a viewer belongs to the scene instead.
+ */
+export declare class SpatialSession {
+    readonly port: SpatialDataPort | null;
+    readonly selection: SpatialSelectionStore | null;
+    private readonly sinks;
+    /** Latest (dataset, view, selection) the spatial subscription saw — so a slice change can
+     *  rebuild the markers for the new plane, and the tile layers and the hover can read it. */
+    latest: SpatialLatest | null;
+    /** Spatial colouring's percentile windows, memoised per coloured vector (SPATIAL-12). */
+    readonly contrastWindows: ContrastWindowCache;
+    /** The 2D gene map's field (the expensive half: it survives a recolour and a re-plot). */
+    readonly geneMap: FieldCache<ExpressionField>;
+    /** The 3D gene map's field. */
+    readonly geneMapVolume: FieldCache<ExpressionVolumeField>;
+    private lastSelectionSeen;
+    private selectionRevision;
+    /** Level-of-detail cell outlines, transcripts and density over the 2D view — created on first
+     *  use, only when a spatial port is bound, and kept across scenes (its tile caches with it). */
+    private tileLayers;
+    private tileOwner;
+    constructor(port: SpatialDataPort | null, selection: SpatialSelectionStore | null, sinks: SpatialTileSinks);
+    /** The tile layers, if they were ever built. */
+    get tiles(): NapariSpatialTileLayers | null;
+    /**
+     * The tile layers, built on first use (null without a spatial port), now drawing for `owner`.
+     * Their host callbacks read the session's live state and the owner's canvas, so they never hold
+     * a stale dataset or colormap.
+     */
+    claimTiles(owner: SpatialTileOwner): NapariSpatialTileLayers | null;
+    /** `owner`'s scene is going away: take the tile layers off its viewer. */
+    releaseTiles(owner: SpatialTileOwner): void;
+    /**
+     * A revision number for a selection object.
+     *
+     * The store hands out a NEW mask object per change, so object identity is the
+     * cheap and exact way to tell two selections apart — a fingerprint over 3.7M
+     * mask bytes would be neither. Counting revisions keeps the cache key a short
+     * string.
+     */
+    selectionRev(selection: SpatialSelectionMask): number;
+    /**
+     * Everything a spatial scene redraws on: the dataset, the view state, the selection — and the
+     * display colormap and reverse flag, which are inputs here, not just something read at build
+     * time: `continuousColormap: null` means "follow the image's colormap", and a setting that only
+     * takes effect at the next unrelated rebuild is not one. Null without a spatial port.
+     */
+    changes$(store: VisualizerStore): Observable<[SpatialDataset | null, SpatialViewState, SpatialSelectionMask, unknown, boolean]> | null;
+}
+/**
+ * What the 2D and 3D spatial scenes share: the subscription that redraws them, the hover over
+ * them, and the latest-wins sequencing of their (async) rebuilds.
+ */
+export declare abstract class SpatialSceneBase {
+    protected readonly ctx: SceneContext;
+    protected readonly session: SpatialSession;
+    protected readonly hover: SpatialHover;
+    /** Latest wins within the scene: a colour fetch is a round-trip, so a fast sequence of
+     *  colour-by changes can resolve out of order, and only the newest may touch the layers. */
+    protected readonly rebuilds: Supersede;
+    private sub;
+    protected constructor(ctx: SceneContext, session: SpatialSession, is3d: boolean);
+    /** Rebuild on every dataset, view, selection or colormap change. */
+    protected subscribeSpatial(): void;
+    /** (Re)build the scene's layers for the current dataset + view state. */
+    protected abstract rebuild(dataset: SpatialDataset | null, view: SpatialViewState, selection?: SpatialSelectionMask): Promise<void>;
+    /** Run after each rebuild is started (the 2D tile layers refresh here). */
+    protected afterChange(): void;
+    /** The observation drawn under a client position, or -1 (see `SpatialHoverHost.pick`). */
+    protected abstract pickObservation(clientX: number, clientY: number, slackPx: number): number;
+    protected hoverTiles(): NapariSpatialTileLayers | null;
+    /** Stop following the data, drop the hover, and make every rebuild in flight stale. */
+    protected disposeSpatial(): void;
+}