@jax-data-science/sci-image-visualizer 0.6.0 → 0.7.0

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

@@ -0,0 +1,240 @@
+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 { SpatialViewState } from '../../contracts/display-types';
+import { SpatialDataset, SpatialImageRef, SpatialPolygonTile, SpatialTranscriptTile } from '../../contracts/spatial-dataset.contract';
+import { SpatialSelectionMask } from '../../spatial/spatial-selection';
+/**
+ * Level-of-detail cell outlines, transcripts and transcript density for the 2D spatial view.
+ *
+ * WHY A SEPARATE CLASS
+ * --------------------
+ * Everything else the spatial view draws is built once per (dataset, view) and only
+ * restyled afterwards. These layers also depend on the CAMERA: which tiles are on screen
+ * 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.
+ *
+ * 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
+ * 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.
+ *
+ * ONE LAYER PER GROUP
+ * -------------------
+ * Each group is one merged layer over every visible tile, rebuilt when the tile set or
+ * 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;
+}
+/** 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;
+    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;
+    constructor(port: SpatialDataPort, host: SpatialTileHost);
+    attach(viewer: Viewer): void;
+    /** 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;
+    /** 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;
+    /**
+     * 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;
+    /** 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;
+export {};

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

@@ -1,8 +1,9 @@
-import { Observable } from 'rxjs';
+import { Observable, BehaviorSubject } 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 { TranscriptEstimate } from './napari-spatial-tiles';
 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';
@@ -162,6 +163,16 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     /** Dataset the 3D scale bar was built for. */
     private spatialScaleBarKey;
     private spatialSub;
+    /** Level-of-detail cell outlines, transcripts and density over the 2D view — created on
+     *  first use, and only when a spatial port is bound. */
+    private spatialTilesMgr;
+    /** For the panel: the transcripts-in-view estimate and the density window in use. */
+    readonly transcriptEstimate$: BehaviorSubject<TranscriptEstimate | null>;
+    readonly densityStats$: BehaviorSubject<{
+        lo: number;
+        hi: number;
+        max: number;
+    } | null>;
     /** Latest (dataset, view, selection) the spatial subscription saw, so a slice
      *  change can rebuild the markers for the new plane. */
     private spatialLatest;
@@ -219,6 +230,12 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private invertEnabled;
     /** Physical scale bar overlay for the 2D image (null when 3D or the image has no µm/pixel). */
     private scaleBar;
+    /** Overview minimap (bottom-right), as OSD's navigator. */
+    private navigator;
+    /** Whether the navigator is shown — the same host setting OSD's navigator honours. */
+    private navigatorVisible;
+    /** Bumped per thumbnail request, so a slow one cannot overwrite a newer slice's. */
+    private navigatorToken;
     /** SVG region-drawing overlay for the 2D image (null until a 2D image is plotted). */
     private regionOverlay;
     /** Pixel-tool plumbing: the plot div id, coord transform, and bound tool hosts. */
@@ -331,6 +348,19 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     /** (Re)install the physical scale bar over the 2D image, sized from the image's µm/pixel
      *  (`/tiles/info` mppX, falling back to the image metadata). No-op without a physical size. */
     private installScaleBar;
+    /**
+     * The overview navigator for a 2D view with an image: a coarse thumbnail of the whole
+     * image with the viewport on it; click or drag to pan at the current zoom (as OSD).
+     */
+    private installNavigator;
+    /**
+     * Draw the navigator's thumbnail from the coarsest pyramid level. A multichannel image
+     * is composited from its channels in their display colours, so the overview looks like
+     * the view rather than like channel 0 in grey.
+     */
+    private refreshNavigatorImage;
+    /** Show/hide the overview navigator (same setting as OSD's). */
+    setNavigatorVisible(visible: boolean): void;
     /** Convert a napari-js `Histogram` (bin count + min/max) to the pane's `IHistogram` (bin edges). */
     private toIHistogram;
     /**
@@ -421,6 +451,17 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
      * driven by drawn ROIs, so without the overlay there is no way to make a selection at all.
      */
     private mountSpatialOmics;
