@jax-data-science/sci-image-visualizer 0.3.2 → 0.4.0

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

@@ -0,0 +1,113 @@
+import { Region } from '../models/region';
+import { SpatialImageRef, SpatialObservations } from '../contracts/spatial-dataset.contract';
+/**
+ * Which observations fall inside a set of drawn regions.
+ *
+ * Pure, like `spatial-encoding.ts` — no store, no renderer — so the geometry is
+ * testable on its own.
+ *
+ * WHY THIS IS THE WHOLE SELECTION MECHANISM
+ * -----------------------------------------
+ * Regions already come from every on-canvas tool the library has: rectangle,
+ * polygon, freehand, magic wand, brush. Testing observations against them turns
+ * all of those into spatial-omics selection tools without adding a single new
+ * canvas interaction — which is why there is no bespoke marquee here.
+ *
+ * COORDINATE FRAMES
+ * -----------------
+ * Regions are drawn in WORLD (image) coordinates. Observations live in the
+ * 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;
+}
+/** An empty selection over `count` observations. */
+export declare function emptySelection(count?: number): SpatialSelectionMask;
+/** Number of set entries in a mask. */
+export declare function countMask(mask: Uint8Array): number;
+/** Selected indices, for export or a downstream query. */
+export declare function maskToIndices(mask: Uint8Array): Uint32Array;
+/**
+ * Renderer-facing inverse: which observations to MUTE. With nothing selected
+ * nothing is muted (the whole tissue reads normally); with a selection, every
+ * 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? */
+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;
+    hit(px: number, py: number): boolean;
+}
+/**
+ * Flatten a region to testable shapes. Returns an empty array for anything that
+ * encloses no area — an open polyline, an intensity-profile line, a degenerate
+ * rectangle — so those never contribute to a selection.
+ */
+export declare function regionShapes(region: Region): Shape[];
+/**
+ * Observations inside ANY of `regions` (union). Coordinates are transformed by
+ * `imageRef` first, so the test happens in the same world space the regions were
+ * drawn in.
+ *
+ * `candidates`, when given, restricts the test to those observation indices — how
+ * a 2D view of a 3D dataset keeps a drawn region meaning what it looks like it
+ * means: the shape was drawn over ONE section, so it selects that section's cells
+ * rather than the whole depth of the specimen behind them. The returned mask stays
+ * 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.
+ *
+ * This is how a region selection works in the 3D cloud. There is no data-space
+ * affine to map a drawn shape through, because the shape was drawn on a 2D screen
+ * against a perspective camera — so the observations come the other way, already
+ * projected to canvas pixels by the renderer (which owns the camera), and the
+ * regions are tested in that same screen space.
+ *
+ * The consequence is worth being explicit about: a screen-space lasso selects
+ * through the WHOLE DEPTH of the cloud, like a cookie cutter, not a slab at some
+ * chosen z. That is inherent to drawing on a flat screen, and it is what napari
+ * and every other orbit-camera point picker do. Orbit and draw again to cut from
+ * another angle.
+ *
+ * `screen` is `[x0, y0, x1, y1, …]` in canvas pixels, `count` entries long. An
+ * observation the camera puts behind the eye is given NaN by the projector and
+ * 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.
+ *
+ * Lets a click toggle against the SELECTION rather than against a remembered
+ * click: picking a class in the legend and then clicking that same class on the
+ * canvas should clear it, and a remembered click cannot know about the legend.
+ * Counts are compared first, so two different selections usually cost nothing.
+ */
+export declare function sameSelection(a: SpatialSelectionMask, b: SpatialSelectionMask): boolean;
+export declare function selectByCategory(codes: Uint16Array, code: number): SpatialSelectionMask;
+export {};

package/lib/spatial/spatial-volume-image.d.ts

