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

package/lib/implementations/napari-js/napari-visualizer.service.d.ts

@@ -1,6 +1,9 @@
 import { Observable } from 'rxjs';
 import { Image } from 'image-js';
 import { IImageInfo } from '../../contracts/image.contract';
+import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import { SpatialObservations } from '../../contracts/spatial-dataset.contract';
+import { SpatialSelectionStore } from '../../store/spatial-selection.service';
 import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
 import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from '../../contracts/visualizer.contract';
 import { ViewerCapabilities } from '../../contracts/capabilities.contract';
@@ -30,20 +33,6 @@ interface NapariLoaded {
      *  handle's `filename` doesn't match the requested image (guards against stale clicks). */
     filename: string;
 }
-/**
- * A WebGPU image backend built on the published `napari-js` library — the POC engine for
- * jit-ui#102 (a browser-based napari shipped as a JS library, swapping image plotting with
- * OpenSeadragon and 3D slicing/isosurfaces with Plotly).
- *
- * Render strategy: rather than re-implement the server's tile/pyramid protocol (which OSD
- * already handles), this backend renders the **complete per-slice image URLs the app already
- * produces** (`IImageInfo.urls`) — `urls[z]` for the 2D image, and the full `urls` stack
- * assembled into a downsampled volume for the 3D types. Region state and display options
- * delegate to the shared {@link RegionStore} / {@link VisualizerStore}, exactly as OSD does.
- *
- * Follow-ups (jit-ui#102): native-resolution pyramidal tiling, on-canvas tools, region
- * overlay rendering, per-channel histograms, TIFF export.
- */
 export declare class NapariVisualizerService extends BaseStoreVisualizer implements IVisualizer {
     private readonly tiles;
     private readonly wandTool;
@@ -55,6 +44,8 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private readonly cellSegmentTool;
     private readonly cellSegmenter;
     private readonly simpleStack;
+    private readonly spatialData;
+    private readonly selectionStore;
     readonly capabilities: ViewerCapabilities;
     private readonly api;
     private viewer;
@@ -90,6 +81,97 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private scatterRegionSub;
     /** napari-js 3D scatter (voxel point cloud). */
     private scatter3dLayer;
+    /** Spatial-omics observation markers + the dataset/view subscription driving them. */
+    private spatialPoints;
+    /** The 3D point cloud. One layer: selection is a per-point alpha on it, not a second. */
+    private spatialPoints3d;
+    private spatialLayerKey3d;
+    /** Interleaved x,y,z, cached so a colour change does not re-walk 3.7M observations. */
+    private spatialPositions3d;
+    /** Identity of the scalars currently uploaded — see {@link rebuildSpatialPoints3d}. */
+    private spatialScalarKey3d;
+    /** The anatomical volume the cloud sits inside, when the dataset has one. */
+    private spatialVolume;
+    private spatialVolumeKey;
+    /** 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;
+    /** Selection identity, as a number the density key can carry. */
+    private lastSelectionSeen;
+    private selectionRevision;
+    /** The gene map: its layer, the field it was estimated from, and the inputs each
+     *  was built for — the field is the expensive half and survives a recolour. */
+    private geneMapLayer;
+    private geneMapKey;
+    private geneMapField;
+    private geneMapFieldKey;
+    /** The 3D gene map: its volume layer, the field behind it, and the inputs each
+     *  was built for — same two clocks as the 2D map. */
+    private geneMapVolumeLayer;
+    private geneMapVolumeKey;
+    private geneMapVolumeField;
+    private geneMapVolumeFieldKey;
+    /** Offset applied to observation coordinates to sit them in the volume's box. */
+    private spatialOrigin3d;
+    /** Cursor tooltip for the spatial views, and everything it needs: what the
+     *  cloud is coloured by, and where each drawn observation is. */
+    private spatialTooltip;
+    private hoverSource;
+    private hoverSourceKey;
+    /** Sequences the async resolutions. The KEY is only committed once one lands,
+     *  so a superseded fetch cannot leave the cache claiming to hold a source it
+     *  never stored. */
+    private hoverSourceToken;
+    /** Drawn observations' positions for hit-testing, indexed BY OBSERVATION with
+     *  NaN for anything not drawn. Screen pixels in 3D (the camera moves them, so
+     *  they are rebuilt when it does) and WORLD units in 2D (where the camera only
+     *  scales, so the pointer is converted instead of 374k points). */
+    private hoverPositions;
+    private hoverPositionsRev;
+    /**
+     * Screen-space bucket index over the 3D projection, built on the first hover after the
+     * scene moved rather than when it moves.
+     *
+     * Lazily, and that is the whole design: an orbit drag changes the camera every frame, so
+     * building eagerly would spend tens of milliseconds a frame indexing for picks nobody is
+     * making. Deferred, it is built once when the drag stops and the pointer next moves —
+     * measured upstream at 3.7M points, that turns a 12.6 ms scan per pointermove into
+     * 0.066 ms.
+     */
+    private hoverIndex;
+    /** Bumped whenever the cached positions go stale: a marker rebuild, or — in 3D
+     *  only, where the projection depends on it — a camera move. */
+    private spatialSceneRev;
+    private hoverPointer;
+    private hoverFrame;
+    private hoverOff;
+    /** Observation indices the cached 3D 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 spatialDrawn3d;
+    /** Reused projection buffers — see {@link getSpatialScreenProjection}. */
+    private spatialProjection3d;
+    /** Per-observation depth from the last projection, for the depth-aware hover pick. */
+    private spatialDepths3d;
+    /** The (viewer, dataset) whose 3D scene has already had its opening framing. */
+    /** Whose 2D observations the camera has been framed on — see {@link frameSpatialPointsOnce}. */
+    private spatial2dFramed;
+    /** Dataset the 3D scale bar was built for. */
+    private spatialScaleBarKey;
+    private spatialSub;
+    /** Latest (dataset, view, selection) the spatial subscription saw, so a slice
+     *  change can rebuild the markers for the new plane. */
+    private spatialLatest;
+    /** Which dataset the current marker layer was built for, so a display-only
+     *  change (size, colour, opacity, selection) can update it in place. */
+    private spatialLayerKey;
+    /** Monotonic guard for the async colour rebuild: fetching a gene vector is a
+     *  round-trip, so a fast sequence of colour-by changes can resolve out of
+     *  order. Only the newest rebuild is allowed to touch the layer. */
+    private spatialRebuildToken;
     /** Monotonic load generation. Bumped by {@link reset} and {@link cancelLoading}; the frame-loading
      *  loops (volume assembly, surface preload) capture it and bail when it changes, so a Cancel (or a
      *  new plot) actually stops fetching frames instead of running to completion in the background. */
@@ -168,7 +250,7 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private readonly autoscaleEvent$;
     private readonly intensityProfile$;
     private readonly viewportChange$;
-    constructor(tiles: TileAccessPort, store: VisualizerStore, regionStore: RegionStore, wandTool: WandToolService, brushTool: BrushToolService, eraserTool: VertexEraserToolService, zoomToBoxTool: ZoomToBoxToolService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, simpleStack: SimpleSliceAccessService, config: VizConfig);
+    constructor(tiles: TileAccessPort, store: VisualizerStore, regionStore: RegionStore, wandTool: WandToolService, brushTool: BrushToolService, eraserTool: VertexEraserToolService, zoomToBoxTool: ZoomToBoxToolService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, simpleStack: SimpleSliceAccessService, config: VizConfig, spatialData?: SpatialDataPort | null, selectionStore?: SpatialSelectionStore | null);
     /**
      * Fetch + cache the server pyramid descriptor (`GET /tiles/info`): the REAL per-level tile grid,
      * tile size, channel metadata and physical pixel size. The backend returns 202 while the source
@@ -269,6 +351,15 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
      *  world box (matching the AxesLayer geometry); the scale text reflects the FULL image extent —
      *  physical µm when µm/pixel is known, else pixel (X/Y) / slice (Z) counts. */
     private buildAxesLabels;
+    /**
+     * The image's declared extent in pixels/slices, and its physical spacing per
+     * axis in µm (0 = undeclared, and then that axis reads in pixels).
+     *
+     * One place, because the volume world box and the axis labels have to agree
+     * about what the image's real dimensions are — the sampled grid is decimated and
+     * says nothing about either.
+     */
+    private imageExtent;
     /**
      * Assemble a downsampled uint8 volume (luminance) from the per-slice tile endpoint. Slices are
      * fetched with bounded concurrency (keeps the connection pool full without flooding it on a deep
@@ -286,6 +377,396 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private rebuildScatterPoints;
     /** Region centroids as flat `[x, y, …]` data coords (rectangle / polygon / multipolygon). */
     private regionCentroids;
+    /**
+     * The interaction stack every 2D mode needs: the region overlay (draw/select/edit), the pixel
+     * tools that read back displayed pixels (wand, brush, vertex eraser, zoom-to-box, SAM/cellpose),
+     * and a camera hook that keeps that readback current as the view pans/zooms and tiled levels
+     * load.
+     *
+     * Extracted because forgetting it is invisible: the toolbar gates its region buttons on 2D-vs-3D
+     * rather than on plot type, so a 2D mode that skips this shows every tool and silently does
+     * nothing. That is exactly what happened to the spatial and region-centroid scatter modes.
+     */
+    private install2dInteraction;
+    /** Marker radius (image px) for a dataset that declares none — segmented cells often don't. */
+    private static readonly SPATIAL_FALLBACK_RADIUS;
+    /** 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. */
+    private static readonly SPATIAL_SLICE_MIN_DIAMETER_PX;
+    /** 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. */
+    private static readonly GENE_MAP_MAX_SIDE;
+    /** Kernel σ in field pixels at smoothing 1: wide enough to read between cells,
+     *  tight enough to keep a nucleus-scale structure distinct. */
+    private static readonly GENE_MAP_SIGMA;
+    /** 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. */
+    private static readonly DENSITY_MAX_CLUSTERS;
+    /** Colour for observations when nothing is selected to colour by: visible, neutral, and
+     *  obviously not encoding anything. */
+    /** How much larger a selected marker is drawn, so a small selection is findable inside a
+     *  3.7M-point cloud rather than merely brighter. */
+    private static readonly SPATIAL_SELECTED_SIZE_SCALE;
+    private static readonly SPATIAL_NEUTRAL_COLOR;
+    /**
+     * Mount the SPATIAL_OMICS view: the tissue image with one marker per observation, coloured by
+     * an annotation column or a gene. 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-tool hosts, 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.
+     */
+    private mountSpatialOmics;
+    /**
+     * Region drawing for the 3D cloud.
+     *
+     * Reuses {@link NapariRegionOverlay} verbatim by handing it a SCREEN-SPACE viewer: the drawn
+     * shape is a lasso in canvas pixels, so "world" is the canvas and both transforms are identity
+     * (bar the client→canvas offset). Every existing tool — rectangle, polygon, freehand — therefore
+     * works in 3D with no new drawing code.
+     *
+     * A screen-space shape stops meaning anything the moment the camera moves, so an orbit clears
+     * the drawn regions. The SELECTION it produced is kept: that is the durable artefact, and the
+     * highlighted points stay highlighted from every angle.
+     */
+    private install3dInteraction;
+    /** Movement, in screen pixels, under which a press-release is a CLICK and not a
+     *  drag. An orbit or a pan starts the same way, so the two have to be told
+     *  apart by how far the pointer travelled. */
+    private static readonly CLICK_SLOP_PX;
+    /** Longest press-release still treated as a click. A long press with the mouse
+     *  held still is more likely an interrupted drag than a selection. */
+    private static readonly CLICK_MAX_MS;
+    /** 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. */
+    private static readonly HOVER_RADIUS_PX;
+    /**
+     * Cursor tooltip for the spatial views: hover a marker, read its class.
+     *
+     * 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, so it and
+     * the legend can never say different things.
+     *
+     * Listens on the 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 throttles to one hit-test per animation frame: a pointermove can
+     * fire far more often than that, and each test is a pass over the cloud.
+     */
+    private installSpatialHover;
+    private removeSpatialHover;
+    /** Hit-test the last pointer position and show or hide the tooltip. */
+    private updateHover;
+    /**
+     * 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;
+    /**
+     * Which observation is under the cursor.
+     *
+     * In 3D this defers to napari-js's {@link nearestProjectedIndex} WITH the depths the
+     * projection produced, so the front-most candidate wins. 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, which reads as a wrong tooltip rather than as
+     * a subtlety of picking.
+     *
+     * In 2D the positions are WORLD coordinates on one plane, so there is no depth to break
+     * ties with and the existing nearest-marker rule is the right one.
+     */
+    private pickObservation;
+    /**
+     * Positions to hit-test against, rebuilt only when the scene or camera moved.
+     *
+     * A pass over 3.7M observations is not something to do per pointermove, and the
+     * cloud does not move between frames unless something says it did.
+     */
+    private hoverPositionsFor;
+    /**
+     * The 2D markers' WORLD positions, indexed by observation, NaN for any not on
+     * the displayed plane — the same affine and the same subset the marker layer was
+     * built from, so the tooltip cannot point at a cell that is not drawn.
+     */
+    private hoverWorldPositions;
+    /**
+     * 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.
+     */
+    private resolveHoverSource;
+    /**
+     * Project every observation to canvas pixels under the current 3D camera.
+     *
+     * The projection itself is the renderer's: `viewer.projectPoints` owns the camera, the
+     * viewport in CSS pixels, the perspective divide and the y-flip. This used to be fifteen
+     * lines of column-major matrix arithmetic here, duplicating a second copy in
+     * `napari-axes-labels` — and the two had drifted on what to do with a NaN w.
+     *
+     * 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.
+     *
+     * Null when the 3D cloud is not mounted, so the caller falls back to the 2D affine path.
+     */
+    getSpatialScreenProjection(obs: SpatialObservations): Float32Array | null;
+    /** Rebuild the markers on any dataset or view-state change. */
+    private subscribeSpatial;
+    /** (Re)build the observation marker layer for the current dataset + view state. */
+    private rebuildSpatialPoints;
+    /**
+     * 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;
+    /**
+     * Frame the 2D 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.
+     */
+    /**
+     * 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.
+     */
+    private hideForeignImage;
+    private frameSpatialPointsOnce;
+    /**
+     * 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 {@link 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;
+    /**
+     * The plane a volume-backed dataset is currently showing: its pixel affine, the
+     * observations that fall in it, and the marker floor that grid needs.
+     *
+     * Null for a dataset with a real `imageRef` (its coordinates are already the
+     * image's pixels and every observation belongs to the one section) and for one
+     * with no volume at all — both of which draw exactly as before.
+     */
+    private spatialSlab;
+    /** Per-point colours for the drawn subset. A broadcast tuple stays broadcast —
+     *  it is one colour for every point either way. */
+    private gatherColors;
+    /**
+     * Redraw the observation 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 a different one.
+     *
+     * Uses the latest values the marker subscription saw; a no-op until it has seen
+     * any, in the 3D cloud (no image, no plane), and with no dataset to draw.
+     */
+    private redrawSpatialMarkers;
+    /**
+     * Mount the SPATIAL_OMICS_3D view: observations as a 3D point cloud under the orbit camera.
+     *
+     * Deliberately much thinner than the 2D mount. There is no tissue image to render (a registered
+     * volume like the Allen CCF has no single reference plane), so no scale bar, no readback, and no
+     * 2D interaction stack — the region tools draw in screen space and have no meaning against an
+     * orbiting camera, which is why `Select from ROIs` is hidden in this mode. `addPoints3D` puts
+     * the viewer in 3D and frames the camera on the cloud itself.
+     */
+    private mountSpatialOmics3d;
+    /**
+     * Scale bar for the 3D 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.
+     *
+     * `NapariScaleBar` needs CSS px per world unit, which an orbit camera does not expose, but at
+     * the pivot it is exactly `viewportHeight / (2 * distance * tan(fov / 2))` — the same
+     * relationship `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 installSpatial3dScaleBar;
+    /** Base marker diameter for the 3D cloud, in SCREEN pixels (the layer's unit). */
+    private static readonly SPATIAL_3D_BASE_SIZE;
+    /** (Re)build the 3D point cloud for the current dataset + view state. */
+    private rebuildSpatialPoints3d;
+    /**
+     * 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 ensureGeneMapVolume;
+    /**
+     * 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
+     * {@link 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;
+    /**
+     * Identity of the colour scale a continuous spatial layer will draw with, for a
+     * cache key: the explicit choice, or else the display colormap and its reverse
+     * flag, since that is what {@link spatialContinuousLut} falls back to.
+     *
+     * The gene maps cache their coloured output, so without this in the key a change
+     * of colour scale left the field on screen in the previous colours — the markers
+     * recoloured and the map under them did not.
+     */
+    private continuousColormapKey;
+    /**
+     * 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.
+     */
+    private selectionRev;
+    /**
+     * 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, so "select a region,
+     * check the box" answers which clusters live there. 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 spatialOrigin3d} 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 ensureSpatialVolume;
+    private removeSpatial3dLayers;
+    /** A one-colour colormap, for the "nothing to colour by" state. */
+    private spatialFlatColormap;
+    /**
+     * The per-point scalar + colormap + window that colour the 3D cloud.
+     *
+     * Continuous data is the natural fit: values go straight through the active colormap with the
+     * same percentile window the 2D path uses. Categorical data has to be smuggled through the same
+     * scalar channel — see {@link SPATIAL_3D_MAX_CATEGORIES}. Codes map to LUT blocks, and
+     * `contrastLimits` of `[-0.5, K - 0.5]` puts code `i` at the centre of block `i`, which is what
+     * makes the round-trip exact instead of approximately right.
+     */
+    private spatialScalar3d;
+    /** Category codes → a stepped LUT, exact for up to {@link SPATIAL_3D_MAX_CATEGORIES}. */
+    private encodeSpatial3dCategorical;
+    /** Continuous values → the active colormap over a percentile-clipped window. */
+    private encodeSpatial3dContinuous;
+    /**
+     * 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 spatialFaceColors;
+    /** Continuous values → RGBA through the active colormap and a clipped window. */
+    private encodeSpatialContinuous;
     /**
      * Mount the NAPARI_SCATTER3D 3D scatter: the downsampled voxel grid as a 3D point cloud colored
      * by intensity (napari-js analog of Plotly's voxel scatter3d). Assembles a coarse volume, then
@@ -451,7 +932,7 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
      *  only (omitted when all are visible → server default). Mirrors the OSD backend. */
     exportData(): Promise<void>;
     unsubscribe(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NapariVisualizerService, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, null, null]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NapariVisualizerService, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, null, null, { optional: true; }, null]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NapariVisualizerService>;
 }
 export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Wheel-zoom sensitivity for the napari-js backend, as `exp(-delta * speed)` per normalized,