+    /**
+     * Whether the 2D observation 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 spatialPointsVisible;
+    /**
+     * The tiled-geometry manager, built on first use. Its host callbacks read this
+     * service's live state, so it never holds a stale dataset or colormap.
+     */
+    private spatialTiles;
     /**
      * Region drawing for the 3D cloud.
      *
@@ -838,7 +879,6 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     zoomIn(): void;
     zoomOut(): void;
     setDragMode(_mode: string | false): void;
-    setNavigatorVisible(_visible: boolean): void;
     setImageSmoothingEnabled(enabled: boolean): void;
     setShowStack(_showstack: boolean): void;
     setZIndex(zIndex: number): void;

package/lib/implementations/spatial-data-http/spatial-data-http.service.d.ts

@@ -1,7 +1,7 @@
 import { HttpClient } from '@angular/common/http';
 import { Observable } from 'rxjs';
-import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
-import { SpatialColumn, SpatialDataset, SpatialEmbedding, SpatialPolygons } from '../../contracts/spatial-dataset.contract';
+import { SpatialDataPort, TranscriptTileQuery } from '../../contracts/ports/spatial-data.port';
+import { SpatialColumn, SpatialDataset, SpatialDensityRaster, SpatialEmbedding, SpatialPolygonTile, SpatialPolygons, CategoricalColumnMeta, SpatialTranscriptCounts, SpatialTranscriptSummary, SpatialTranscriptTile } from '../../contracts/spatial-dataset.contract';
 import { SpatialDatasetSummary, SpatialManifest } from './spatial-wire';
 import * as i0 from "@angular/core";
 /**
@@ -58,6 +58,12 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     private static readonly CACHE_LIMIT;
     /** In-flight requests, so double-clicking a gene issues one fetch. */
     private readonly inFlight;
+    /**
+     * Tiles get their own, larger cache: panning revisits them constantly, and one screen
+     * of a zoomed-out section is dozens of them — far past the vector cache's limit.
+     */
+    private readonly tileCache;
+    private static readonly TILE_CACHE_LIMIT;
     private volumePromise;
     private polygonsPromise;
     constructor(http: HttpClient);
@@ -89,6 +95,24 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     getFeatureVector(name: string): Promise<Float32Array>;
     searchFeatures(query: string, limit?: number): Promise<string[]>;
     getPolygons(): Promise<SpatialPolygons>;
