@jax-data-science/sci-image-visualizer 0.16.0 → 0.18.0

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

@@ -39,6 +39,18 @@ export interface NapariScene {
     screenProjection?(obs: SpatialObservations): Float32Array | null;
     /** Show these region reconstructions in the 3D view (volume scenes only). */
     setRegionMeshes?(meshes: readonly RegionMesh3D[]): void;
+    /**
+     * Where the reconstructions' slices are, in the observations' units, when their region set says
+     * (a 3D segmentation's planes); null: they are the plotted stack's slices (spatial 3D only).
+     */
+    setRegionPlanes?(z: readonly number[] | null): void;
+    /**
+     * The plane of those (see {@link setRegionPlanes}) the 2D spatial view shows, over an image of
+     * one plane: its observations and transcripts are the ones drawn (spatial 2D only).
+     */
+    setRegionPlane?(k: number): void;
+    /** Draw these classes of the dataset's region set as individual cells (spatial 3D only). */
+    setRegionCells?(classes: readonly string[] | null): void;
     /** Highlight the reconstructions of these keys (none: all as usual). */
     setRegionHighlight?(keys: readonly string[]): void;
     /** Hide the reconstructions of these keys. */

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

@@ -36,10 +36,27 @@ export declare class Spatial2dScene extends SpatialSceneBase implements NapariSc
      *  SPATIAL-19): a new field key supersedes — and aborts — it; a rebuild that leaves the key
      *  alone lets it finish. */
     private readonly geneMapLoads;
+    /**
+     * The planes of the dataset's region set (its `sliceZ`), set while they slice an image of one
+     * plane, and which of them the slider shows: the observations and transcripts drawn are that
+     * plane's, as a stack's slice shows its own.
+     */
+    private planes;
+    private plane;
+    /** Mounted: its markers are in the scene and follow the plane (set before then, it is kept). */
+    private mounted;
     /** `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;
+    setRegionPlanes(z: readonly number[] | null): void;
+    setRegionPlane(k: number): void;
+    /** The planes and the one shown, while planes slice the image. */
+    private planeView;
+    /** The z band of the plane shown, or null (every depth). */
+    private zBand;
+    /** Another plane (or none): its observations and transcripts are drawn. */
+    private planeChanged;
     histogram(channel: number, bins: number): IHistogram | null;
     setImageSmoothing(enabled: boolean): void;
     setNavigatorVisible(visible: boolean): void;
@@ -61,9 +78,8 @@ export declare class Spatial2dScene extends SpatialSceneBase implements NapariSc
      */
     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.