+ * clamped wheel-delta unit.
+ *
+ * Derived from {@link OSD_ZOOM_PER_SCROLL} rather than written as its own number: the two backends
+ * draw the same images, and a wheel that zooms further under one renderer than the other is a
+ * difference the user has no way to explain.
+ *
+ * napari-js clamps a single event's delta before applying the speed — mouse notches and trackpad
+ * momentum ticks both exceed the clamp, so the clamped step IS the per-notch step — which makes
+ * matching the two a matter of solving `exp(WHEEL_DELTA_CLAMP * speed) = OSD_ZOOM_PER_SCROLL`.
+ * The clamp is imported rather than copied: it belongs to napari-js, and a local literal would go
+ * silently stale the day that library retuned it.
+ */
+export declare const NAPARI_WHEEL_ZOOM_SPEED: number;

package/lib/implementations/osd/osd-zoom.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Wheel-zoom step for the OpenSeadragon backend.
+ *
+ * Applied per scroll EVENT, not per unit of delta — which is what OpenSeadragon's own
+ * `zoomPerScroll` does, and what the region overlay does when an active tool has taken the wheel
+ * over. That makes the step compound with the number of events a device sends: a mouse notch is
+ * one event, but a trackpad swipe is a burst of them, so a step that feels right for a mouse runs
+ * away under a trackpad.
+ *
+ * At the previous 1.1 (OpenSeadragon's default is 1.2) an image doubled in 7 notches, against the
+ * ~24 the napari-js backend took for the same picture — the same gesture zoomed several times
+ * further depending only on which renderer was active. 1.03 puts the two within a whisker of each
+ * other, so the wheel feels the same whichever backend is drawing.
+ *
+ * Shared because the viewer option and the overlay's handler MUST agree: whether the wheel is
+ * handled by OpenSeadragon or by the overlay depends on whether a region tool is active, and the
+ * zoom visibly changing pace when a tool is picked up is the bug this constant prevents.
+ */
+export declare const OSD_ZOOM_PER_SCROLL = 1.03;