+    getPolygonTile(set: string, level: number, gx: number, gy: number): Promise<SpatialPolygonTile>;
+    getTranscriptTile(level: number, gx: number, gy: number, query: TranscriptTileQuery): Promise<SpatialTranscriptTile>;
+    getTranscriptBins(level: number, tx: number, ty: number): Promise<SpatialTranscriptTile>;
+    /** Small JSON answers, keyed by URL — hovering back and forth must not refetch. */
+    private readonly summaryCache;
+    getTranscriptSummary(query: {
+        box?: [number, number, number, number];
+        genes?: string[];
+        cells?: number[];
+    }): Promise<SpatialTranscriptSummary>;
+    getDensity(genes: string[], binSize?: number): Promise<SpatialDensityRaster>;
+    importGroups(label: string, table: string): Promise<{
+        column: CategoricalColumnMeta;
+        matched: number;
+    }>;
+    getTranscriptCounts(genes: string[]): Promise<SpatialTranscriptCounts>;
+    /** LRU over tile promises, so concurrent asks share one request and a failure is not kept. */
+    private cachedTile;
     /**
      * The reference volume's voxels, single-flighted like the polygons.
      *

package/lib/implementations/spatial-data-http/spatial-wire.d.ts

@@ -1,4 +1,4 @@
-import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialEmbedding, SpatialEmbeddingMeta, SpatialFeatureMeta, SpatialImageRef, SpatialObservations, SpatialPolygons, SpatialVolumeMeta } from '../../contracts/spatial-dataset.contract';
+import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialDensityMeta, SpatialDensityRaster, SpatialEmbedding, SpatialEmbeddingMeta, SpatialFeatureMeta, SpatialImageRef, SpatialObservations, SpatialPolygonTile, SpatialPolygonTilesMeta, SpatialPolygons, SpatialTranscriptBinsMeta, SpatialTranscriptBinsStatus, SpatialTranscriptTile, SpatialTranscriptTilesMeta, SpatialVolumeMeta } from '../../contracts/spatial-dataset.contract';
 /**
  * The wire format the bundled example server speaks, and its decoders.
  *
@@ -33,7 +33,18 @@ import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialEmbedding, Spa
  * GET {base}/spatial/{id}/feature/{name}   -> f32[N]
  * GET {base}/spatial/{id}/features?q=&limit= -> { names: string[] }
  * GET {base}/spatial/{id}/polygons         -> u32 count, u32[count+1] offsets, f32[2*rings] coords
+ * GET {base}/spatial/{id}/polygon-tile/{set}/{level}/{gx}/{gy}
+ *                                          -> u32 count, u32[count] obs, u32[count+1] offsets, f32 coords
+ * GET {base}/spatial/{id}/transcript-tile/{level}/{gx}/{gy}?genes=A,B&quality=high|all
+ *                                          -> see decodeTranscriptTile
+ * GET {base}/spatial/{id}/density?genes=A,B -> f32[rows*cols]
+ * GET {base}/spatial/{id}/transcript-bins/{level}/{tx}/{ty}
+ *                                          -> transcript-tile layout, one entry per bin
  * ```
+ *
+ * The three tiled routes are optional and advertised in the manifest
+ * (`polygonTiles`, `transcriptTiles`, `density`); a server without them never
+ * sees them requested.
  */
 /** Bumped when the layout changes incompatibly; the client refuses anything else. */
 export declare const SPATIAL_WIRE_VERSION = 1;