+     * Whether the markers are drawn: while the user wants them, at every zoom, and not while the
+     * cells are — the observations are shown as their markers or as their cells, one or the other.
      */
     private pointsVisible;
     /**

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

@@ -0,0 +1,141 @@
+import type { Layer, Viewer } from 'napari-js';
+import type { Cells3dStatus } from '../../contracts/display-types';
+import type { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import type { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import { PlanePlacement } from './napari-volume-region-meshes';
+/**
+ * A 3D segmentation's cells in the spatial 3D view, each reconstructed by itself (see
+ * `geometry/cell-meshes`), where the region classes are otherwise one merged surface per class.
+ *
+ * Built to stay out of the way of the UI thread and the GPU:
+ *  - the space is cut into chunks (a grid over the region set's bounds); each chunk is one surface
+ *    layer of its cells, meshed in the cells' own worker, a few hundred cells per call, so the
+ *    work is cancelled between calls when the view moves on (and the region tiles the 2D view
+ *    reads never wait behind it);
+ *  - level of detail by chunk: a coarse mesh everywhere first, then the chunks on screen are meshed
+ *    finer as the camera comes close, within a triangle budget for the whole scene; the region
+ *    set's tiles are read at the level of detail that mesh needs;
+ *  - at most {@link CELLS_3D_MAX_CELLS} cells and {@link CELLS_3D_TRIANGLE_BUDGET} triangles, the
+ *    chunks nearest the centre of the view first (one chunk over either by itself is meshed in
+ *    part), planned again as each chunk's real size is learnt; the status says when cells are left
+ *    out, so the view never claims to show them all;
+ *  - colour and visibility change no geometry: colours are per vertex (each vertex's cell), and a
+ *    hidden cell's triangles are left out of what is drawn.
+ * Builds report on the canvas's loading badge.
+ */
+/** The most cells drawn at once. */
+export declare const CELLS_3D_MAX_CELLS = 20000;
+/** The most triangles every chunk together may have. */
+export declare const CELLS_3D_TRIANGLE_BUDGET = 3000000;
+export interface Cells3dHost {
+    readonly viewer: Viewer;
+    readonly port: SpatialDataPort | null;
+    /** Show the cells loading on the canvas until the returned function is called. */
+    beginTask(label: 'Cells'): () => void;
+    status(status: Cells3dStatus | null): void;
+}
+export type { Cells3dStatus };
+export declare class Spatial3dCells {
+    private readonly host;
+    private dataset;
+    private source;
+    private classes;
+    private hidden;
+    private colors;
+    private visible;
+    /** The selection (null: none): the cells it leaves out fade, keeping their colours. */
+    private selected;
+    private opacity;
+    private placement;
+    private zScale;
+    private chunks;
+    private readonly byLayer;
+    private generation;
+    private timer;
+    private running;
+    private disposed;
+    /** Each surface's geometry as last set: a recolour that leaves it so uploads none again. */
+    private readonly installed;
+    private cameraOff;
+    constructor(host: Cells3dHost);
+    /** The dataset whose region set the cells are read from. */
+    setDataset(dataset: SpatialDataset | null): void;
+    /** The classes drawn as cells (none: the cells are not drawn). */
+    setClasses(classes: ReadonlySet<string> | null): void;
+    /** Classes hidden (the Region Editor's eyes): their cells are left out of what is drawn. */
+    setHiddenClasses(classes: readonly string[]): void;
+    /**
+     * Each observation's colour (RGBA 0..1) and whether it is shown (null: all), and the surfaces'
+     * opacity: the panel's Cell Color, groups and selection. Changes no geometry.
+     */
+    setStyle(colors: Float32Array | null, visible: Uint8Array | null, opacity: number, selected?: Uint8Array | null): void;
+    /** Where the planes are among the observations (null: nowhere, nothing drawn), and the Z stretch. */
+    setPlacement(placement: PlanePlacement | null, zScale: number): void;
+    /** The observation of the cell drawn under canvas point (`x`, `y`) (CSS px), or -1. */
+    pick(x: number, y: number): number;
+    /** Whether `layer` is one of the cells' surfaces. */
+    owns(layer: Layer): boolean;
+    dispose(): void;
+    private schedule;
+    /** Drop every chunk (their layers) and any build in flight. */
+    private reset;
+    private closeSource;
+    /** Decide each chunk's detail (and whether it is drawn at all), then build what changed. */
+    private plan;
+    /** {@link assignTiers} from the view as it is now, taking down what it leaves out. */
+    private replanTiers;
+    /** Voxel edge of each tier, image px: fractions of a typical cell's diameter. */
+    private steps;
+    /**
+     * The chunks, nearest the centre of the view first, with how many screen pixels an image pixel
+     * of each takes (0 off screen).
+     */
+    private priority;
+    /**
+     * Each chunk's tier: in order, within the cell cap, as fine as the screen asks within the
+     * triangle budget. The chunks last in order give up their detail first, then are left out; the
+     * first is never left out, but one over the cap or the budget by itself meshes only the cells
+     * that fit (its {@link Chunk.limit}).
+     */
+    private assignTiers;
+    /** A chunk's triangles at `tier`: as built, else scaled from a tier built (by the step's square). */
+    private trianglesAt;
+    /** Build every chunk whose tier changed, nearest first, one at a time, until none is left. */
+    private run;
+    private build;
+    /**
+     * Draw every chunk again (a recolour, a hidden class, a selection): a few at a time, yielding the
+     * main thread between them so that a click selecting a cell never holds a frame; a newer redraw
+     * takes over from this one.
+     */
+    private redraw;
+    private redrawGeneration;
+    /** Place a chunk's vertices in the world, in the cells' worker, then draw it (unless superseded). */
+    private placeChunk;
+    /** Draw a chunk's visible cells, in their colours: its layer updated in place, or added. */
+    private draw;
+    /**
+     * One of a chunk's surfaces with these triangles and colours: updated in place, added, or hidden
+     * when it has none. Returns the layer (null: none was ever needed).
+     */
+    private drawSurface;
+    /** The triangles of the cells shown: their class not hidden, the observation shown. */
+    private visibleFaces;
+    /**
+     * Each vertex its cell's colour (white without colours). With a selection, a cell it leaves out
+     * keeps its colour and fades, as a picked region fades the others: its alpha brought down to the
+     * dimmed regions' opacity. `solid`: the selected cells' own surface, every vertex opaque.
+     */
+    private vertexColors;
+    private dropLayer;
+    private report;
+    /** Tell the host how the cells stand, only when that changed (the camera re-plans often). */
+    private lastStatus;
+    private emit;
+    private toWorldPoint;
+}
+/**
+ * Triangles `faces` split by whether their cell (`vertexCell` of their first vertex) is selected:
+ * the selected cells' triangles, then the others'.
+ */
+export declare function splitFaces(faces: Uint32Array, vertexCell: Uint32Array, selected: Uint8Array): [Uint32Array, Uint32Array];

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

