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

package/lib/implementations/napari-js/napari-loading-state.d.ts

@@ -0,0 +1,30 @@
+/** What the service itself counts on the badge; the spatial tile layers report their own names. */
+export type LoadingSource = 'Image' | 'Observations';
+/**
+ * "x reloading…" at the bottom of the canvas, aggregated over everything that loads into one
+ * scene: image tiles (the tile client), observation colourings (the spatial scenes) and the
+ * spatial tile layers' own loads (which report a list of layer names).
+ *
+ * Each load is a {@link begin} that hands back its own `end`. {@link reset} starts a new scene:
+ * the counts are dropped, and an `end` from a load that began before it is a no-op, so a load
+ * that settles after a re-plot can neither un-count the new scene's work nor drive a count below
+ * zero (which hid the next scene's "Observations reloading…" until a second load overlapped it).
+ */
+export declare class LoadingBadgeState {
+    private host;
+    private badge;
+    private readonly counts;
+    private tileLayers;
+    private generation;
+    /** The element the badge is drawn into (the plot host); set per plot. */
+    attach(host: HTMLElement): void;
+    /** One load of `source` started; call the returned function once it settles. */
+    begin(source: LoadingSource): () => void;
+    /** The spatial tile layers still loading (their own names, in their order). */
+    setTileLayers(layers: readonly string[]): void;
+    /** The text the badge has set (shown, or about to be once the show delay passes). */
+    get text(): string;
+    /** A new scene: forget every count and remove the badge. */
+    reset(): void;
+    private show;
+}

package/lib/implementations/napari-js/napari-region-overlay.d.ts

@@ -1,16 +1,29 @@
 import { IRegionOverlay, RegionToolMode } from '../../contracts/region-overlay.contract';
 import { RegionStore } from '../../store/region-store.service';