@@ -63,6 +74,11 @@ export interface SpatialManifest {
     volume?: SpatialVolumeMeta;
     embeddings?: SpatialEmbeddingMeta[];
     micronsPerUnit?: number;
+    polygonTiles?: SpatialPolygonTilesMeta;
+    transcriptTiles?: SpatialTranscriptTilesMeta;
+    density?: SpatialDensityMeta;
+    transcriptBins?: SpatialTranscriptBinsMeta;
+    transcriptBinsStatus?: SpatialTranscriptBinsStatus;
 }
 /** `GET /spatial/datasets` */
 export interface SpatialDatasetSummary {
@@ -104,6 +120,23 @@ export declare function decodeColumn(buf: ArrayBuffer, meta: SpatialColumnMeta,
  * field is 4-byte wide so each typed-array view stays aligned.
  */
 export declare function decodePolygons(buf: ArrayBuffer): SpatialPolygons;
+/**
+ * `GET /polygon-tile/...` → one tile of rings with their owning observations. Layout
+ * `[u32 count][u32 obs × count][u32 offsets × (count+1)][f32 coords × 2·offsets[count]]`.
+ */
+export declare function decodePolygonTile(buf: ArrayBuffer): SpatialPolygonTile;
+/**
+ * `GET /transcript-tile/...` → transcripts or aggregates. Layout, 4-byte aligned:
+ * `[u32 n][u32 flags][f32 x·n][f32 y·n][f32 z·n][u32 weight·n][u32 obs·n][u16 gene·n, padded]`;
+ * flags bit 0 marks an aggregated level.
+ */
+export declare function decodeTranscriptTile(buf: ArrayBuffer): SpatialTranscriptTile;
+/**
+ * `GET /density?genes=&bin=` → the summed raster. Layout
+ * `[u32 rows][u32 cols][f32 cellW][f32 cellH][f32 originX][f32 originY][f32 rows·cols]`:
+ * the geometry travels with the values because re-binning changes it.
+ */
+export declare function decodeDensity(buf: ArrayBuffer, genes: string[]): SpatialDensityRaster;
 /**
  * Fold a manifest plus its fetched coordinate/id/radius vectors into the
  * library-facing {@link SpatialDataset}. Column and feature *values* are not

package/lib/spatial/spatial-tiles.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Level-of-detail planning for tiled spatial geometry — cell outlines and transcripts.
+ *
+ * The renderer knows its camera (a world-space centre, a zoom in canvas pixels per world
+ * unit, a canvas size); a tiled dataset knows its grids (one per level, in observation
+ * units). This module is the bridge: which level the zoom calls for, which tiles are on
+ * screen, how big a transcript marker should be. Everything here is pure, so the policy
+ * — the part that decides whether the view is fast and legible — is testable without a
+ * GPU.
+ *
+ * Observation units map onto world units through the dataset's `imageRef` affine
+ * (`world = data · scale + translate`), so "pixels per observation unit" is
+ * `zoom · scale`. For a Xenium bundle the data unit is the micron and the world unit the
+ * morphology pixel.
+ */
+import type { SpatialBounds, SpatialImageRef, SpatialTileLevel } from '../contracts/spatial-dataset.contract';
+import type { SpatialViewState } from '../contracts/display-types';
+import type { SpatialDataset } from '../contracts/spatial-dataset.contract';
+/** A rectangle in observation coordinates. */
+export interface DataRect {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** Tile address. */
+export interface TileKey {
+    level: number;
+    gx: number;
+    gy: number;
+}
+/** Whether cell outlines are drawn: the user's choice, else on when the dataset has any. */
+export declare function cellsShown(dataset: Pick<SpatialDataset, 'polygonTiles' | 'polygons'> | null, view: Pick<SpatialViewState, 'showCells'>): boolean;
+/** A column holding a hand-curated cell-type annotation, by naming convention. */
+export declare function isCuratedColumn(name: string): boolean;
+/**
+ * The categorical column that names each cell's type: the view's choice when it is a
+ * column of this dataset, else the first categorical column that is not a curated
+ * annotation (a pipeline's clustering is the default; curation is opted into), else
+ * any categorical column.
+ */
+export declare function cellTypeColumnFor(dataset: SpatialDataset, view: Pick<SpatialViewState, 'cellTypeColumn'>): string | null;
+export declare function tileId(k: TileKey): string;
+/** Canvas pixels per observation unit along x, for a camera zoom and a data→world affine. */
+export declare function pixelsPerDataUnit(zoom: number, ref?: SpatialImageRef | null): number;
+/**
+ * The part of observation space the camera shows, padded by `margin` (a fraction of the
+ * viewport) so tiles just off screen are already there when a pan brings them in.
+ */
+export declare function visibleDataRect(center: readonly [number, number], zoom: number, canvasW: number, canvasH: number, ref?: SpatialImageRef | null, margin?: number): DataRect | null;
+/**
+ * Tiles of one level intersecting `rect`, clipped to the dataset's `bounds` (so zooming
+ * out over empty canvas does not ask for tiles that cannot exist). Ordered from the
+ * rectangle's centre outward, so the middle of the screen fills in first.
+ */
+export declare function tilesInRect(rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
+/**
+ * Typical cell diameter, in observation units, used to judge how large cells appear.
+ * Derived from the per-observation radius when there is one; 12 µm otherwise.
+ */
+export declare function typicalCellDiameter(radius: Float32Array | number | undefined, fallback?: number): number;
+/**
+ * On-screen cell diameter (px) at or above which each polygon level is used. A level
+ * halves the vertices of the one below, so each should take over when the cell is about
+ * half as large on screen. Below the last finite threshold outlines are not drawn at
+ * all — a cell a few pixels wide is a dot, and the observation markers already draw it
+ * as one.
+ *
+ * Xenium's fourth level (3 vertices per cell) is deliberately never used: seen on
+ * screen it is a field of triangles, which reads as an artefact rather than as cells.
+ * The dots below 8 px say the same thing more honestly.
+ */
+export declare const POLYGON_LEVEL_MIN_CELL_PX: number[];
+/**
+ * Which polygon level suits this zoom, or -1 for "too small to outline".
+ * `detail` > 1 prefers finer levels (sharper, slower); < 1 coarser.
+ */
+export declare function polygonLevelFor(pxPerUnit: number, cellDiameter: number, levelCount: number, detail?: number): number;
+/**
+ * Which transcript level suits this zoom: the one whose tiles come out closest to
+ * `targetTilePx` on screen. Coarser levels aggregate more, so this keeps the number of
+ * markers per screen roughly constant however far out the camera is — the property that
+ * keeps the view fast.
+ */
+export declare function transcriptLevelFor(pxPerUnit: number, levels: readonly SpatialTileLevel[], targetTilePx?: number): number;
+/** Smallest and largest transcript marker, in canvas pixels. */
+export declare const TRANSCRIPT_MIN_PX = 4;
+export declare const TRANSCRIPT_MAX_PX = 32;
+/**
+ * Physical diameter a single transcript is drawn at, in µm — clearly larger than the
+ * imaged spot (~0.3 µm) so it stays legible, and small enough that neighbouring
+ * molecules inside one cell stay apart.
+ */
+export declare const TRANSCRIPT_PHYSICAL_UM = 1.2;
+/**
+ * Marker diameter in canvas pixels for an entry standing for `weight` transcripts.
+ *
+ * The convention spatial viewers share (deck.gl's `radiusMinPixels`/`radiusMaxPixels`,
+ * Xenium Explorer's transcript size): a PHYSICAL size, clamped to a screen-pixel range.
+ * Zoomed out, markers sit at the minimum and never vanish; zoomed in, they grow with the
+ * tissue instead of shrinking to specks next to cells hundreds of pixels wide. A fixed
+ * screen size does the opposite at high zoom, which is what made transcripts disappear
+ * at pixel-level zoom.
+ *
+ * Aggregates grow with the cube root of their count: area ∝ count would let one dense
+ * aggregate swallow its neighbours, the cube root keeps a 1000-transcript cluster clearly
+ * larger than a 10-transcript one without covering the tile.
+ *
+ * `pxPerMicron` is omitted for data with no known physical unit; the marker is then
+ * screen-sized only.
+ */
+export declare function transcriptMarkerPx(weight: number, scale?: number, pxPerMicron?: number): number;
+/** Marker shapes for the transcript "icon" mode. All star-convex, so a fan fills them. */
+export declare const TRANSCRIPT_GLYPHS: readonly ["circle", "star", "triangle", "square", "diamond", "cross", "hexagon", "triangle-down", "pentagon", "x"];
+export type TranscriptGlyph = typeof TRANSCRIPT_GLYPHS[number];
+/** Unit outline of a glyph, radius ≈ 1, centred on the origin, as `[x0, y0, x1, y1, …]`. */
+export declare function glyphOutline(glyph: TranscriptGlyph): Float32Array;
+/** The glyph a gene gets by default: by its position in the selected list. */
+export declare function defaultGlyphFor(slot: number): TranscriptGlyph;
+/**
+ * Expand point markers into glyph rings for a shapes layer: entry `i` becomes a copy of
+ * `glyphs[gene[i]]` scaled to `radius[i]` and centred on `(x[i], y[i])`.
+ */
+export declare function glyphRings(x: Float32Array, y: Float32Array, radius: Float32Array, glyphOf: (i: number) => Float32Array): {
+    coords: Float32Array;
+    offsets: Uint32Array;
+};
+/**
+ * A shapes layer colours through a colormap LUT, not per-shape RGBA. A categorical
+ * palette becomes a piecewise-constant colormap: category `c` of `n` owns the band
+ * `[c/n, (c+1)/n)`, and a shape takes the value at its band's centre, so the LUT's
+ * linear filtering never blends two categories.
+ *
+ * Returns the stops (linear 0..1 RGB) and a function mapping a category code to the
+ * value to hand the layer. `missing` is the colour of the extra band used for "no
+ * category".
+ */
+export declare function discreteColormapStops(rgb: readonly (readonly [number, number, number])[], missing: readonly [number, number, number]): {
+    stops: {
+        t: number;
+        color: [number, number, number];
+    }[];
+    valueOf: (code: number) => number;
+};
+/**
+ * Separable Gaussian blur of a row-major raster, `sigma` in raster cells.
+ *
+ * A per-gene count raster at 10 µm is mostly zeros and ones — drawn as-is it is speckle,
+ * not a density. A σ of one to two cells (10–20 µm, about a cell diameter) turns it into
+ * a field that reads as territory while keeping structures a few cells wide.
+ */
+export declare function smoothRaster(values: Float32Array, rows: number, cols: number, sigma: number): Float32Array;
+/**
+ * Colour a density raster as RGBA bytes: log-scaled, windowed at a high percentile of the
+ * non-zero values, and faded in from transparent so empty tissue shows what is under it.
+ */
+export declare function colorDensity(values: Float32Array, lut: readonly (readonly [number, number, number])[], opacity: number, { log, percentile }?: {
+    log?: boolean | undefined;
+    percentile?: number | undefined;
+}): Uint8Array;
+/** Smallest on-screen spacing between groups, in px — below it groups read as noise. */
+export declare const GROUP_MIN_SPACING_PX = 14;
+/** Area of `rect` inside `bounds` (the whole rect when there are none). */
+export declare function visibleArea(rect: DataRect, bounds?: SpatialBounds | null): number;
+export type AllGenesPlan = {
+    kind: 'individual';
+} | {
+    kind: 'bins';
+    level: number;
+} | {
+    kind: 'none';
+};
+/**
+ * How to draw every transcript in view without exceeding `budget` markers.
+ *
+ * - The transcripts themselves, once the estimated count in view fits the budget.
+ * - Otherwise the finest pyramid level whose bins are at least `minSpacingPx` apart on
+ *   screen and number no more than the budget — groups big enough to read, few enough
+ *   to draw.
+ *
+ * The count in view is estimated from the average density, which over- or under-shoots
+ * locally; the renderer still caps what it draws, so an estimate is enough to choose.
+ */
+export declare function allGenesPlan(o: {
+    rect: DataRect;
+    bounds: SpatialBounds;
+    total: number;
+    pxPerUnit: number;
+    levels: readonly {
+        binSize: number;
+    }[];
+    budget: number;
+    canIndividual: boolean;
+    minSpacingPx?: number;
+}): AllGenesPlan;
+/**
+ * Diameter in px of a group of `count` transcripts in a bin `binPx` wide, where
+ * `refCount` is a typical busy bin in view (its 95th percentile).
+ *
+ * Area grows with the count — a bin with a quarter of the transcripts gets half the
+ * diameter — between a third of the bin (so a sparse bin is still visible) and a little
+ * over the full bin (so dense neighbours just touch rather than pile up).
+ */
+export declare function groupedMarkerPx(count: number, refCount: number, binPx: number, scale?: number): number;
+/** The `p` quantile (0..1) of a count vector — a sample of it for large vectors. */
+export declare function quantileOf(values: ArrayLike<number>, p: number): number;
+/** {@link tilesInRect} for a grid whose tile (0, 0) starts at `origin`. */
+export declare function tilesInRectFrom(origin: readonly [number, number], rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
+/** A density window from the non-empty bins: 1st to 99th percentile. */
+export declare function densityAutoRange(values: ArrayLike<number>): [number, number];
+/**
+ * Colour density bins through `lut` over the window `[lo, hi]` — Xenium Explorer's
+ * "scale threshold". Bins at or below `lo` are transparent, so empty tissue shows the
+ * image under it; bins at or above `hi` saturate.
+ */
+export declare function colorDensityWindow(values: ArrayLike<number>, lut: readonly (readonly [number, number, number])[], opacity: number, lo: number, hi: number): Uint8Array;
+/**
+ * Inferno (matplotlib), as an inline `[stop, colour]` scale: the density map's default,
+ * as in Xenium Explorer. Inline because the colormap tree's `INFERNO_LUT` key is resolved
+ * at runtime by the store, which the renderer does not see.
+ */
+export declare const INFERNO_SCALE: [number, string][];