@@ -12,6 +12,11 @@ import { SpatialSceneBase, SpatialSession } from './napari-spatial-scene';
 import type { NapariScene, SceneContext } from './napari-scene';
 /** The least Z stretch: a tenth of the true depth. */
 export declare const SPATIAL_Z_SCALE_MIN = 0.1;
+/**
+ * In-plane voxels across the image when a region set's planes are reconstructed over the dataset's
+ * own image (see voxelStep): a step of about 5 px on a 5,700 px wide MERFISH section (0.6 µm).
+ */
+export declare const REGION_PLANES_VOXELS = 1024;
 /**
  * The most a box's Z may be stretched: until it is twice as deep as it is wide, so even a section
  * microns thick and millimetres wide can be stood up into a block — but never less than the
@@ -62,6 +67,12 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
     /** The anatomical volume the cloud sits inside, when the dataset has one. */
     private volume;
     private volumeKey;
+    /**
+     * The reference volume on its way (its key and the load), shared by every rebuild that asks for
+     * it meanwhile: each one adding its own left one layer behind, which the view's toggle (bound to
+     * {@link volume}) then never hid.
+     */
+    private volumeLoading;
     /** 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. */
@@ -103,8 +114,15 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
      * regions were drawn on is that volume's stack (see {@link placeRegionMeshes}).
      */
     private readonly regionMeshes;
+    /** The transcripts of the genes the Transcripts panel draws, at their own z (see Spatial3dTranscripts). */
+    private readonly transcripts3d;
     /** Whether the reference volume lets every region surface through (see setRegionsThroughVolume). */
     private regionsThrough;
+    /**
+     * Each slice's z, in the observations' units, of the region set the surfaces are built from when
+     * it says where its slices are (a 3D segmentation's planes, see setRegionPlanes); else null.
+     */
+    private regionPlanes;
     /** The store's invert setting, which the density volumes follow (no other subscription of
      *  this scene carries it). */
     private invertSub;
@@ -113,10 +131,37 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
      *        image, see showVolumeAsImage) when the dataset has a volume, which the regions are on
      */
     constructor(ctx: SceneContext, session: SpatialSession, info?: IImageInfo | undefined);
+    /** The region set's classes drawn as individual cells (none: the class surfaces only). */
+    private readonly cells3d;
+    private readonly cellLookup;
+    private readonly cellWindows;
+    private cellClasses;
+    /** What the cells were last coloured for, so a rebuild that changed none of it recolours nothing. */
+    private cellStyleKey;
+    private cellStyleRequest;
+    /**
+     * Draw these classes of the dataset's region set as individual cells, each its own surface in
+     * the panel's Cell Color (see Spatial3dCells); none: no cells.
+     */
+    setRegionCells(classes: readonly string[] | null): void;
+    /**
+     * The cells' colours (the panel's Cell Color, its selection muting), which are shown (its groups
+     * switched off and gene filter hide theirs; the Cells switch all), and their opacity.
+     */
+    private styleCells;
+    private lastCellSelection;
+    private cellSelectionCount;
+    private cellSelectionRev;
     /** Show these region reconstructions with the cloud (replacing the ones shown). */
     setRegionMeshes(meshes: readonly RegionMesh3D[]): void;
     setRegionHighlight(keys: readonly string[]): void;
     setRegionHidden(keys: readonly string[]): void;