@@ -0,0 +1,67 @@
+import { IImageInfo } from '../contracts/image.contract';
+import { SpatialDataset, SpatialImageRef, SpatialObservations, SpatialVolumeMeta } from '../contracts/spatial-dataset.contract';
+/**
+ * A dataset's reference volume, encoded as the z-stack image the 2D path renders,
+ * plus the blob URLs backing it.
+ *
+ * The URLs belong to the CALLER: nothing else can know when the image stops being
+ * displayed, and a dataset switch that forgets to revoke them leaks a volume's
+ * worth of PNGs per switch.
+ */
+export interface VolumeStackImage {
+    info: IImageInfo;
+    urls: string[];
+}
+/**
+ * Turn a spatial dataset's registered volume into a scrubbable z-stack image.
+ *
+ * A 3D omics dataset arrives as one volume and NO `imageRef`, so there is no image
+ * behind it — which left every image-shaped surface (the Image view, the slice
+ * bar, the contrast window, regions) with nothing to work on, and the Image view
+ * showing whatever slide happened to be loaded before. Encoding each z plane as a
+ * blob PNG makes the volume itself the image, so the existing stack machinery
+ * drives it unchanged: the same `urls[z]` + `isStack` shape a host emits for a
+ * multi-page TIFF, which is exactly what this volume is.
+ *
+ * Every plane is encoded up front rather than on demand, because the slice count
+ * comes from `urls.length` — the component has to know the depth before the user
+ * scrubs. The voxels are already resident (megabytes, fetched in one call), and a
+ * plane is a few KB of PNG, so the cost is bounded by the volume the host already
+ * chose to fetch.
+ *
+ * Returns null when the dataset declares no volume, or the byte count contradicts
+ * the declared geometry — a short buffer would silently produce slices of shifted
+ * anatomy, which is worse than no image at all.
+ */
+export declare function buildVolumeStackImage(dataset: SpatialDataset, voxels: Uint8Array): Promise<VolumeStackImage | null>;
+/**
+ * The data→image affine a registered volume implies.
+ *
+ * Once the volume IS the image ({@link buildVolumeStackImage}), one slice is a
+ * `width x height` pixel grid whose voxel `(i, j)` covers
+ * `[i * voxelSize[0], (i + 1) * voxelSize[0])` of the observations' coordinate
+ * space — the contract's rule that the volume's near corner sits at the
+ * coordinate origin. So observations reach pixel space by dividing out the voxel
+ * size, and nothing has to move.
+ *
+ * Shaped as a `SpatialImageRef` on purpose: the marker layer and the ROI
+ * selection then take the SAME transform they take for a dataset that ships a
+ * real `imageRef`, instead of each growing a volume special case.
+ */
+export declare function volumeImageRef(volume: SpatialVolumeMeta, micronsPerUnit?: number): SpatialImageRef;
+/** The voxel plane a coordinate falls in, clamped into the volume. */
+export declare function sliceIndexOf(z: number, volume: SpatialVolumeMeta): number;
+/**
+ * Indices of the observations that fall in one voxel plane of the volume.
+ *
+ * A 2D view of a 3D dataset shows ONE plane, so it must draw one plane's
+ * observations: without this the whole depth of the specimen piles onto a single
+ * section and reads as a solid smear rather than a section's cells. The plane is
+ * a slab `voxelSize[2]` thick, which is exactly the sampling the volume itself
+ * has — for serial sections registered into a common frame, one slab is one
+ * section.
+ *
+ * Every observation is in the plane when the dataset carries no z: a genuinely
+ * flat dataset over a volume has nothing to filter on.
+ */
+export declare function observationsInSlice(obs: SpatialObservations, volume: SpatialVolumeMeta, slice: number): Uint32Array;

package/lib/spatial/tsne-worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Factory for the t-SNE Web Worker, isolated in its own module so the `import.meta.url`
+ * reference — which the bundler needs in order to locate the worker — is never pulled
+ * into the ts-jest CommonJS compile of anything that uses it. Unit tests `jest.mock` this
+ * module, or pass their own factory. Same arrangement as `mask-worker.ts`.
+ */
+export declare function createTsneWorker(): Worker;

package/lib/spatial/world-grid.d.ts

@@ -0,0 +1,58 @@
+/**
+ * How finely a drawn shape's vertices may be placed in world space.
+ *
+ * Region geometry has always been stored in whole world units, and for an image that is
+ * exactly right: world units ARE pixels, a region should align to them, and integers keep
+ * the stored geometry exact and tidy.
+ *
+ * It is wrong for a dataset whose coordinates are not pixels. seqFISH's observations span
+ * about 5 x 7 units in total, so snapping vertices to integers leaves roughly SIX BY EIGHT
+ * distinct positions in the whole sample — every ROI collapses to the same handful of
+ * boxes and drawing a fine shape is not possible at any zoom. Nothing errors; the tool
+ * simply cannot express what the user is drawing.
+ *
+ * So the step is chosen from the world's own extent rather than assumed to be one. An
+ * image keeps integers, because its extent is thousands of units and a finer step would
+ * buy nothing; a unitless dataset gets a step fine enough to draw with.
+ *
+ * Pure — no renderer, no store — so both region overlays can share one answer, and the
+ * napari and OSD paths cannot drift into disagreeing about what a vertex may be.
+ */
+/** One world unit: the step for a world whose units are image pixels. */
+export declare const PIXEL_WORLD_QUANTUM = 1;
+/**
+ * Distinct positions a drawn shape should be able to reach across the world's extent.
+ *
+ * Set by what a person can actually place with a pointer, not by float precision: a few
+ * thousand steps across the sample is finer than any screen it will be drawn on, so the
+ * limit stops being the grid and becomes the hand.
+ */
+export declare const WORLD_GRID_STEPS = 4096;
+/**
+ * The step size for a world of this extent, for a world whose units are NOT pixels.
+ *
+ * The caller decides which world it has, because the extent cannot say: a 2,000 unit world
+ * is a small slide if the units are pixels and an enormous one if they are microns, and
+ * only the caller knows which. An image keeps {@link PIXEL_WORLD_QUANTUM} by never asking.
+ *
+ * Never returns anything coarser than {@link PIXEL_WORLD_QUANTUM}. A non-pixel world can
+ * still be large — the Allen atlas is ~11,000 microns across — and there a finer step than
+ * one unit buys nothing.
+ *
+ * Rounded DOWN to a power of ten, so the step is a number a person reading the stored
+ * geometry can recognise — 0.001 rather than 0.0017044 — and so it does not shift when the
+ * extent changes slightly between datasets.
+ *
+ * A non-finite or empty extent falls back to the pixel grid: an unknown world is treated
+ * as the conservative, established case rather than given an invented precision.
+ */
+export declare function worldQuantumForExtent(spanX: number, spanY: number): number;
+/**
+ * Snap one world coordinate to the grid.
+ *
+ * A step of zero or less means no snapping — the caller keeps full float precision.
+ * Division and multiplication by the step leaves a float artefact (0.001 * 3 is not
+ * exactly 0.003), so the result is rounded to the step's own number of decimals; without
+ * that, "tidy" geometry acquires a trail of digits the grid was supposed to remove.
+ */
+export declare function snapToWorldGrid(value: number, quantum: number): number;