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

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

@@ -0,0 +1,126 @@
+import type { RegionMesh3D } from './napari-volume-region-meshes';
+import type { Viewer } from 'napari-js';
+import type { VolumeFrame } from './napari-volume-region-meshes';
+import type { PlaneAxis, SlicePlanes } from './napari-volume-slice-planes';
+import { IImageInfo } from '../../contracts/image.contract';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { IIsosurfaceControls, ISurface3dControls } from '../../contracts/visualizer.contract';
+import { SpatialObservations } from '../../contracts/spatial-dataset.contract';
+import { VisualizerStore } from '../../store/visualizer-store.service';
+import { RegionStore } from '../../store/region-store.service';
+import { NapariTileClient } from './napari-tile-client';
+import { NapariDisplayState } from './napari-display-state';
+import { LoadingBadgeState } from './napari-loading-state';
+import { NapariToolBridge } from './napari-tool-bridge';
+/**
+ * What one `plot()` mounts into the viewer (review Appendix B): the 2D image (alone, under the
+ * region-centroid scatter, or under the spatial markers), a volume, a surface, a 3D scatter or the
+ * spatial 3D cloud. The service picks one per plot type and talks to it through this interface
+ * instead of asking which layer handle happens to be non-null; a scene owns every layer, key,
+ * subscription and listener it creates, and {@link dispose} drops them all — so a re-plot can no
+ * longer inherit a stale "already built" key from the previous one (NAPARI-SVC-1, -8).
+ */
+export interface NapariScene {
+    /** Build the scene into the viewer. Resolves once the first frame's data is in. */
+    mount(): Promise<void>;
+    /** The stack slider moved to `z` (already recorded as the image's slice). */
+    setZ(z: number): void;
+    /** The histogram pane's distribution for `channel`, or null when there is none (yet). */
+    histogram(channel: number, bins: number): IHistogram | null;
+    /** The isosurface threshold controls (volume scenes only). */
+    isoControls?(): IIsosurfaceControls | null;
+    /** The 3D camera/axes/wireframe controls (3D scenes only). */
+    surface3dControls?(): ISurface3dControls | null;
+    /** Bilinear vs nearest-neighbour image sampling changed (2D image scenes). */
+    setImageSmoothing?(enabled: boolean): void;
+    /** The overview navigator was shown or hidden (2D image scenes). */
+    setNavigatorVisible?(visible: boolean): void;
+    /** Observations projected to canvas pixels (the spatial 3D cloud), or null. */
+    screenProjection?(obs: SpatialObservations): Float32Array | null;
+    /** Show these region reconstructions in the 3D view (volume scenes only). */
+    setRegionMeshes?(meshes: readonly RegionMesh3D[]): void;
+    /** Highlight the reconstructions of these keys (none: all as usual). */
+    setRegionHighlight?(keys: readonly string[]): void;
+    /** Hide the reconstructions of these keys. */
+    setRegionHidden?(keys: readonly string[]): void;
+    /**
+     * Draw the region reconstructions through the volume (it hides none of them) rather than hidden
+     * where it is in front of them (see VolumeScene.setRegionsThroughVolume).
+     */
+    setRegionsThroughVolume?(through: boolean): void;
+    /** Show the planes of the sections beside the 3D view (volume scenes only). */
+    setSlicePlanes?(planes: SlicePlanes): void;
+    /** The assembled volume the sections are cut from (volume scenes only). */
+    volumeVoxels?(): VolumeVoxelsOnScreen | null;
+    /** Image px per voxel of the assembled volume, in-plane (volume scenes only). */
+    voxelStep?(): number | null;
+    /** Remove everything the scene added; called before the viewer is disposed. */
+    dispose(): void;
+}
+/** Viewer settings that outlive a scene: a re-plot keeps them. */
+export interface NapariSettings {
+    /** Decimate factor for the 3D types (1 = Full, 2 = ½, 4 = ¼ default, 8 = ⅛). */
+    resolutionScale: number;
+    /** Whether the 2D overview navigator is shown (the same host setting OSD's navigator honours). */
+    navigatorVisible: boolean;
+    /** Image smoothing (bilinear) vs nearest-neighbour (crisp pixels, the default). */
+    imageSmoothing: boolean;
+    /** The 3D axes gizmo's on/off choice. */
+    axesVisible: boolean;
+    /** The surface's wireframe choice. */
+    surfaceWireframe: boolean;
+    /** The volume's user Z-height factor (1 = the volume's natural proportions). */
+    volumeZScale: number;
+}
+/** The stack-loading flag and progress the host shows while frames load. */
+export interface StackProgress {
+    loading(on: boolean): void;
+    progress(percent: number): void;
+}
+/** Everything a scene is built from: the viewer and its DOM, the service's collaborators, and the
+ *  service state a scene reads live. */
+/** A volume as assembled for display (voxels per channel, key 0 the grayscale one) and its frame. */
+export interface VolumeVoxelsOnScreen {
+    width: number;
+    height: number;
+    depth: number;
+    channels: ReadonlyMap<number, Uint8Array>;
+    multichannel: boolean;
+    frame: VolumeFrame;
+}
+export interface SceneContext {
+    readonly viewer: Viewer;
+    readonly host: HTMLElement;
+    readonly canvas: HTMLCanvasElement;
+    /** The scene's lifetime: aborted when the service resets into the next scene. */
+    readonly signal: AbortSignal;
+    /** Frame loading (volume assembly, surface preload): aborted by a reset AND by
+     *  `cancelLoading()`, which renews it — so read it when a load starts. */
+    loading(): AbortSignal;
+    /** The image on screen and its current slice, as `load()`/`setZIndex()` recorded them. */
+    info(): IImageInfo | undefined;
+    z(): number;
+    readonly tiles: NapariTileClient;
+    readonly display: NapariDisplayState;
+    readonly badge: LoadingBadgeState;
+    readonly tools: NapariToolBridge;
+    readonly store: VisualizerStore;
+    readonly regionStore: RegionStore;
+    readonly settings: NapariSettings;
+    readonly stack: StackProgress;
+    /** The image's full-resolution size as the scene drew it — read by the readback, the camera
+     *  fit and `getTrueImageSize()`; it outlives the scene. */
+    imageSize(): {
+        width: number;
+        height: number;
+    };
+    setImageSize(width: number, height: number): void;
+    /** Fit the 2D camera to the image on the next frame. */
+    fitCameraSoon(): void;
+    outsideZone<T>(fn: () => T): T;
+    inZone<T>(fn: () => T): T;
+    /** A region reconstruction was clicked (its key), or the volume beside them (null). */
+    regionMeshPicked(key: string | null, additive: boolean): void;
+    /** A section's plane dragged in the volume to `value` along its axis. */
+    slicePlaneMoved(axis: PlaneAxis, value: number): void;
+}

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