+    /**
+     * Where the region set's slices are, in the observations' units (null: they are the plotted
+     * stack's slices): its surfaces then sit at their planes among the observations (see
+     * placeRegionMeshes), on an image of one plane too.
+     */
+    setRegionPlanes(z: readonly number[] | null): void;
     /** As the Volume view: the reference volume hides the surfaces behind what it shows, or none. */
     setRegionsThroughVolume(through: boolean): void;
     /**
@@ -126,6 +171,11 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
      * is offset to sit in it). Only when the plotted image IS that volume's stack: regions drawn on
      * another image (a tissue image) have no place in it, and are not shown - nor are surfaces
      * placed in a volume this one replaced.
+     *
+     * Unless the region set says where its slices are ({@link setRegionPlanes}: a 3D segmentation's
+     * planes) and the plotted image is the dataset's own (`imageRef`): image pixels are then taken
+     * back to the observations' units through `imageRef`, slice k to its plane's z, and both moved
+     * by the offset the cloud is, so each cell's surface sits around its observation.
      */
     private placeRegionMeshes;
     /**
@@ -134,9 +184,26 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
      * share its cached surface). Null while there is no volume stack to place them in.
      */
     voxelStep(): number | null;
+    /**
+     * Where the region set's slices go (see placeRegionMeshes): only with their planes known, on the
+     * dataset's own image (one with an `imageRef`, not the reference volume's stack), once the box
+     * the cloud is offset into is there.
+     */
+    private planePlacement;
     /** Whether the plotted image is the reference volume's stack: its size and slice count. */
     private isVolumeStack;
     mount(): Promise<void>;
+    /**
+     * Picking the region surfaces (a cell type's, by type), as the Volume view does: with the selection
+     * tool armed, a click on one picks its class (null beside them), and the Region Editor highlights
+     * it, the others fading. Hovering is the spatial tooltip's (the type and its cells).
+     */
+    private listenToRegionMeshes;
+    private meshPointer;
+    /** Gives the camera back napari-js's own depth range (see keepSceneInDepth). */
+    private restoreDepth;
+    private toolSub;
+    private selecting;
     /** 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. */
@@ -172,6 +239,19 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
      * observation whose section is hidden.
      */
     screenProjection(obs: SpatialObservations): Float32Array | null;
+    /** The region surface (a class) under a client position, or null. */
+    pickRegion(clientX: number, clientY: number): {
+        key: string;
+        label?: string;
+    } | null;
+    /**
+     * With a selection, grey out the class surfaces none of it is in (a class is a category of the
+     * cell-type column: a 3D segmentation's cell type), as the observations it leaves out are muted.
+     */
+    private muteRegions;
+    private muteRequest;
+    /** The observation of the individual cell drawn under a client position, or -1. */
+    pickCell(clientX: number, clientY: number): number;
     dispose(): void;
     /**
      * The observation under a client position: the FRONT-most marker within `slackPx` of the
@@ -206,6 +286,13 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
      * source swapped in place otherwise; then the selection and the visibility.
      */
     private drawCloud;
+    /**
+     * The markers shown as the view asks, but not while the cells (a 3D segmentation's) stand in for
+     * them: the observations are shown as their markers or as their cells. Only once the set is placed
+     * here (its planes known): a set that could not be opened, has no planes or was not attached draws
+     * no cells, and the markers stay.
+     */
+    private showPointsAsAsked;
     /** Interleaved x,y,z of the `shown` observations (null: all of them), offset by {@link origin}. */
     private cloudPositions;
     /**
@@ -285,6 +372,8 @@ export declare class Spatial3dScene extends SpatialSceneBase implements NapariSc
      * the camera frames the points instead.
      */
     private ensureVolume;
