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

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

@@ -1,10 +1,31 @@
 import type { Layer, Viewer } from 'napari-js';
 import type { Rgb } from '../../contracts/colormap-lut';
-import { type SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import type { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
 import type { SpatialViewState } from '../../contracts/display-types';
-import { SpatialDataset, SpatialDensityRaster, SpatialImageRef, SpatialPolygonTile, SpatialTranscriptTile } from '../../contracts/spatial-dataset.contract';
-import { SpatialSelectionMask } from '../../spatial/spatial-selection';
-import { DataRect } from '../../spatial/spatial-tiles';
+import type { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import type { SpatialSelectionMask } from '../../spatial/spatial-selection';
+import { DataRect } from '../../spatial/lod';
+import { DensityStats, TranscriptEstimate } from './spatial-tiles/density-layer';
+export type { TranscriptEstimate } from './spatial-tiles/density-layer';
+/** What the tile layers read from, and report to, the visualizer service. */
+export interface SpatialTileHost {
+    /** Latest dataset/view/selection, as the spatial subscription saw them. */
+    latest(): [SpatialDataset | null, SpatialViewState, SpatialSelectionMask] | null;
+    /** Canvas size in CSS pixels. */
+    canvasSize(): [number, number];
+    /** The continuous LUT the view is using (so cells coloured by a gene match the markers). */
+    continuousLut(view: SpatialViewState): Rgb[];
+    /** Outlines appeared or disappeared: the markers' visibility follows. */
+    polygonsShownChanged(shown: boolean): void;
+    /** The density window changed (auto-derived or set). */
+    densityChanged?(stats: DensityStats): void;
+    /** Estimated transcripts in view for the current selection, against the budget. */
+    estimateChanged?(estimate: TranscriptEstimate | null): void;
+    /** Transcripts of each selected gene inside the view, or null when not known. */
+    geneCountsChanged?(counts: Record<string, number> | null): void;
+    /** The layers whose data is in flight now ("Transcripts", "Cells"…); empty when none. */
+    loadingChanged?(layers: string[]): void;
+}
 /**
  * Level-of-detail cell outlines, transcripts and transcript density for the 2D spatial view.
  *
@@ -15,11 +36,19 @@ import { DataRect } from '../../spatial/spatial-tiles';
  * and which level of detail the zoom calls for. Keeping that loop — plan on camera idle,
  * fetch tiles, merge, draw — out of the visualizer service keeps both readable.
  *
+ * COLLABORATORS (spatial-tiles/)
+ * ------------------------------
+ * This class is the coordinator: it debounces camera moves, runs one plan per idle camera
+ * (a {@link PlanContext}) and retries an incomplete one. The work is done by
+ * {@link CellLayers}, {@link TranscriptLayers} (with {@link TranscriptJobPlanner} deciding what
+ * to fetch), {@link DensityLayer} and {@link TranscriptEstimator}; {@link TranscriptHover}
+ * names the drawn markers, and {@link OrderedLayerGroups} keeps their layers in order.
+ *
  * LAYER ORDER
  * -----------
- * napari-js's layer list is append-only (add / remove / clear), so order is kept by
- * re-adding: cell fill, cell outline, the transcript density, then transcripts on top.
- * The service's observation markers sit under all of them; while outlines are drawn the
+ * 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
@@ -31,285 +60,49 @@ import { DataRect } from '../../spatial/spatial-tiles';
  * level changes. Recolouring (a new cell-type column, a selection) only rewrites the
  * per-shape values — the geometry is not re-expanded.
  */
-export interface SpatialTileHost {
-    /** Latest dataset/view/selection, as the spatial subscription saw them. */
-    latest(): [SpatialDataset | null, SpatialViewState, SpatialSelectionMask] | null;
-    /** Canvas size in CSS pixels. */
-    canvasSize(): [number, number];
-    /** The continuous LUT the view is using (so cells coloured by a gene match the markers). */
-    continuousLut(view: SpatialViewState): Rgb[];
-    /** Outlines appeared or disappeared: the markers' visibility follows. */
-    polygonsShownChanged(shown: boolean): void;
-    /** The density window changed (auto-derived or set). */
-    densityChanged?(stats: {
-        lo: number;
-        hi: number;
-        max: number;
-    }): void;
-    /** Estimated transcripts in view for the current selection, against the budget. */
-    estimateChanged?(estimate: TranscriptEstimate | null): void;
-    /** Transcripts of each selected gene inside the view, or null when not known. */
-    geneCountsChanged?(counts: Record<string, number> | null): void;
-    /** The layers whose data is in flight now ("Transcripts", "Cells"…); empty when none. */
-    loadingChanged?(layers: string[]): void;
-}
-/** Xenium Explorer's "Estimated Transcript Points". */
-export interface TranscriptEstimate {
-    /** Transcripts of the visible genes estimated to be in view. */
-    points: number;
-    /** The marker budget. */
-    max: number;
-}
-/** A transcript fetch the planner can key before running. */
-interface TranscriptJob {
-    /** What one entry is — decides what hovering it says. */
-    kind: 'genes' | 'individual' | 'bins';
-    /** For bins: their size and grid origin, so a hovered bin's square can be recovered. */
-    bin?: {
-        size: number;
-        origin: [number, number];
-    };
-    /** Identifies what will be drawn, so an unchanged plan is a no-op. */
-    key: string;
-    /** Fetch and merge; `px` is each entry's marker diameter in screen pixels. A job may
-     *  switch to another kind once it sees the data (individual → bins); it then says so. */
-    load(): Promise<TranscriptLoad>;
-}
-interface TranscriptLoad {
-    merged: SpatialTranscriptTile;
-    px: Float32Array;
-    /** For a gene selection: group it on this bin ladder once hidden genes are dropped. */
-    ladder?: {
-        baseBin: number;
-        levels: number;
-        start: number | null;
-    };
-    /** Already one marker per cluster per bin (zoomed out, from the density grids): no cells. */
-    clustered?: {
-        group: Int32Array;
-        names: string[];
-        genes: string[][];
-        bin: number;
-        origin: [number, number];
-    };
-    kind?: TranscriptJob['kind'];
-    bin?: TranscriptJob['bin'];
-}
 export declare class NapariSpatialTileLayers {
-    private readonly port;
     private readonly host;
     private viewer;
     private cameraOff;
     private timer;
-    /** Set when a tile of the current plan failed to load (see fetchAll). */
-    private planIncomplete;
     /** Consecutive retries of an incomplete view. */
     private tileRetries;
     private token;
-    private readonly layers;
-    /** What each group currently shows, so an unchanged plan is a no-op. */
-    private readonly keys;
-    private polygonsShown;
-    /** Rings currently drawn and the (dataset, set, tiles) they came from. */
-    private currentRings;
-    private cellGeometryKey;
-    private currentNuclei;
-    private cellStyleKey;
-    /** Selection identity → revision, so a change key can name a selection cheaply. */
-    private lastSelection;
-    private selectionRevision;
+    /** The overlays' layers, one per group, in their fixed order. */
+    private readonly groups;
+    /** Loads in flight, per layer label, for the loading badge. */
+    private readonly loads;
+    private readonly lookup;
+    private readonly jobs;
+    private readonly density;
+    private readonly cells;
+    private readonly estimator;
+    private readonly hover;
+    private readonly transcripts;
     constructor(port: SpatialDataPort, host: SpatialTileHost);
     attach(viewer: Viewer): void;
-    /**
-     * Group a gene selection for the zoom: one marker per gene-tree cluster (a gene in no
-     * cluster is its own) per bin of the pyramid ladder, starting at the finest bin whose
-     * markers are 14 px apart and stepping up while the markers would exceed the budget.
-     * Null to draw every transcript: zoomed in, with the selection within the budget.
-     */
-    private groupSelection;
-    /** µm per observation unit of the drawn dataset, for describing a grouped marker's area. */
-    private micronsPerUnit;
-    /** Loads in flight, per layer label, for the loading badge. */
-    private readonly loading;
-    /** Report `label` loading while `work` is in flight. */
-    private track;
-    /** The loaded per-gene transcripts the in-view counts are taken from. */
-    private countSource;
+    /** Stop following the camera and remove every overlay layer from the viewer. */
+    detach(): void;
     /**
      * Transcripts of each selected gene inside `rect`: each entry counts for the transcripts it
      * stands for (an aggregate at a coarse level holds several). Null without per-gene data.
      */
     geneCountsIn(rect: DataRect): Record<string, number> | null;
+    /**
+     * Tooltip lines for the transcript marker under world point `(wx, wy)`, or null; the
+     * server's details arrive through `onDetails` once the pointer rests (see TranscriptHover).
+     */
+    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;
-    detach(): void;
     /** True while outlines are on screen — the service hides its dots then. */
     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;
     /** Called right after the service adds its marker layer: everything goes back on top. */
     afterObservations(): void;
     private schedule;
     private plan;
-    private planCells;
-    private selectionRev;
-    /** Per-shape values + colormap for the rings' owners. */
-    /**
-     * Per-shape values + colormap for the rings' owners, by the view's cell-colour mode
-     * (Xenium Explorer's "Cell Color"). A selection mutes what it leaves out.
-     */
-    private cellColors;
-    /** Codes of the group column that are switched off, or null when none are. */
-    private hiddenCodes;
-    private cellTypeColumnName;
-    private categoricalCodes;
-    private categoricalColormap;
-    /**
-     * The cell rings (and, for "both", the nucleus rings) covering `rect` at `level`, minus
-     * the hidden groups — reused when nothing that decides them changed. Null when the
-     * view went stale or the dataset has no set to draw.
-     */
-    private cellGeometry;
-    private planTranscripts;
-    /** One sized circle per entry, the size saying how many transcripts it stands for. */
-    private drawTranscriptCircles;
-    private drawTranscriptGlyphs;
-    private drawn;
-    private hoverTypes;
-    /** Details already fetched, by hovered entry. */
-    private readonly hoverCache;
-    private hoverKey;
-    private hoverTimer;
-    /**
-     * Tooltip lines for the transcript marker under world point `(wx, wy)`, or null.
-     *
-     * Returns what is known at once (gene, count, cell type); anything that needs the
-     * server — distinct genes in a group, its top genes and cells, the cell's display id —
-     * arrives through `onDetails` once the pointer has rested on the marker briefly.
-     */
-    hoverAt(wx: number, wy: number, radiusWorld: number, onDetails: (lines: string[]) => void): string[] | null;
-    private fetchDetails;
-    /** The tooltip text for entry `i`, with the server's details when they have arrived. */
-    private describe;
-    /** Physical marker size needs µm; null when the dataset's unit is unknown. */
-    private pxPerMicron;
-    /**
-     * The chosen genes, at the level the zoom calls for — or coarser, while the markers in
-     * view would exceed the budget.
-     */
-    private geneJob;
-    /**
-     * A gene selection from the pyramid's per-gene levels: starting at the level whose bins are
-     * `startBin`, fetch the view's tiles for the selected genes and step to a coarser level while
-     * one marker per cluster per bin would exceed the max. Hidden genes are fetched too (their
-     * counts in view still show) and dropped before drawing; grouping by cluster happens there.
-     */
-    private geneBinsJob;
-    /** The selection's clusters: each gene-tree group's visible genes, then each ungrouped gene. */
-    private selectionClusters;
-    /**
-     * Per-gene density grids summed for `genes`, cached (a cluster is asked for once per bin).
-     * Keyed by dataset too: this manager outlives a dataset, and another may share gene names.
-     */
-    private densityFor;
-    private readonly densityCache;
-    /**
-     * A gene selection zoomed out: one marker per cluster per bin, from the per-gene density
-     * grids. The bin starts where markers are 14 px apart and doubles until the markers fit the
-     * max; each marker sits at the count-weighted centre of the finer grid inside it, so markers
-     * follow the tissue rather than a lattice.
-     */
-    private clusterDensityJob;
-    /**
-     * Every gene: the transcripts themselves once they fit the budget, else bins of the
-     * all-gene pyramid sized by how many transcripts each holds.
-     */
-    private allGenesJob;
-    /** Bins of the all-gene pyramid at `level`, sized by how many transcripts each holds. */
-    private binsJob;
-    /** Per-entry colours both as RGBA (points) and as colormap values (glyph shapes). */
-    private transcriptColors;
-    private planDensity;
-    private countsCache;
-    /**
-     * Transcripts in view for the visible genes: each gene's dataset total times the share
-     * of the tissue on screen. An estimate — expression is not uniform — which is also what
-     * Xenium Explorer shows; it tells the user whether the budget will force grouping.
-     */
-    private planEstimate;
-    /** The density window in use and the densest bin, for the panel's threshold control. */
-    densityStats: {
-        lo: number;
-        hi: number;
-        max: number;
-    } | null;
-    /**
-     * Fetch every tile, drawing what arrived. A failure does not fail the view, but it marks the
-     * plan incomplete: the caller must not cache it as done, and `plan()` retries it.
-     */
-    private fetchAll;
-    /**
-     * Put a shapes layer in place for `group`: a geometry change builds a new layer, a
-     * colour-only change mutates values/colormap on the existing one.
-     */
-    private upsertShapes;
-    /**
-     * Install `layer` as `group`'s layer and restore the order of the groups above it.
-     * The layer was just added by the caller (so it is on top); groups that belong above
-     * it are removed and re-added.
-     */
-    private replace;
-    private drop;
-    private dropCells;
-    private setPolygonsShown;
-}
-/** What the transcript layer currently shows — what hovering needs to name a marker. */
-interface DrawnTranscripts {
-    kind: TranscriptJob['kind'];
-    bin?: TranscriptJob['bin'];
-    merged: SpatialTranscriptTile;
-    /** Marker radius per entry, in observation units. */
-    radius: Float32Array;
-    genes: string[];
-    ref: SpatialImageRef | null;
-    /** For a grouped gene selection: each entry's group, and the groups' names. */
-    entryGroup?: Int32Array;
-    groupNames?: string[];
-    /** Each group's genes, when the markers came from the density grids (for the hover). */
-    groupGenes?: string[][];
-    /** Lazily built spatial index: bucket → entry indices. */
-    grid: {
-        size: number;
-        buckets: Map<number, number[]>;
-    } | null;
 }
-/** Index of the entry under `(x, y)` — within its own radius or `tolerance` — or -1. */
-export declare function pickNearest(d: Pick<DrawnTranscripts, 'merged' | 'radius' | 'grid'>, x: number, y: number, tolerance: number): number;
-/** Rings whose owning cell is in a switched-off group removed. */
-export declare function filterRings(rings: SpatialPolygonTile, hidden: {
-    codes: Uint16Array;
-    hidden: Uint8Array;
-} | null): SpatialPolygonTile;
-/** Entries in a hidden group's cell, or of a hidden gene, removed (with their sizes). */
-export declare function filterTranscripts(t: SpatialTranscriptTile, px: Float32Array, hidden: {
-    codes: Uint16Array;
-    hidden: Uint8Array;
-} | null, hiddenGenes: Uint8Array | null): {
-    merged: SpatialTranscriptTile;
-    px: Float32Array;
-};
-/** Concatenate tiles' rings into one set, dropping rings already seen (a cell straddling
- *  two tiles may be listed by both). */
-export declare function mergePolygonTiles(tiles: SpatialPolygonTile[]): SpatialPolygonTile;
-/** Concatenate transcript tiles, stopping at `limit` entries. */
-export declare function mergeTranscriptTiles(tiles: SpatialTranscriptTile[], limit?: number): SpatialTranscriptTile;
-/**
- * One marker per (cluster, `bin` square) from per-cluster density grids: the counts of the grid
- * cells inside `area` summed per square, at their count-weighted centre. `slots[c]` is the gene
- * slot whose icon cluster c's markers take.
- */
-export declare function clusterMarkers(rasters: SpatialDensityRaster[], slots: number[], bin: number, area: DataRect): {
-    tile: SpatialTranscriptTile;
-    group: Int32Array;
-};
-export {};

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

@@ -1,6 +1,6 @@
 /**
  * Cursor tooltip naming the observation under the pointer, for the spatial-omics
- * views — the same overlay-in-the-host pattern as {@link NapariScaleBar}.
+ * views — the same overlay-in-the-host pattern as napari-js's `ScaleBarOverlay`.
  *
  * 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 the job a tooltip removes. It

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

@@ -0,0 +1,76 @@
+import type { SurfaceLayer } from 'napari-js';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { ISurface3dControls } from '../../contracts/visualizer.contract';
+import { LumaPlane } from './napari-helpers';
+import type { NapariScene, SceneContext } from './napari-scene';
+/**
+ * NAPARI_SURFACE (review Appendix B, cluster G): the slice as a height field. A height field is
+ * single-scalar, so for a multichannel image the surface follows ONE band — the pane-selected
+ * channel — coloured by that channel's window/colormap (like the Plotly SURFACE, which is
+ * grayscale-only). Every slice's plane is pre-loaded with a progress bar (as the volume does) so
+ * the stack slider re-slices instantly. All mesh + GPU work lives in napari-js (`heightField` +
+ * `Viewer.addSurface`); this scene supplies scalar slices.
+ */
+export declare class SurfaceScene implements NapariScene {
+    private readonly ctx;
+    /** The height-field mesh (null until the first build). */
+    layer: SurfaceLayer | null;
+    /** Which band the surface samples (a channel index for multichannel, else the composite). */
+    private channel;
+    /** True when the surface follows one band of a multichannel image. */
+    private multichannel;
+    /** Pre-loaded per-slice luminance planes (already decimated to the surface grid), keyed by z,
+     *  so the stack slider rebuilds the surface instantly. Filled by {@link preloadPlanes}. */
+    readonly planes: Map<number, LumaPlane>;
+    /** The preload in flight; a newer one (a channel switch) aborts it. */
+    private preload;
+    /** In-plane grid cap for this load (full grid ÷ the decimate factor). */
+    private maxGrid;
+    /** Contrast window [min,max] the current mesh was built with. A change reshapes the mesh (pixel
+     *  height = intensity within [min,max]), so it triggers a geometry rebuild. */
+    private window;
+    /** The current slice's plane, for the intensity histogram. */
+    private histogramPlane;
+    private gizmo;
+    private displaySub;
+    constructor(ctx: SceneContext);
+    mount(): Promise<void>;
+    /** One slice → one mesh: re-build the height field for the new slice. Not built yet → nothing to
+     *  do; the build at the end of the mount reads the current slice. */
+    setZ(z: number): void;
+    /** The current slice's intensity histogram (the plane the mesh was built from). */
+    histogram(_channel: number, bins: number): IHistogram | null;
+    surface3dControls(): ISurface3dControls | null;
+    dispose(): void;
+    /** Add the axes gizmo + labels around the (origin-centered) mesh, matching the volume. The box
+     *  tracks the mesh bounds, X/Y show the physical (or pixel) extent, and Z is the intensity axis. */
+    private installAxes;
+    /** X/Y/Z end-labels for the gizmo: X/Y are the physical (µm) or pixel extent of the FULL image;
+     *  Z is the intensity/height axis. Anchors are in the centered box (matching AxesLayer). */
+    private axesLabels;
+    /**
+     * Pre-fetch every stack slice's luminance plane (decimated to the surface grid) into
+     * {@link planes}, driving the stack progress — the same load-with-progress UX as the volume, but
+     * keeping one 2D plane per slice rather than packing a 3D volume. Bounded concurrency keeps the
+     * connection pool busy without flooding it on a deep stack.
+     */
+    preloadPlanes(): Promise<void>;
+    /** Slice `z` as a whole-image luminance plane of the surface's band, decimated to `maxGrid`. */
+    fetchPlane(z: number, maxGrid: number): Promise<LumaPlane>;
+    /** The channel state driving the surface: the chosen band for multichannel (matched by index),
+     *  else the single grayscale channel. */
+    private channelState;
+    /**
+     * (Re)build the mesh for slice `z` from the pre-loaded plane cache (instant — this is what the
+     * stack slider calls); a slice missing from the cache is fetched on demand. napari-js's pure
+     * `heightField` builds the triangle grid (z = normalized intensity), then `addSurface` renders
+     * it. The slice plane also feeds the intensity histogram.
+     */
+    private build;
+    /** The store colormap / reverse / invert / channel window → the surface, so histogram & channel
+     *  dialog edits update it live without a re-fetch. **min/max reshapes the surface's height** (a
+     *  pixel's height = its intensity within [min,max]), so a window change rebuilds the mesh
+     *  geometry (from the cached slice); colour-only edits (colormap/LUT, gamma, reverse, invert)
+     *  just update the layer's uniforms. */
+    private followDisplayState;
+}