@@ -0,0 +1,163 @@
+import type { ImageLayer, Viewer } from 'napari-js';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import { SpatialViewState } from '../../contracts/display-types';
+import { SpatialSelectionMask } from '../../spatial/spatial-selection';
+import { NapariSpatialTileLayers } from './napari-spatial-tiles';
+import { Image2dScene } from './napari-image-2d-scene';
+import { SpatialSceneBase, SpatialSession, SpatialTileOwner } from './napari-spatial-scene';
+import type { NapariScene, SceneContext } from './napari-scene';
+/**
+ * SPATIAL_OMICS (review Appendix B, cluster J): the tissue image (an {@link Image2dScene}) with one
+ * marker per observation, coloured by an annotation column or a gene, the gene map under the
+ * cells, and the level-of-detail tile layers (outlines, transcripts, density) over them. The
+ * markers rebuild whenever the dataset or the view state changes, so switching the colour-by
+ * column does not remount the scene.
+ *
+ * Sets up the full 2D interaction stack — region overlay, pixel tools, readback currency — exactly
+ * as the plain image view does. That is NOT optional here: this mode's selection is driven by
+ * drawn ROIs, so without the overlay there is no way to make a selection at all.
+ */
+export declare class Spatial2dScene extends SpatialSceneBase implements NapariScene, SpatialTileOwner {
+    readonly image: Image2dScene;
+    /** The observation markers, and which dataset/plane they were built for — so a display-only
+     *  change (size, colour, opacity, selection) can update them in place. */
+    private points;
+    private layerKey;
+    /** The observation each marker is, in draw order; null when every observation is drawn. */
+    private drawn;
+    /** The gene map's layer and the inputs it was coloured for (its field is cached in the session,
+     *  on a clock of its own). */
+    geneMapLayer: ImageLayer | null;
+    private geneMapKey;
+    /** The dataset the camera has been framed on — see {@link frameOnce}. */
+    private framed;
+    /** The gene-map estimate in flight (off the main thread past the worker threshold,
+     *  SPATIAL-19): a new field key supersedes — and aborts — it; a rebuild that leaves the key
+     *  alone lets it finish. */
+    private readonly geneMapLoads;
+    /** `noImage`: an image-less dataset opened before any image — the observations alone. */
+    constructor(ctx: SceneContext, session: SpatialSession, noImage?: boolean);
+    mount(): Promise<void>;
+    setZ(z: number): void;
+    histogram(channel: number, bins: number): IHistogram | null;
+    setImageSmoothing(enabled: boolean): void;
+    setNavigatorVisible(visible: boolean): void;
+    dispose(): void;
+    canvasSize(): [number, number];
+    polygonsShownChanged(): void;
+    protected afterChange(): void;
+    protected hoverTiles(): NapariSpatialTileLayers | null;
+    /**
+     * The observation under a client position: napari-js's pick on the marker layer itself (a grid
+     * over its positions, rebuilt only when they change), so the tooltip cannot name a cell that is
+     * not drawn, then the drawn index mapped back to the observation.
+     *
+     * A marker is hit anywhere on its drawn disc, or within `slackPx` screen pixels of its centre
+     * when it is smaller than that (a 1.5 px dot still has to be hoverable), and of several hits the
+     * NEAREST centre wins (an exact tie goes to the one drawn on top). Not napari's `'topmost'`: the
+     * slack is wider than most markers, and over a dense field of small ones "the last drawn within
+     * 10 px" names a neighbour rather than the cell under the cursor.
+     */
+    protected pickObservation(clientX: number, clientY: number, slackPx: number): number;
+    /**
+     * Whether the markers are drawn: when the user wants them, and not while cell outlines are on
+     * screen — then a cell IS its outline, and a circle on top of it is noise. Zoomed out past the
+     * outline threshold, the circles stand in for the cells.
+     */
+    private pointsVisible;
+    /**
+     * Redraw the markers over a freshly rendered image. Two reasons, both invisible from the
+     * spatial store — which is why a scrub or a re-render never reached the markers on its own:
+     *  - the image render CLEARS the layer list, taking the markers with it;
+     *  - over a volume-backed dataset the displayed plane decides which observations belong on
+     *    screen at all, so the cells have to move with the section rather than hang over another.
+     */
+    private redrawMarkers;
+    /** (Re)build the observation marker layer for the current dataset + view state. */
+    protected rebuild(dataset: SpatialDataset | null, view: SpatialViewState, selection?: SpatialSelectionMask): Promise<void>;
+    /** Nothing to draw: drop the markers and the gene map. */
+    private removeLayers;
+    /**
+     * Draw the observation markers over the image (and the gene map): restyled in place for a
+     * display-only change, else a new layer.
+     */
+    private drawMarkers;
+    /**
+     * Tell the region overlay how finely a drawn vertex may be placed.
+     *
+     * Region geometry is stored in whole world units, which is right when the world IS
+     * pixels — a region should align to them. It is wrong for a dataset that registers onto
+     * no image: seqFISH's observations span about 5 x 7 units in total, so whole-unit
+     * vertices leave roughly six by eight placeable positions across the entire sample and
+     * an ROI cannot be drawn at any zoom. Nothing errors; the tool just cannot express the
+     * shape.
+     *
+     * Keyed on whether the dataset brings PIXELS rather than on the extent, because the
+     * extent cannot tell the two apart — 2,000 units is a small slide or a large section
+     * depending only on what the units are, and only the dataset knows.
+     */
+    private setRegionGridFor;
+    /**
+     * Hide the image layer for a dataset that brings no image of its own.
+     *
+     * The host's viewer keeps whatever image was last loaded, and for a dataset that
+     * registers onto none that picture belongs to something else entirely — the example's
+     * default slide, say. It is not merely irrelevant: the two live in different coordinate
+     * spaces (image pixels against the embedding's own units), so the leftover is magnified
+     * roughly a hundredfold. At the fitted zoom the camera sits inside its corner, where it
+     * reads as blank background, and it appears only once you zoom out far enough to find
+     * it — which is exactly how it gets noticed.
+     *
+     * Hidden rather than removed, and hidden HERE rather than by clearing the host's image
+     * state: that state drives the whole render pipeline, including a Plotly backend whose
+     * fields are declared with definite-assignment assertions, so emptying it throws from
+     * whichever field the next path happens to read. This touches one layer's visibility
+     * and nothing else.
+     */
+    hideForeignImage(viewer: Pick<Viewer, 'layers' | 'requestRender'>, datasetHasPixels: boolean): void;
+    /**
+     * Frame the camera on the observations, for a dataset that brings no image.
+     *
+     * The 2D camera is normally fitted to the IMAGE, because the observations are in that
+     * image's pixel space and framing the image frames them too. A dataset with no
+     * reference image has coordinates in its own units instead — seqFISH's span about
+     * 5x7 — so the image framing left over from whatever was on screen before puts the
+     * whole cloud offscreen: measured at 9.7 x 13.4 PIXELS, centred 256px from where the
+     * camera was looking. The points are all there and drawn; they are a speck. Which
+     * looks exactly like the dataset having failed to load.
+     *
+     * Once per dataset, as napari-js's `fit3d: 'once'` does for the cloud: re-colouring,
+     * slicing or picking a gene re-adds this layer, and re-framing on those would move
+     * the camera under the user — the camera tools and the canvas drag are meant to be
+     * the only things that do.
+     */
+    private frameOnce;
+    /**
+     * The **gene map**: the active gene's expression as a continuous field drawn under
+     * the cells.
+     *
+     * A scatter coloured by a gene says which cells express it; it cannot say where,
+     * because the eye will not integrate thousands of dots into a territory. The field
+     * is a kernel-weighted MEAN per cell (see `spatial-expression.ts`), so a dense
+     * region does not glow merely for being dense, and it is transparent wherever no
+     * cell was measured — an unsampled gap must not read as "not expressed".
+     *
+     * It shares the points' LUT, percentile window and log flag, so the layer under
+     * the cells and the cells themselves cannot disagree about what a colour means.
+     *
+     * Estimated on the DISPLAYED image's pixel grid, coarsened so the long side is at
+     * most `GENE_MAP_MAX_SIDE`: a smooth field gains nothing from a slide's full
+     * resolution. For a volume-backed dataset that grid is the current slice, and only
+     * that plane's observations are included — the same rule the markers follow.
+     */
+    private ensureGeneMap;
+    /**
+     * Per-observation colours for the current view state, or a single flat colour when nothing is
+     * selected to colour by. Categorical columns use the column's own palette; continuous columns
+     * and gene vectors go through the active colormap with a percentile-clipped window.
+     */
+    private faceColors;
+    /** Continuous values → RGBA through the active colormap and a clipped window. */
+    encodeContinuous(values: Float32Array, view: SpatialViewState, muted?: Uint8Array | null): Float32Array;
+}

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