+import type { Affine } from '../../region-overlay/svg-region-renderer';
 /**
  * The slice of the napari Viewer the overlay needs (coord transforms + control gating).
  *
+ * COORDINATE SPACES: `canvasToWorld` takes CLIENT pixels (viewport coordinates, as a pointer
+ * event's `clientX/Y`), exactly as napari-js `Viewer.canvasToWorld` does. `canvasTransform` is
+ * the camera's world → CANVAS-LOCAL CSS-pixel affine, napari-js `Viewer.canvasTransform`, which
+ * reads no layout: drawing and following the camera use it, so a camera frame costs one
+ * `matrix(...)` and no `getBoundingClientRect()` (review NAPARI-BOUNDARY-10). The svg covers the
+ * plot host and the canvas is the host's in-flow child at its top-left, so canvas-local and
+ * svg-local pixels are the same; a pointer's client pixels are mapped into the svg by the
+ * overlay itself.
+ *
  * Exported because the 3D spatial mode supplies a SCREEN-SPACE implementation of it: there the
  * drawn shape is a lasso in canvas pixels, not a rectangle in image space, so "world" is the
- * canvas itself and both transforms collapse to identity. That lets the 3D view reuse this whole
- * overlay — every tool, the handles, the store round-trip — with no 3D-specific drawing code.
+ * canvas itself — `canvasToWorld` is the client → canvas offset and `canvasTransform` the
+ * identity. That lets the 3D view reuse this whole overlay — every tool, the handles, the store
+ * round-trip — with no 3D-specific drawing code.
  */
 export interface OverlayViewer {
+    /** Client px → world. */
     canvasToWorld(clientX: number, clientY: number): [number, number];
-    worldToCanvas(worldX: number, worldY: number): [number, number];
+    /** World → canvas-local (= svg-local) CSS px, as an SVG affine `[a, b, c, d, e, f]`. */
+    canvasTransform(): Affine;
     setControlsEnabled(enabled: boolean): void;
     readonly camera: {
         readonly changed: {
@@ -20,22 +33,31 @@ export interface OverlayViewer {
 }
 /**
  * SVG region overlay for the napari-js WebGPU image view (jit-ui#102), mirroring the OSD backend's
- * {@link OsdRegionOverlay} but driven by napari's `canvasToWorld`/`worldToCanvas` transforms.
+ * {@link OsdRegionOverlay} but driven by napari's `canvasToWorld`/`canvasTransform` transforms
+ * (see {@link OverlayViewer} for their coordinate spaces).
  * Vector shapes are drawn in an absolutely-positioned `<svg>` over the canvas (no need to push
- * them through WebGPU). It writes completed shapes to the shared {@link RegionStore} (so save /
- * undo / export work identically to OSD) and re-renders from the store on every camera move,
- * region change, and selection change.
+ * them through WebGPU) by {@link NapariRegionSvgRenderer} over the shared `SvgRegionRenderer`:
+ * in world coordinates inside one transformed group, rebuilt on a region or selection change,
+ * while a camera move only rewrites the transform (napari-js's `canvasTransform`, the camera
+ * centre/zoom) and the few screen-space handles and labels. This class is
+ * the gesture controller: pointer handlers, the tool mode, and the edit/draft/marquee state.
+ * It writes completed shapes to the shared {@link RegionStore} (so save / undo / export work
+ * identically to OSD).
  *
  * Supports (jit-ui#102): rectangle / polygon / freehand path drawing, click-select and rubber-band
  * marquee select, pan/zoom gating via `setControlsEnabled`, body move, vertex move/add/delete,
- * bezier handle editing, and donut holes (including hole vertex + hole-bezier-handle editing) —
- * full parity with {@link OsdRegionOverlay}.
+ * bezier handle editing, and donut holes (including hole vertex + hole-bezier-handle editing).
+ * Hit-testing shares `region-overlay/region-geometry` with the OSD overlay, so both follow
+ * the same rules (multi-part regions, holes, open polylines, handle-less bezier curves).
  */
 export declare class NapariRegionOverlay implements IRegionOverlay {
     private readonly host;
     private readonly viewer;
     private readonly store;
     private readonly svg;
+    private readonly renderer;
+    /** Client ↔ svg-local ↔ world conversions, with the svg origin read once per gesture/redraw. */
+    private readonly projection;
     private readonly subs;
     private readonly disconnectCamera;
     private mode;
@@ -44,8 +66,6 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     private draftRect;
     /** In-progress rubber-band selection marquee (select mode), image-space. */
     private marquee;
-    /** Dedicated marquee rect element, updated directly during the drag (no full region redraw). */
-    private marqueeEl;
     private draftPath;
     private drawing;
     private regionsVisible;
@@ -65,88 +85,60 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     setMode(mode: RegionToolMode): void;
     setSelectedBezier(bezier: boolean): void;
     /**
-     * How finely a drawn vertex may be placed, in world units.
-     *
-     * One by default, because for an image the world IS pixels and a region should align to
-     * them. A dataset whose coordinates are not pixels sets it finer — seqFISH's whole
-     * sample spans about 5 x 7 units, where whole-unit vertices leave roughly six by eight
-     * placeable positions and no ROI can be drawn at all.
+     * How finely a drawn vertex may be placed, in world units: one (an image's pixels) by
+     * default, finer for a dataset whose coordinates are not pixels (see OverlayProjection).
      */
-    private worldQuantum;
     setWorldQuantum(quantum: number): void;
     destroy(): void;
-    /** Pointer client coords → world coords, snapped to {@link worldQuantum}. */
-    private toImage;
-    /**
-     * World units spanned by one screen pixel, measured through the viewer's own transform.
-     *
-     * Read from the transform rather than from the camera, so it holds for both the 2D and
-     * the 3D screen-space adapters without either having to expose a zoom. Falls back to 1
-     * if the transform gives nothing usable, which keeps the established pixel behaviour
-     * rather than collapsing the threshold to zero and recording a point per event.
-     */
-    private worldPerCanvasPixel;
-    /** Image coords → SVG-local px (the svg overlays the canvas at the same client rect). */
-    private toLocal;
     private readonly onPointerDown;
+    private pointerDown;
     private readonly onPointerMove;
     private readonly onPointerUp;
+    /**
+     * The pointer gesture ended without a pointerup (the browser cancelled it, or capture was
+     * lost): end it without committing. Also fires after every normal release, when nothing
+     * is live any more.
+     */
+    private readonly onPointerCancel;
+    /**
+     * End whatever pointer gesture is live without committing it: close the store batch a drag
+     * opened (so later edits are emitted again) and forget the drag (so a bare hover no longer
+     * moves the region), and drop the marquee and a rectangle/freehand draft. A click-placed
+     * polygon is not a pointer gesture and survives.
+     */
+    private endGesture;
     /** Click-to-place polygon: add a vertex, or close when clicking near the first one. */
     private handlePolygonClick;
     private readonly onDblClick;
     /** The currently-selected region (single selection), or null. */
     private selectedRegion;
-    /** Screen distance (px) between a client point and an image coord. */
-    private screenDist;
     /**
      * Start a select/move interaction: grab a handle (rectangle corner) or vertex of the already-
      * selected region first; otherwise select the topmost region under the cursor and drag its body.
      */
     private beginManipulation;
-    /** Create/update the marquee rect element directly (avoids a full region redraw per move). */
+    /** Show the marquee where it is now (only the marquee element: no full region redraw). */
     private updateMarqueeEl;
-    /** Remove the marquee element from the SVG. */
-    private clearMarqueeEl;
-    /** Test whether a client point grabs a rectangle corner or a polygon vertex of `region`. */
-    private hitHandle;
-    /** Apply the live drag for the active manipulation (image coords `ix,iy`). */
-    private applyManipulation;
-    /** addpoint mode: insert a vertex on the selected polygon's nearest edge at the click. */
+    /** addpoint mode: insert a vertex at the click on the selected polygon's nearest edge
+     *  (exterior or a hole ring). */
     private handleAddPoint;
-    /** deletepoint mode: remove the selected polygon's vertex nearest the click. */
+    /** deletepoint mode: remove the selected polygon's vertex nearest the click (exterior or a
+     *  hole ring). */
     private handleDeletePoint;
-    /** Distance from point (px,py) to segment (ax,ay)-(bx,by), in image units. */
-    private pointSegDist;
-    /** Finalize a rubber-band marquee: select every region whose bounding box it overlaps (a tiny
-     *  marquee is treated as a click on empty space → clear the selection). */
+    /** Finalize a rubber-band marquee: select every region whose bounding box it overlaps (a
+     *  marquee under {@link MIN_MARQUEE_PX} is a click on empty space → clear the selection). */
     private finishMarquee;
-    /** A region's bounding box in image coords (rectangle, polygon, or multipolygon), or null. */
-    private regionBBox;
     private commitRectangle;
     private commitPolygon;
-    private hitTest;
     /** Show or hide the drawn regions. A region being drawn stays visible either way. */
     setRegionsVisible(visible: boolean): void;
+    /** Follow a camera move: one transform attribute plus the screen-space elements. */
+    private updateCamera;
+    /**
+     * Rebuild every element from the store: the regions in world coordinates (one transformed
+     * group), their labels, and the overlay. Reads no layout: the camera affine is the viewer's.
+     */
     redraw(): void;
-    /** Draw a region's classification label at its top-left, when labels are enabled (matches OSD). */
-    private drawLabel;
-    /** Draw grab handles for the selected region: rectangle corners or polygon vertices. */
-    private drawHandles;
-    /** Draw one bezier control point (anchor + handle offset) as a small circle connected to its
-     *  anchor by a tangent line. `handle` is the [dx,dy] offset from the anchor in image space. */
-    private drawBezierHandle;
-    private buildRegionEl;
-    /** Path data for a polygon: the exterior ring (bezier or straight) plus any holes (bezier when
-     *  the donut carries hole handles, else straight) as sub-paths — even-odd fill cuts them out. */
-    private polygonPathData;
-    /** SVG path data for a straight ring/polyline in image coords (closed appends `Z`). */
-    private straightPath;
-    /** SVG cubic-bezier path data for any ring (exterior or hole): anchors joined by cubic segments
-     *  whose control points are `anchor + handleOut` (leaving) and `nextAnchor + handleIn` (arriving),
-     *  in image space. Used for both the exterior and (donut) hole rings. */
-    private ringBezierPath;
-    private style;
-    /** Draw the in-progress rectangle / path preview. */
-    private drawDraft;
-    private styleDraft;
+    /** Rebuild the screen-space overlay only: the selected regions' handles and the draft. */
+    private renderOverlay;
 }

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

@@ -0,0 +1,93 @@
+import type { Viewer } from 'napari-js';
+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;
+    /** 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. */
+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;
+}

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;
+}