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

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

@@ -27,6 +27,7 @@ export interface DensityGrid {
     /** World size of one voxel per axis, in the observations' units. */
     voxelSize: [number, number, number];
 }
+/** Kernel and observation subset for a density estimate. */
 export interface DensityOptions {
     /** Kernel σ per axis, in the observations' units. */
     sigma: [number, number, number];
@@ -44,12 +45,21 @@ export interface DensityOptions {
  */
 export declare function densityGrid(dataset: SpatialDataset, stride?: number, targetLongAxis?: number, zStride?: number): DensityGrid | null;
 /**
- * In-place separable Gaussian along one axis of a w x h x d field.
+ * A normalised 1-D Gaussian kernel of radius `ceil(3σ)` (at least 1), centre at
+ * index `radius`.
+ */
+export declare function gaussianKernel(sigma: number): {
+    kernel: Float32Array;
+    radius: number;
+};
+/**
+ * In-place separable Gaussian along one axis of a w x h x d field. A 2-D field is
+ * the `d = 1` case.
  *
- * Exported because the gene-map volume estimates a different quantity on the same
- * lattice with the same kernel (see `spatial-expression.ts`): two copies of a
- * separable blur would be two chances to smooth the estimate and its normaliser
- * differently, which is the one thing a Nadaraya-Watson field cannot survive.
+ * The ONE blur for every field in this folder: the 2-D gene map, the gene-map
+ * volume and the density volumes all smooth through it. Two copies of a separable
+ * blur would be two chances to smooth an estimate and its normaliser differently,
+ * which is the one thing a Nadaraya-Watson field cannot survive.
  */
 export declare function blurVolumeAxis(field: Float32Array, w: number, h: number, d: number, axis: 0 | 1 | 2, sigmaVox: number): void;
 /**

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

@@ -19,45 +19,16 @@ import { ColormapValue } from '../contracts/display-types';
  *
  * COLOUR REPRESENTATION
  * ---------------------
- * Internally everything is a flat `Float32Array` of `[r,g,b,a, …]` in 0..1 —
- * one allocation for N points, GPU-upload shaped. napari-js 0.12.0's
- * `PointsLayer.faceColor` takes `RGBA[]` (an array of 4-tuples) instead, so
- * {@link toRgbaTuples} adapts at the boundary; when the layer accepts a typed
- * array the adapter goes away and the flat buffer is passed straight through.
+ * Everything is a flat `Float32Array` of `[r,g,b,a, …]` in 0..1 — one
+ * allocation for N points, GPU-upload shaped. napari-js (≥ 0.15)
+ * `PointsLayer.faceColor` and `Points3DLayer.colors` take it as is.
  */
-/** napari-js per-point colour tuple: r, g, b, a in 0..1. */
+/** One RGBA colour, r, g, b, a in 0..1 (napari-js's broadcast colour). */
 export type RGBA = [number, number, number, number];
 /** Neutral grey for observations with no value (NaN, or {@link NO_CATEGORY}). */
 export declare const MISSING_COLOR: Rgb;
 /** Default alpha for muted (background / unselected) points — CosMx-style context. */
 export declare const DEFAULT_MUTED_OPACITY = 0.15;
-/**
- * Largest number of CATEGORIES whose colours survive the 3D points layer's LUT
- * intact.
- *
- * That layer has no per-point RGBA — it maps a per-point SCALAR through a
- * 256-entry colormap LUT — so a categorical palette is encoded as one contiguous
- * block of LUT entries per value. Measured against napari-js, every K in 2..96
- * blocks round-trips exactly and K=97 is the first that does not: 256 texels
- * cannot keep more values apart than that.
- *
- * One of those 96 blocks is spent on {@link NO_CATEGORY}, which every column can
- * contain, so what fits is **95 categories** — the number published here. It was
- * 96 while the encoder rejected at 96, which meant a 96-category column drew flat
- * with the panel showing no warning: the one failure this ceiling exists to
- * prevent, arrived at from the other direction.
- *
- * Above it the cloud draws FLAT rather than draw a lie, because subtly wrong
- * category colours under a confident legend is the failure nobody catches.
- *
- * A limit of that one layer, and of nothing else: the 2D markers carry per-point
- * RGBA, and a density volume is a scalar field per cluster. Shared here so the
- * renderer that enforces it and the panel that explains it cannot drift apart.
- */
-export declare const SPATIAL_3D_MAX_CATEGORIES = 95;
-/** LUT blocks the 3D layer can keep apart — {@link SPATIAL_3D_MAX_CATEGORIES}
- *  plus the one reserved for a missing value. */
-export declare const SPATIAL_3D_LUT_BLOCKS: number;
 /**
  * Fallback categorical palette. Colour-blind-safe and stable, so a category
  * without an authored colour still lands somewhere sensible and lands there
@@ -73,12 +44,14 @@ interface MuteOptions {
     /** `1` at index i mutes observation i. Absent ⇒ nothing is muted. */
     muted?: Uint8Array | null;
 }
+/** Options for {@link encodeCategorical}: a colour per category, plus muting. */
 export interface CategoricalEncodingOptions extends MuteOptions {
     /** Per-category `#rrggbb`, index-aligned with the column's categories. */
     colors: string[];
     /** Colour for {@link NO_CATEGORY}. Default {@link MISSING_COLOR}. */
     missingColor?: Rgb;
 }
+/** Options for {@link encodeContinuous}: a colormap, a contrast window and scaling, plus muting. */
 export interface ContinuousEncodingOptions extends MuteOptions {
     /** 256-entry RGB table from {@link buildColormapLut}. */
     lut: Rgb[];
@@ -90,8 +63,8 @@ export interface ContinuousEncodingOptions extends MuteOptions {
     /** Colour for `NaN`. Default {@link MISSING_COLOR}. */
     missingColor?: Rgb;
 }
-/** Parse `#rgb` / `#rrggbb` to 0–255 RGB; unparseable input falls back to grey.
- *  Exported so the 3D LUT path parses palettes exactly as the 2D path does. */
+/** Parse a CSS colour (`#rgb` / `#rrggbb`, see {@link parseCssColor}) to 0–255 RGB; unparseable
+ *  input falls back to grey. Exported so the tile layers parse palettes exactly as the markers do. */
 export declare function parseHex(hex: string): Rgb;
 /**
  * Per-category colours: the column's authored `colors` where present (so the
@@ -110,7 +83,9 @@ export declare function encodeContinuous(values: Float32Array, opts: ContinuousE
  * fractions (0.01 / 0.99 clips the extreme 1% at each end).
  *
  * Returns `[0, 1]` for an empty or all-missing vector so callers always get a
- * usable window.
+ * usable window. A large vector is windowed from an even sample of it — see
+ * `spatial/stats.ts` — because this runs on every recolour, and sorting millions
+ * of values each time cost most of a second.
  */
 export declare function contrastWindow(values: Float32Array, lo?: number, hi?: number): [number, number];
 /**
@@ -122,14 +97,6 @@ export declare function contrastWindow(values: Float32Array, lo?: number, hi?: n
  * often don't); it is in image pixels, like everything else in this space.
  */
 export declare function markerDiameters(observations: SpatialObservations, fallbackRadius?: number): number | Float32Array;
-/**
- * Adapt a flat RGBA buffer to the `RGBA[]` shape napari-js 0.12.0's
- * `PointsLayer.faceColor` accepts. One 4-element array per point — the reason
- * this is a named boundary rather than inlined: it is the one place the model
- * stops being typed-array shaped, and it is what a future napari-js taking a
- * `Float32Array` would delete.
- */
-export declare function toRgbaTuples(flat: Float32Array): RGBA[];
 /** Convenience: a 256-entry LUT for a colormap value, falling back to Viridis. */
 export declare function lutFor(colormapValue: unknown, reverse?: boolean): Rgb[];
 /** True when every entry of a LUT is a neutral grey. Tested on the VALUES rather

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

@@ -40,6 +40,10 @@ export interface ExpressionFieldOptions {
     /** Observations to include; every one when absent (a plane, a selection). */
     indices?: Uint32Array;
 }
+/**
+ * A 2D field of kernel-weighted mean expression on a `width × height` grid, with the
+ * support that says where it was actually measured.
+ */
 export interface ExpressionField {
     width: number;
     height: number;
@@ -60,6 +64,15 @@ export interface ExpressionField {
  * than an empty one the reader has to interpret.
  */
 export declare function expressionField(obs: SpatialObservations, opts: ExpressionFieldOptions): ExpressionField | null;
+/**
+ * Contrast window of a gene map (2-D or 3-D), from percentiles of the MEASURED pixels.
+ *
+ * `mean` is 0 wherever `support` is 0, and those zeros are not data: windowing the whole
+ * array pins the low percentile at 0 and slides the high one upward on any section the
+ * tissue does not fill, so the colours stop describing what was measured. `lo`/`hi` are
+ * fractions, as for `contrastWindow`; `[0, 1]` when nothing was measured.
+ */
+export declare function fieldContrastWindow(field: Pick<ExpressionField | ExpressionVolumeField, 'mean' | 'support'>, lo?: number, hi?: number): [number, number];
 /**
  * Colour a field into RGBA8 for a `channels: 4` image source.
  *
@@ -73,28 +86,7 @@ export declare function colorExpressionField(field: ExpressionField, lut: readon
     log?: boolean;
     opacity?: number;
 }): Uint8Array;
-/**
- * The same estimator in 3D: a gene's expression over a serially sectioned
- * specimen, on a {@link DensityGrid} lattice.
- *
- * Two modes, and the difference between them is the difference between a
- * measurement and an estimate:
- *
- *  - **sheets** (`interpolate` unset) blurs in-plane only, so exactly the z planes
- *    that hold cells are filled and the gaps between sections stay empty. This is
- *    the measured sections, stacked — the 2D gene map of each slide, at its own z.
- *  - **volume** (`interpolate` set) also smooths along z, so the planes between
- *    the sections carry an interpolated value. Smoothing the numerator and the
- *    denominator together is what makes that honest: it is Nadaraya-Watson, so an
- *    unimaged plane inherits its neighbours' MEAN rather than their sum thinned
- *    over a gap nobody sampled. Outside the sampled range the field is zeroed —
- *    "smoothed between the imaged sections" must not put expression in front of
- *    the first section or behind the last.
- *
- * Individual cells are still never interpolated: consecutive sections sample
- * different cells, so there is nothing to interpolate along. What is interpolated
- * is a field, which is legitimately defined between the planes.
- */
+/** Options for {@link expressionVolume}. */
 export interface ExpressionVolumeOptions {
     /** Kernel σ per axis, in the observations' own units. The z term is used only
      *  when {@link interpolate} is set. */
@@ -107,6 +99,10 @@ export interface ExpressionVolumeOptions {
      *  sheets isolated at their own planes. */
     interpolate?: boolean;
 }
+/**
+ * The 3D counterpart of {@link ExpressionField}: kernel-weighted mean expression on a
+ * `width × height × depth` voxel grid, with its support.
+ */
 export interface ExpressionVolumeField {
     width: number;
     height: number;
@@ -118,6 +114,28 @@ export interface ExpressionVolumeField {
     /** Finite range of `mean` over the supported voxels, for a contrast window. */
     range: [number, number];
 }
+/**
+ * The same estimator in 3D: a gene's expression over a serially sectioned
+ * specimen, on a {@link DensityGrid} lattice.
+ *
+ * Two modes, and the difference between them is the difference between a
+ * measurement and an estimate:
+ *
+ *  - **sheets** (`interpolate` unset) blurs in-plane only, so exactly the z planes
+ *    that hold cells are filled and the gaps between sections stay empty. This is
+ *    the measured sections, stacked — the 2D gene map of each slide, at its own z.
+ *  - **volume** (`interpolate` set) also smooths along z, so the planes between
+ *    the sections carry an interpolated value. Smoothing the numerator and the
+ *    denominator together is what makes that honest: it is Nadaraya-Watson, so an
+ *    unimaged plane inherits its neighbours' MEAN rather than their sum thinned
+ *    over a gap nobody sampled. Outside the sampled range the field is zeroed —
+ *    "smoothed between the imaged sections" must not put expression in front of
+ *    the first section or behind the last.
+ *
+ * Individual cells are still never interpolated: consecutive sections sample
+ * different cells, so there is nothing to interpolate along. What is interpolated
+ * is a field, which is legitimately defined between the planes.
+ */
 export declare function expressionVolume(obs: SpatialObservations, grid: DensityGrid, opts: ExpressionVolumeOptions): ExpressionVolumeField | null;
 /**
  * Encode a field into the uint8 scalar a `VolumeLayer` renders, windowed the same

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

@@ -12,6 +12,7 @@
 /** Fraction of the viewport the coordinates are fitted into, so the outermost markers are not
  *  flush against the edge. Matches napari-js's own fit margin. */
 export declare const SPATIAL_FIT_MARGIN = 0.95;
+/** A 2D camera framing: where to centre, and how far to zoom. */
 export interface SpatialFraming {
     /** World point to put at the centre of the viewport. */
     center: [number, number];

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

@@ -35,6 +35,7 @@ export interface HeatmapGroups {
     codes: Uint16Array;
     categories: readonly string[];
 }
+/** Options for {@link heatmapMatrix}: the observations, scaling and size limits. */
 export interface HeatmapMatrixOptions {
     /** Observations to include; every one when absent (an ROI selection). */
     indices?: Uint32Array;
@@ -62,6 +63,7 @@ export interface HeatmapMatrixOptions {
      */
     maxCols?: number;
 }
+/** Mean expression of genes (rows) per group (columns), ready for a heatmap trace. */
 export interface HeatmapMatrix {
     /** Gene names, one per row, in the order given. */
     rows: string[];

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