+    /** Fetch the reference volume and add it, unless another one was asked for meanwhile. */
+    private loadVolume;
     /**
      * The box everything sits in, centred on the world origin, and the offset that sits the
      * observations in it; with the axes gizmo and the Z handle on it.

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

@@ -0,0 +1,103 @@
+import type { Points3DLayer, Viewer } from 'napari-js';
+import { type SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import type { SpatialViewState } from '../../contracts/display-types';
+import { type SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import type { SpatialSelectionMask } from '../../spatial/spatial-selection';
+/** Most transcripts drawn in the 3D view: past it, every k-th one is drawn (and the console says so). */
+export declare const TRANSCRIPTS_3D_MAX = 2000000;
+/** Most level-0 tiles read for the 3D view: a dataset needing more is too large to draw whole. */
+export declare const TRANSCRIPTS_3D_MAX_TILES = 4096;
+/** A transcript's marker in the 3D view, in screen pixels at a transcript scale of 1. */
+export declare const TRANSCRIPT_3D_BASE_SIZE = 2;
+/** What the 3D transcripts need of the scene: where the cloud sits and how Z is stretched. */
+export interface Transcripts3dFrame {
+    /** Offset applied to observation coordinates to sit them in the scene's box. */
+    origin: readonly [number, number, number];
+    zScale: number;
+}
+/** The genes a view draws in 3D, as the tile query takes them, or null when it draws none. */
+export declare function transcripts3dGenes(dataset: SpatialDataset, view: SpatialViewState): {
+    query: string[];
+    allGenes: boolean;
+} | null;
+/**
+ * Each loaded transcript's colour, packed RGBA, as the 2D markers colour them by gene: a gene's
+ * chosen colour, else the palette's by its slot (the selection's order, or with "All genes" the
+ * dataset's gene code).
+ */
+export declare function transcripts3dColors(view: SpatialViewState, names: readonly string[] | null, gene: Uint16Array, count: number): Float32Array;
+/**
+ * How the panel's "Colour by" applies in 3D, as it does to the 2D markers (`colorViewFor`): by
+ * cell type when the dataset has one (else by gene), by cluster for the selected genes (with "All
+ * genes" a cluster is its gene), by gene otherwise.
+ */
+export declare function transcripts3dColorBy(dataset: SpatialDataset, view: SpatialViewState, allGenes: boolean): 'cellType' | 'cluster' | 'gene';
+/**
+ * The transcripts of the 3D spatial view: the molecules of the genes the Transcripts panel draws
+ * (its selected genes, or "All genes"), at their own x, y and z, in the cloud's box and Z stretch.
+ *
+ * By level of detail, as the 2D view reads them: the pyramid level the camera's distance calls for
+ * (`transcriptLevelFor`, the markers per screen kept about constant: aggregates far out, every
+ * molecule close in on a cell), and only the tiles of the part of the section in view (the canvas's
+ * corners cast onto the section's plane). Planned again when the camera rests; tiles are cached, so
+ * coming back reads nothing. "Loading transcripts…" shows on the canvas while they load and draw.
+ * Drawn only for a dataset whose transcripts carry z.
+ */
+export declare class Spatial3dTranscripts {
+    private readonly viewer;
+    private readonly begin;
+    private layer;
+    /** What {@link layer} was loaded from (dataset, genes, quality), and styled with. */
+    private loadKey;
+    private styleKey;
+    private loaded;
+    private readonly loads;
+    /** Each drawn transcript's cell ({@link NO_OBSERVATION} for none), for fading by the selection. */
+    private drawnCells;
+    /** The selection the layer's alphas fade by (null: none, every transcript as it is). */
+    private fadedBy;
+    /** The last sync's inputs: the camera resting plans the detail again from them. */
+    private last;
+    private cameraTimer;
+    private cameraOff;
+    /** Tiles read, by genes, quality, level and tile (least recently used dropped first). */
+    private readonly tileCache;
+    constructor(viewer: Viewer, begin: (message: string) => () => void);
+    /** The camera moved: once it rests, read the level and tiles it now calls for. */
+    private cameraMoved;
+    /** Stop following the camera (the scene went away). */
+    dispose(): void;
+    /**
+     * The level and the tiles the camera calls for: the level whose tiles come out about 512 screen
+     * pixels across at the target's depth, the tiles of the section in view (whole, when a corner of
+     * the canvas looks past the section's plane).
+     */
+    private plan;
+    /**
+     * The part of the section the canvas sees, in observation units: its corners and centre cast onto
+     * the plane through the camera's target, widened by a quarter. A corner looking past the plane
+     * (towards the horizon) reaches far along its ray instead (the tiles are clipped to the section).
+     */
+    private footprint;
+    /** A tile, read once (and again only once dropped from the cache). */
+    private tile;
+    /** The layer drawn, if any (for tests and the scene's Z stretch). */
+    get drawn(): Points3DLayer | null;
+    /**
+     * Draw what `view` asks for, loading the molecules when the genes changed. With a `selection`
+     * (a cell, or a cell type's cells), the transcripts of the selected cells keep their colour and
+     * the others fade, as the cells do.
+     */
+    sync(dataset: SpatialDataset, view: SpatialViewState, port: SpatialDataPort | null, frame: Transcripts3dFrame, selection?: SpatialSelectionMask | null): Promise<void>;
+    /** Follow the scene's Z stretch (nothing is re-uploaded). */
+    setZScale(s: number): void;
+    /** Take the layer down and forget what it showed. */
+    remove(): void;
+    private clearLayer;
+    /**
+     * Fade the drawn transcripts outside the selection (their alpha only: the colours stay
+     * uploaded), or bring them all back without one. A no-op for the selection already applied.
+     */
+    private fade;
+    private draw;
+}

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

