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

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

@@ -1,14 +1,14 @@
 /**
- * What is under the cursor, and what to say about it.
+ * What to say about the observation under the cursor.
  *
  * A coloured cloud answers "how is this annotation distributed"; it cannot answer
  * "which class is THAT" — the legend has 34 entries, several of them similar
  * colours, and matching a dot to a swatch by eye is exactly the task a tooltip
  * exists to remove.
  *
- * Pure — no DOM, no camera, no data access. The renderer supplies screen
- * positions (it owns the projection) and the active colour source; everything
- * here is arithmetic and string formatting, so it is tested directly.
+ * Pure — no DOM, no camera, no data access. Finding the observation is the
+ * renderer's (napari-js picks on the layers it drew); this is string formatting
+ * over the active colour source, so it is tested directly.
  */
 /** The colour source a tooltip describes, as the renderer already has it. */
 export type HoverSource = {
@@ -26,18 +26,6 @@ export type HoverSource = {
     /** Unit for the value, when the dataset declares one. */
     unit?: string;
 };
-/**
- * Index of the drawn observation nearest `(x, y)` within `maxDist` screen pixels,
- * or -1.
- *
- * `screen` is `[x0, y0, x1, y1, …]` indexed BY OBSERVATION, with NaN for anything
- * not currently drawn — off screen, behind the eye, or on a hidden section. NaN
- * fails every comparison, so those are skipped without a special case.
- *
- * Ties go to the LATER observation, which is the one drawn on top and therefore
- * the one the user believes they are pointing at.
- */
-export declare function nearestObservation(screen: Float32Array, x: number, y: number, maxDist: number): number;
 /**
  * The tooltip's lines for one observation: what it is, then which column said so.
  *

package/lib/spatial/spatial-panel-model.d.ts

@@ -0,0 +1,135 @@
+import type { CategoricalColumnMeta, SpatialColumnMeta, SpatialDataset, SpatialMarkerGenes } from '../contracts/spatial-dataset.contract';
+import type { SpatialCategoricalView } from '../contracts/visualizer.contract';
+import type { ColormapValue, SpatialViewState, TranscriptGlyphName } from '../contracts/display-types';
+import type { Rgb } from '../contracts/colormap-lut';
+/**
+ * Pure model of the spatial-omics panel: the option lists, rows and patches its controls
+ * show and write, as functions of the dataset and the view. No Angular and no state, so
+ * every rule here is unit-tested without a TestBed and shared by whichever panel shows it.
+ */
+/** A labelled dropdown option. */
+export interface PanelOption<T> {
+    label: string;
+    value: T;
+}
+/** A gene name as a dropdown option. Objects rather than bare strings because the
+ *  dropdown filters on a named field (`filterBy="label"`), which a string has not. */
+export declare function geneOption(name: string): PanelOption<string>;
+/** A transcript glyph choice, with an SVG `points` string for its preview. */
+export interface GlyphOption extends PanelOption<TranscriptGlyphName> {
+    points: string;
+}
+/** Glyph choices with an SVG `points` string for the preview. */
+export declare const GLYPH_OPTIONS: GlyphOption[];
+/** The preview outline of `glyph`, or `''` for an unknown one. */
+export declare function glyphPoints(glyph: TranscriptGlyphName): string;
+/** Outlier clipping presets, as `[lo, hi]` percentile fractions. */
+export declare const CLIP_OPTIONS: PanelOption<[number, number]>[];
+/**
+ * `group,gene` rows (CSV or TSV, header optional) → gene groups, in file order.
+ */
+export declare function parseGeneGroups(text: string): {
+    name: string;
+    genes: string[];
+}[];
+/** `name — 2 categories` / `name — counts`: a column as the pickers list it. */
+export declare function columnLabel(c: SpatialColumnMeta): string;
+/** Colour-by column choices — "None" plus every column the dataset declares. */
+export declare function columnOptions(ds: SpatialDataset | null): PanelOption<string | null>[];
+/** The option lists of the cell and transcript controls, which depend on the dataset only. */
+export interface TileOptions {
+    cellSetOptions: PanelOption<string>[];
+    transcriptModeOptions: PanelOption<SpatialViewState['transcriptMode']>[];
+    cellColorOptions: PanelOption<SpatialViewState['cellColorMode']>[];
+}
+/** {@link TileOptions} for `ds`: short labels, cell set first, "Both" when there are two —
+ *  as Xenium Explorer. */
+export declare function tileOptions(ds: SpatialDataset | null): TileOptions;
+/** A section of the group picker. */
+export interface GroupOptionSection {
+    label: string;
+    items: PanelOption<string>[];
+}
+/** The value the group picker uses for a family of columns. */
+export declare const FAMILY_PREFIX = "family:";
+/**
+ * The group picker: categorical columns under their section heading, a family of
+ * variants (k-means at k = 2…10) listed once. Values are a column name, or
+ * `family:<id>` for a family. The segmentation method is not a grouping of cells.
+ */
+export declare function groupOptions(ds: SpatialDataset | null): GroupOptionSection[];
+/** The group picker's value for the active group column: its family's entry, or itself. */
+export declare function groupEntryFor(ds: SpatialDataset | null, column: string | null): string | null;
+/** The columns of family `id`, in dataset order. */
+export declare function familyMembers(ds: SpatialDataset | null, id: string): CategoricalColumnMeta[];
+/** Variants of the active column's family (k = 2…10), or none when it has no family. */
+export declare function groupVariantOptions(ds: SpatialDataset | null, column: string | null): PanelOption<string>[];
+/** One row of the groups list: a category with its colour and cell count. */
+export interface GroupRow {
+    label: string;
+    color: string;
+    count: number;
+}
+/** A grouping's categories with colours and cell counts, largest first, and their total. */
+export declare function countGroupRows(v: Pick<SpatialCategoricalView, 'categories' | 'colors' | 'codes'>): {
+    rows: GroupRow[];
+    total: number;
+};
+/** `list` with `items` removed (`on`) or added (`!on`) — a hidden-set toggle. */
+export declare function toggleHidden(list: readonly string[], items: readonly string[], on: boolean): string[];
+/** One node of the selected-genes tree: a named gene group, or the ungrouped rest (`null`). */
+export interface GeneTreeNode {
+    name: string | null;
+    genes: string[];
+}
+/** The selected genes as Explorer's tree: named groups, then the ungrouped ones. */
+export declare function buildGeneTree(selected: readonly string[], groups: readonly {
+    name: string;
+    genes: readonly string[];
+}[]): GeneTreeNode[];
+/** Every categorical column but the segmentation method, which says nothing about genes. */
+export declare function markerColumnOptions(columns: readonly SpatialColumnMeta[] | undefined): PanelOption<string>[];
+/**
+ * Each picked cluster's marker genes as a gene group named after it. A gene that marks
+ * several clusters goes to the one it scores highest in, so the tree lists it once;
+ * clusters left with no gene are dropped.
+ */
+export declare function markerGeneGroups(result: Pick<SpatialMarkerGenes, 'groups'>, picked: ReadonlySet<string>): {
+    name: string;
+    genes: string[];
+}[];
+/** `groups` merged into the view's gene groups (replacing any of the same name). */
+export declare function withGeneGroups(view: Pick<SpatialViewState, 'transcriptGeneGroups'>, groups: {
+    name: string;
+    genes: string[];
+}[]): SpatialViewState['transcriptGeneGroups'];
+/**
+ * The patch that adds marker groups: the groups, their genes appended to the selection,
+ * transcripts coloured by cluster (as their cells are), and switched on when off.
+ */
+export declare function markerGenesPatch(view: Pick<SpatialViewState, 'transcriptGeneGroups' | 'transcriptGenes' | 'transcriptMode'>, groups: {
+    name: string;
+    genes: string[];
+}[]): Partial<SpatialViewState>;
+/** The patch that imports gene groups: the groups, and their genes added to the selection. */
+export declare function importGeneGroupsPatch(view: Pick<SpatialViewState, 'transcriptGeneGroups' | 'transcriptGenes'>, groups: {
+    name: string;
+    genes: string[];
+}[]): Partial<SpatialViewState>;
+/** `linear-gradient(...)` sampling `lut` at `steps + 1` evenly spaced stops. */
+export declare function gradientCss(lut: readonly Rgb[], steps?: number): string;
+/**
+ * The continuous colour bar, resolved exactly the way the renderer resolves its colours —
+ * the same override, the same grey fallback. Built from `lutFor` alone, this bar showed a
+ * black-to-white ramp while the canvas drew Viridis, which makes the key worse than none.
+ */
+export declare function continuousColorBarCss(colormap: unknown, reverse: boolean, override: ColormapValue | null): string;
+/** The density map's colour bar: its own colormap, Inferno by default. */
+export declare function densityColorBarCss(colormap: SpatialViewState['densityColormap']): string;
+/** The middle of a section stack: where a "one section" picker opens, rather than on the
+ *  first section, which for a brain is a nearly empty olfactory-bulb slide. */
+export declare function middleSection(sections: ArrayLike<number> | null): number;
+/** "12 of 53" — 1-based, because the sections are slides, not array slots; `''` with none. */
+export declare function sectionLabel(sections: ArrayLike<number> | null, at: number | null): string;
+/** Why "All genes" is not offered yet, while the server builds its pyramid; null otherwise. */
+export declare function allGenesPreparingNote(ds: SpatialDataset | null): string | null;

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

@@ -1,5 +1,6 @@
 import { Region } from '../models/region';
-import { SpatialImageRef, SpatialObservations } from '../contracts/spatial-dataset.contract';
+import { RingBounds as Bounds } from '../geometry/ring';
+import { SpatialImageRef, SpatialObservations, SpatialSelectionMask } from '../contracts/spatial-dataset.contract';
 /**
  * Which observations fall inside a set of drawn regions.
  *
@@ -19,11 +20,8 @@ import { SpatialImageRef, SpatialObservations } from '../contracts/spatial-datas
  * dataset's own frame and reach the world through `imageRef` — so they are
  * transformed forward before testing, matching exactly what the renderer draws.
  */
-/** A selection over N observations: `mask[i] === 1` when i is selected. */
-export interface SpatialSelectionMask {
-    mask: Uint8Array;
-    count: number;
-}
+/** Moved to the dataset contract (a pure data type); re-exported here for existing importers. */
+export type { SpatialSelectionMask };
 /** An empty selection over `count` observations. */
 export declare function emptySelection(count?: number): SpatialSelectionMask;
 /** Number of set entries in a mask. */
@@ -36,15 +34,13 @@ export declare function maskToIndices(mask: Uint8Array): Uint32Array;
  * unselected observation is muted — the CosMx highlight-vs-mute rule.
  */
 export declare function mutedFromSelection(selection: SpatialSelectionMask): Uint8Array | null;
-/** Even-odd ray cast: is (px, py) inside the closed ring xs/ys? */
+/**
+ * Even-odd ray cast: is (px, py) inside the closed ring xs/ys?
+ *
+ * Public API kept with its (ring, point) argument order; the test itself is
+ * the shared `geometry/ring` one the region overlays and tools use.
+ */
 export declare function pointInRing(xs: readonly number[], ys: readonly number[], px: number, py: number): boolean;
-/** Axis-aligned bounds of a ring, for a cheap reject before the ray cast. */
-interface Bounds {
-    minX: number;
-    minY: number;
-    maxX: number;
-    maxY: number;
-}
 /** A region flattened to something testable: bounds + a hit test. */
 interface Shape {
     bounds: Bounds;
@@ -56,6 +52,16 @@ interface Shape {
  * rectangle — so those never contribute to a selection.
  */
 export declare function regionShapes(region: Region): Shape[];
+/**
+ * A selection from an explicit list of observation indices.
+ *
+ * What a lasso in a linked plot produces: the plot knows which points the user drew
+ * around, and the map needs that as a mask over ALL observations. Out-of-range and
+ * duplicate indices are ignored rather than rejected — a plot may hand back the same
+ * point twice, and a stale index from a plot drawn before a dataset change must not
+ * throw in the middle of a selection gesture.
+ */
+export declare function selectByIndices(indices: Iterable<number>, observationCount: number): SpatialSelectionMask;
 /**
  * Observations inside ANY of `regions` (union). Coordinates are transformed by
  * `imageRef` first, so the test happens in the same world space the regions were
@@ -68,16 +74,6 @@ export declare function regionShapes(region: Region): Shape[];
  * indexed by observation, so every consumer (charts, legend, the 3D cloud) reads it
  * the same way.
  */
-/**
- * A selection from an explicit list of observation indices.
- *
- * What a lasso in a linked plot produces: the plot knows which points the user drew
- * around, and the map needs that as a mask over ALL observations. Out-of-range and
- * duplicate indices are ignored rather than rejected — a plot may hand back the same
- * point twice, and a stale index from a plot drawn before a dataset change must not
- * throw in the middle of a selection gesture.
- */
-export declare function selectByIndices(indices: Iterable<number>, observationCount: number): SpatialSelectionMask;
 export declare function selectInRegions(observations: SpatialObservations, imageRef: SpatialImageRef | undefined, regions: readonly Region[], candidates?: Uint32Array): SpatialSelectionMask;
 /**
  * Select observations whose SCREEN projection falls inside the drawn regions.
@@ -99,7 +95,6 @@ export declare function selectInRegions(observations: SpatialObservations, image
  * never selected.
  */
 export declare function selectInRegionsProjected(screen: Float32Array, count: number, regions: readonly Region[]): SpatialSelectionMask;
-/** Every observation whose categorical code equals `code` — the legend click. */
 /**
  * Whether two selections hold exactly the same observations.
  *
@@ -109,5 +104,5 @@ export declare function selectInRegionsProjected(screen: Float32Array, count: nu
  * Counts are compared first, so two different selections usually cost nothing.
  */
 export declare function sameSelection(a: SpatialSelectionMask, b: SpatialSelectionMask): boolean;
+/** Every observation whose categorical code equals `code` — the legend click. */
 export declare function selectByCategory(codes: Uint16Array, code: number): SpatialSelectionMask;
-export {};

package/lib/spatial/spatial-tile-merge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Merging and filtering of the spatial-tile wire format (observation ids, NO_CATEGORY): the
+ * pieces of the 2D view's tile loop that are pure — concatenating tiles, dropping hidden
+ * groups and genes, and the density-grid markers of a zoomed-out gene selection.
+ *
+ * These work on SIV's own tile contract, so they stay in SIV rather than moving to napari-js.
+ */
+import type { SpatialViewState } from '../contracts/display-types';
+import { SpatialDensityRaster, SpatialPolygonTile, SpatialTranscriptTile } from '../contracts/spatial-dataset.contract';
+import type { DataRect } from './lod';
+/** Rings whose owning cell is in a switched-off group removed. */
+export declare function filterRings(rings: SpatialPolygonTile, hidden: {
+    codes: Uint16Array;
+    hidden: Uint8Array;
+} | null): SpatialPolygonTile;
+/** Slots (indices into the selected genes) switched off with their eye toggle. */
+export declare function hiddenGeneSlots(view: SpatialViewState): Uint8Array | null;
+/** 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;
+};
+/** The median of `v`, from a sample of about 1024 values. */
+export declare function median(v: Float32Array): number;
+/** 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;
+};

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

@@ -1,259 +1,12 @@
 /**
- * Level-of-detail planning for tiled spatial geometry — cell outlines and transcripts.
+ * Spatial tile helpers, re-exported from the modules they now live in.
  *
- * 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, SpatialTranscriptTile } 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;
-/**
- * The bin a selection of genes is grouped into at this zoom, in observation units, or null
- * to draw every transcript. Bins follow the all-gene pyramid's ladder (`baseBin` × 2^m) so a
- * gene selection and "all genes" group alike: the finest bin whose markers land at least
- * `spacingPx` apart on screen. Once the finest bin is that wide, transcripts are drawn as
- * themselves.
- */
-export declare function geneBinSize(pxPerUnit: number, baseBin: number, levels?: number, spacingPx?: number): number | null;
-/** The entries of `t` inside `rect` (observation units). */
-export declare function clipTranscripts(t: SpatialTranscriptTile, rect: DataRect): SpatialTranscriptTile;
-/**
- * Group transcripts into `bin`-wide squares of a grid anchored at the origin (so a pan does
- * not move them), one entry per (group, square): `groupOf(gene slot)` says which group a gene
- * is in — its cluster in the gene tree, or itself. Each entry sits at its transcripts'
- * centroid, weighted by how many each stands for; it takes the gene and the cell holding most
- * of them, each summed over all its transcripts in the entry. `group[i]` is entry i's group.
- */
-export declare function groupTranscripts(t: SpatialTranscriptTile, bin: number, groupOf?: (geneSlot: number) => number): {
-    tile: SpatialTranscriptTile;
-    group: Int32Array;
-};
-/**
- * The colour of each gene-tree cluster of a selection, for colouring transcripts by cluster: a
- * cluster named like a group of the cells' grouping takes that group's colour (its cells and its
- * transcripts agree); the others take palette colours in tree order. Clusters are the tree's
- * groups holding a selected gene, then each ungrouped selected gene on its own. Every gene of a
- * cluster gets the same colour — the tree's swatches and the markers use this one map.
- */
-export declare function clusterColorMap(genes: readonly string[], groups: readonly {
-    name: string;
-    genes: readonly string[];
-}[], cellColors: ReadonlyMap<string, string>, palette: readonly string[]): Map<string, string>;
-/** The cluster a selected gene is in: its first gene-tree group holding it, else itself. */
-export declare function clusterOfGene(gene: string, groups: readonly {
-    name: string;
-    genes: readonly string[];
-}[]): string;
-/** 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.
+ * @deprecated Kept for one release so existing imports keep working. Import from
+ * `./lod` (level of detail, tiles in view), `./transcript-grouping` (grouping, marker
+ * sizing, cluster colours), `./glyphs` (transcript icons) or `./density-raster` (density
+ * window and scale) instead.
  */
-export declare const INFERNO_SCALE: [number, string][];
+export * from './lod';
+export * from './transcript-grouping';
+export * from './glyphs';
+export * from './density-raster';

package/lib/spatial/stats.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Percentiles for the spatial code: one "collect, sort, index" routine instead of one per
+ * caller.
+ *
+ * The callers used to differ in rounding (`round(p·(n-1))` against `floor(p·n)`), in
+ * sampling and in filtering, so windows computed for the same data in different views
+ * could disagree. Here there is one rule for each:
+ *
+ *  - **Rank**: `round(p·(n-1))` — the nearest rank. `floor(p·n)` is biased upward and
+ *    hands back the maximum for `p = 0.99` on a hundred values, outlier included.
+ *  - **Sort**: a typed-array sort, which is native and numeric — several times faster
+ *    than a comparator sort of a boxed `number[]`, and far lighter on the heap.
+ *  - **Sample**: past `2·sampleSize` qualifying values, every `floor(count/sampleSize)`-th
+ *    one, which is plenty for a display window and keeps a 3.7M-cell recolour from
+ *    sorting 3.7M values.
+ */
+export interface QuantileOptions {
+    /** Which values count: every finite one (the default), or only those above zero. */
+    filter?: 'finite' | 'positive';
+    /** Count index `i` only where `where[i] > 0` — e.g. a field's support. */
+    where?: ArrayLike<number>;
+    /** Sample down to about this many values (see the module doc); unsampled when absent. */
+    sampleSize?: number;
+}
+/**
+ * The `ps` quantiles (each 0..1, clamped) of the values that qualify, or null when none do.
+ */
+export declare function quantiles(values: ArrayLike<number>, ps: readonly number[], opts?: QuantileOptions): number[] | null;
+/** One quantile; see {@link quantiles}. */
+export declare function quantile(values: ArrayLike<number>, p: number, opts?: QuantileOptions): number | null;
+/** Sample size for a contrast window: a display window does not need every value. */
+export declare const WINDOW_SAMPLE_SIZE = 65536;
+/**
+ * A `[lo, hi]` percentile window over the qualifying values, never flat or inverted
+ * (a flat window would divide by zero downstream, so it is widened by one), and `[0, 1]`
+ * when nothing qualifies, so callers always get a usable window.
+ */
+export declare function percentileWindow(values: ArrayLike<number>, lo: number, hi: number, opts?: QuantileOptions): [number, number];