@@ -2,7 +2,7 @@ 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 { GroupColorOverrides, 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
@@ -16,6 +16,13 @@ export declare const SPATIAL_FALLBACK_RADIUS = 4;
  *  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;
+/**
+ * Smallest drawn marker diameter in the 2D view, in SCREEN pixels, at any zoom. A marker's size is
+ * the cell's own (data units), so zoomed out over a whole Cytos plate or Xenium section every cell
+ * fell below a pixel and the observations vanished; with the floor they stay a dense field of
+ * dots, coloured as they are, at every zoom (the GPU applies it per frame: no rebuild on zoom).
+ */
+export declare const SPATIAL_MARKER_MIN_SCREEN_PX = 2;
 /** 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. */
@@ -116,4 +123,4 @@ export declare function totalDensityGroup(selection: SpatialSelectionMask): Dens
  * {@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[];
+export declare function rankDensityGroups(columnName: string, column: CategoricalColumn, count: number, selection: SpatialSelectionMask, groupColors?: GroupColorOverrides | null): DensityGroup[];

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

@@ -23,6 +23,16 @@ export interface SpatialHoverHost {
      * drawn index back to the observation.
      */
     pick(clientX: number, clientY: number, slackPx: number): number;
+    /**
+     * The observation of an individual cell's surface under a client position (spatial 3D's cells),
+     * or -1: a click on one selects that cell rather than its class. Optional.
+     */
+    pickCell?(clientX: number, clientY: number): number;
+    /** The region surface (a class: a cell type's, in spatial 3D) under a client position, or null. Optional. */
+    pickRegion?(clientX: number, clientY: number): {
+        key: string;
+        label?: string;
+    } | null;
     /** The 2D transcript markers, which sit on top of everything and are asked first. */
     tiles(): NapariSpatialTileLayers | null;
     /** A region tool owns the pointer (placing a polygon vertex is also a still click). */
@@ -47,6 +57,10 @@ export declare class SpatialHover {
     /** What the markers are coloured by, resolved once per colour source rather than per hover. */
     private hoverSource;
     private hoverSourceKey;
+    /** In 3D: what a cell's tooltip says of it (its type, id, measurements), resolved once per dataset. */
+    private cellInfo;
+    private cellInfoKey;
+    private readonly cellInfoLoads;
     /** Latest wins within the scene: the KEY is only committed once a resolution lands, so a
      *  superseded fetch cannot leave the cache claiming to hold a source it never stored. */
     private readonly resolutions;
@@ -75,6 +89,14 @@ export declare class SpatialHover {
      * the pointer moved would be indefensible either way.
      */
     resolveSource(dataset: SpatialDataset | null, view: SpatialViewState): Promise<void>;
+    /**
+     * What a 3D cell's tooltip says (see `cellText`): the cell-type column's codes, the ids, and the
+     * dataset's first few continuous columns. Resolved once per dataset and type column; a failure
+     * leaves the tooltip with what the colouring says.
+     */
+    private resolveCellInfo;
+    /** In 3D: the tooltip of the cell, or of the cell type's surface, under a client position. */
+    private cell3dText;
     /** Hit-test the last pointer position and show or hide the tooltip. */
     private update;
     /**

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

@@ -1,3 +1,4 @@
+import type { Cells3dStatus } from '../../contracts/display-types';
 import { Observable } from 'rxjs';
 import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
 import { SpatialDataset } from '../../contracts/spatial-dataset.contract';
@@ -28,6 +29,8 @@ export interface SpatialTileSinks {
     loadingChanged(layers: string[]): void;
     /** Whether the observation gene filter could be applied; see {@link SpatialSession.reportGeneFilter}. */
     geneFilterFailed?(failed: boolean): void;
+    /** How the 3D view's individual cells stand; see {@link SpatialSession.reportCells3d}. */
+    cells3dStatus?(status: Cells3dStatus | null): void;
 }
 /** The 2D scene the tile layers currently draw into. */
 export interface SpatialTileOwner {
@@ -66,6 +69,8 @@ export declare class SpatialSession {
     private tileLayers;
     private tileOwner;
     constructor(port: SpatialDataPort | null, selection: SpatialSelectionStore | null, sinks: SpatialTileSinks);
+    /** Tell the panel how the 3D view's individual cells stand (null: none drawn). */
+    reportCells3d(status: Cells3dStatus | null): void;
     /** Tell the panel whether the observation gene filter could be applied this rebuild. */
     reportGeneFilter(failed: boolean): void;
     /** The tile layers, if they were ever built. */
@@ -116,6 +121,13 @@ export declare abstract class SpatialSceneBase {
     protected afterChange(): void;
     /** The observation drawn under a client position, or -1 (see `SpatialHoverHost.pick`). */
     protected abstract pickObservation(clientX: number, clientY: number, slackPx: number): number;
+    /** The region surface (a class) under a client position, or null (none drawn). */
+    pickRegion(_clientX: number, _clientY: number): {
+        key: string;
+        label?: string;
+    } | null;
+    /** The observation of an individual cell's surface under a client position, or -1 (none drawn). */
+    pickCell(_clientX: number, _clientY: number): number;
     protected hoverTiles(): NapariSpatialTileLayers | null;
     /** Stop following the data, drop the hover, and make every rebuild in flight stale. */
     protected disposeSpatial(): void;

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

@@ -48,11 +48,10 @@ export interface SpatialTileHost {
  * -----------
  * Cell fill, cell outline, nucleus outline, the transcript density, then transcripts on top
  * ({@link TILE_LAYER_ORDER}); a plan restores the order once, after all its groups are in
- * place. The service's observation markers sit under all of them; while outlines are drawn the
- * markers are hidden (a cell is its outline then, not a dot), so the cells never have to
- * be ordered against them. The density goes OVER the markers on purpose: under 10^5
- * dots it would only show in the gaps between cells. {@link afterObservations} restores
- * the order after the service re-adds its markers.
+ * place. The service's observation markers sit under all of them, drawn at every zoom: once
+ * cells are big enough to outline, their outlines go over their markers. The density goes
+ * OVER the markers on purpose: under 10^5 dots it would only show in the gaps between cells.
+ * {@link afterObservations} restores the order after the service re-adds its markers.
  *
  * ONE LAYER PER GROUP
  * -------------------
@@ -68,6 +67,10 @@ export declare class NapariSpatialTileLayers {
     /** Consecutive retries of an incomplete view. */
     private tileRetries;
     private token;
+    /** The z band of the plane shown, when the view shows one plane of a 3D assay (see setZBand). */
+    private zBand;
+    /** The plane of a 3D segmentation shown (see setPlane), or null. */
+    private plane;
     /** The overlays' layers, one per group, in their fixed order. */
     private readonly groups;
     /** Loads in flight, per layer label, for the loading badge. */
@@ -95,12 +98,23 @@ export declare class NapariSpatialTileLayers {
     hoverAt(wx: number, wy: number, radiusWorld: number, onDetails: (lines: string[]) => void): string[] | null;
     /** Whether `layer` is one of the overlays drawn here (density, cells, transcripts). */
     owns(layer: Layer): boolean;
-    /** True while outlines are on screen — the service hides its dots then. */
+    /** True while outlines are on screen. */
     get outlinesShown(): boolean;
     /** The density window in use and the densest bin, for the panel's threshold control. */
     get densityStats(): DensityStats | null;
     /** Dataset, view or selection changed: re-plan now rather than on camera idle. */
     refresh(): void;
+    /**
+     * Show one plane of a 3D assay (its z band, `[lo, hi)` in observation units), or every depth
+     * (null): the transcripts drawn are those in the band. Re-plans when it changes.
+     */
+    setZBand(band: readonly [number, number] | null): void;
+    /**
+     * Show plane `plane` of a 3D segmentation (an index into its region set's planes), or none: a
+     * boundary set naming its region set draws that plane's cells (see `CellLayers.setPlane`).
+     * Re-plans when it changes.
+     */
+    setPlane(plane: number | null): void;
     /** Called right after the service adds its marker layer: everything goes back on top. */
     afterObservations(): void;
     private schedule;