@jax-data-science/sci-image-visualizer 0.3.3 → 0.5.0

package/index.d.ts

@@ -11,18 +11,29 @@ export * from './lib/contracts/ports/image-state.port';
 export * from './lib/contracts/ports/tile-access.port';
 export * from './lib/contracts/ports/region-io.port';
 export * from './lib/contracts/ports/preferences.port';
+export * from './lib/contracts/ports/spatial-data.port';
+export * from './lib/contracts/spatial-dataset.contract';
 export * from './lib/contracts/channel-histogram-api.contract';
 export * from './lib/contracts/viz-config';
 export * from './lib/contracts/image.contract';
 export * from './lib/contracts/plot-type';
 export * from './lib/contracts/toolbar-config';
 export * from './lib/contracts/toolbar-tool.contract';
+export * from './lib/contracts/plot-type-contribution.contract';
 export * from './lib/contracts/capabilities.contract';
 export * from './lib/contracts/region-overlay.contract';
 export * from './lib/contracts/display-types';
 export * from './lib/contracts/sam.contract';
 export * from './lib/contracts/cell-segmenter.contract';
 export { CellposeSegmenterService } from './lib/toolbar/segmentation/cellpose-segmenter.service';
+export { SpatialDataHttpService, SupersededError } from './lib/implementations/spatial-data-http/spatial-data-http.service';
+export { SPATIAL_WIRE_VERSION, isLittleEndian, assertManifestVersion, datasetFromManifest, decodeCoords, decodeRadius, decodeColumn, decodeFeatureVector, decodePolygons, } from './lib/implementations/spatial-data-http/spatial-wire';
+export type { SpatialManifest, SpatialDatasetSummary, SpatialRadiusSpec, } from './lib/implementations/spatial-data-http/spatial-wire';
+export { encodeCategorical, encodeContinuous, resolveCategoryColors, contrastWindow, markerDiameters, toRgbaTuples, lutFor, DEFAULT_CATEGORICAL_PALETTE, DEFAULT_MUTED_OPACITY, MISSING_COLOR, } from './lib/spatial/spatial-encoding';
+export type { RGBA, CategoricalEncodingOptions, ContinuousEncodingOptions, } from './lib/spatial/spatial-encoding';
+export { selectInRegions, selectByCategory, mutedFromSelection, pointInRing, emptySelection, countMask, maskToIndices, } from './lib/spatial/spatial-selection';
+export type { SpatialSelectionMask } from './lib/spatial/spatial-selection';
+export { SpatialSelectionStore } from './lib/store/spatial-selection.service';
 export * from './lib/contracts/instance-segmenter.contract';
 export * from './lib/contracts/semantic-segmenter.contract';
 export { ProcessingImage } from './lib/processing/processing-image';
@@ -40,3 +51,8 @@ export { VisualizerComponent } from './lib/visualizer.component';
 export { RegionEditorComponent } from './lib/region-editor/region-editor.component';
 export { HexColorPickerComponent } from './lib/hex-color-picker/hex-color-picker.component';
 export { ChannelHistogramComponent } from './lib/channel-histogram/channel-histogram.component';
+export { SpatialControlsComponent, } from './lib/spatial-controls/spatial-controls.component';
+export type { SpatialLegendEntry } from './lib/spatial-controls/spatial-controls.component';
+export { SpatialChartsComponent } from './lib/spatial-controls/spatial-charts/spatial-charts.component';
+export { buildOmicsTraces, omicsLayout, benefitsFromGrouping, } from './lib/implementations/plotly/omics-trace-builders';
+export type { OmicsChartKind, OmicsGrouping, OmicsTraceInput, } from './lib/implementations/plotly/omics-trace-builders';

package/lib/contracts/display-types.d.ts

@@ -39,3 +39,134 @@ export interface IBrushOptions {
     /** Brush diameter in matrix (image) pixels. */
     size?: number;
 }
+/** What drives point colour in the spatial-omics mode: an annotation column
+ *  from the dataset, or one feature (gene) vector fetched on demand. */
+export interface SpatialColorBy {
+    kind: 'column' | 'feature';
+    name: string;
+}
+/** Display state for the spatial-omics plot mode. Lives in `VisualizerStore`
+ *  alongside the colormap/channel state so the renderer reacts to edits the
+ *  same way it does for an image. */
+export interface SpatialViewState {
+    /** Colour source; `null` renders every observation in one neutral colour
+     *  (useful on its own — it shows where the tissue actually is). */
+    colorBy: SpatialColorBy | null;
+    /** Multiplier on the dataset's physical marker size. 1 = true size, which for
+     *  a 55 µm Visium spot is correct but can be invisible when zoomed out. */
+    pointScale: number;
+    /** Alpha for points that are not muted. */
+    opacity: number;
+    /** Log-scale continuous values before mapping them onto the colormap. Seeded
+     *  from the column's `logScaleHint` — count data needs it. */
+    logScale: boolean;
+    /** Percentile clip for the contrast window as `[lo, hi]` fractions, so a
+     *  handful of saturated observations don't flatten the rest. */
+    percentileClip: [number, number];
+    /**
+     * Colormap for CONTINUOUS spatial colouring — a gene, a numeric column — as a
+     * {@link ColormapValue}, the same shape the display colormap carries: a scale
+     * NAME for the built-ins, or an inline `[stop, colour]` array for the rest.
+     * Null follows the display colormap.
+     *
+     * Its own setting because the display colormap belongs to the tissue image and
+     * is usually a grey ramp, which is the wrong thing to read a measurement
+     * through: grey over grey cannot be told apart from the anatomy. Following it
+     * (with a Viridis fallback for exactly that case) is a reasonable default and a
+     * poor ceiling, since which gradient reads best is a judgement about the data.
+     *
+     * One setting for the markers, the 2D gene map and the 3D gene map together, so
+     * the field under the cells and the cells over it cannot disagree about what a
+     * colour means — and the panel's own colour bar is built from it too.
+     */
+    continuousColormap: ColormapValue | null;
+    /**
+     * What the 3D scene draws. The three things in it — the reference volume, the
+     * observation cloud and the cluster density volumes — occupy the same space, so
+     * any two of them hide each other to some degree. These are independent because
+     * the useful views are the combinations: the volumes alone to read an estimated
+     * distribution, one section's cells over them to check that estimate against the
+     * measurement, the anatomy alone to find a landmark.
+     *
+     * Visibility only — the layers stay built, so toggling one back on is immediate
+     * and does not re-run a rasterisation. {@link densityVolume} is the exception and
+     * genuinely gates construction, because building six volumes is not free.
+     */
+    showVolume: boolean;
+    /**
+     * The reference volume's opacity.
+     *
+     * Its own, not {@link opacity} (which belongs to the markers): the volume is a
+     * BACKDROP, and reading the cloud or a density field through it means turning
+     * the anatomy down without touching the data drawn over it. Ranges lower than
+     * the markers' slider for the same reason — a faint anatomical hint is a useful
+     * setting for a backdrop and a useless one for the measurement.
+     */
+    volumeOpacity: number;
+    /** Draw the observation cloud (3D). */
+    showPoints: boolean;
+    /**
+     * Restrict the cloud to ONE imaged section, by index into the dataset's sampled
+     * sections; null draws every section.
+     *
+     * The whole cloud is a stack of discs that hides whatever is drawn between them.
+     * One section at a time is the view that answers "does the estimated field
+     * actually follow the cells I measured" — and it is only offered for data that
+     * really is sectioned (see `sampledSections`).
+     */
+    pointSection: number | null;
+    /**
+     * Draw each cluster as a translucent DENSITY volume alongside the 3D cloud.
+     *
+     * Serial sections hundreds of microns apart make a cloud hard to read as an
+     * anatomical distribution — the eye cannot integrate discs into a shape. A
+     * density field can be estimated between the imaged planes (a continuous
+     * estimate, unlike individual cells, which have no correspondence to
+     * interpolate along) and renders as a cloud that reads as an estimate.
+     */
+    densityVolume: boolean;
+    /** Multiplier on the default kernel bandwidth. Above 1 is smoother and less
+     *  committal; below 1 exposes the individual sections. */
+    densitySmoothing: number;
+    /**
+     * Draw the active GENE as a continuous field under the observations (2D).
+     *
+     * Colouring the markers by a gene says which cells express it; it cannot say
+     * where, because the eye will not integrate thousands of dots into a territory.
+     * The field is an estimate — a kernel-weighted mean per cell, transparent where
+     * no cell was measured — and it is drawn beneath the cells, not instead of them,
+     * so the measurement stays on screen next to the interpolation.
+     *
+     * Ignored unless the colour source is a gene: there is nothing else to map.
+     */
+    geneMap: boolean;
+    /**
+     * Restrict the 3D gene map to ONE imaged section, by index into the dataset's
+     * sampled sections; null draws every section's sheet.
+     *
+     * Separate from {@link pointSection} so the combinations stay open: all the
+     * sheets with one section's cells over them is a useful view, and so is one
+     * sheet inside the whole cloud. Ignored while {@link geneMapVolume} is set —
+     * interpolating a single section along z would smear one slide through the
+     * specimen's whole depth and call it an estimate.
+     */
+    geneMapSection: number | null;
+    /**
+     * Smooth the per-section gene maps along z into a continuous VOLUME (3D).
+     *
+     * The sheets are what was measured — one field per imaged slide, with the gaps
+     * between them empty. This turns them into an estimate defined between the
+     * slides, the same move the cluster density volumes make and with the same
+     * caveat: a field may be interpolated between sections, individual cells may
+     * not, and the result is drawn as a translucent cloud so it cannot be mistaken
+     * for measurement.
+     */
+    geneMapVolume: boolean;
+    /** Multiplier on the gene map's kernel bandwidth. */
+    geneMapSmoothing: number;
+    /** The gene map's own opacity. Separate from {@link opacity}, which belongs to
+     *  the markers: turning the cells down to read the field underneath must not
+     *  turn the field down with them. */
+    geneMapOpacity: number;
+}
+export declare const DEFAULT_SPATIAL_VIEW: SpatialViewState;

package/lib/contracts/image.contract.d.ts

@@ -31,6 +31,13 @@ export interface IImageMetadata {
     /** Physical pixel size in µm; null/undefined when the format reports none. */
     mppX?: number | null;
     mppY?: number | null;
+    /** Physical spacing BETWEEN slices in µm — the z counterpart of `mppX`/`mppY`,
+     *  for a stack that knows it (a resampled volume, a confocal stack). It is what
+     *  lets the 3D volume view render true anisotropy: with all three present the
+     *  world box is the image's real physical extent, so 40 x 40 x 200 µm voxels
+     *  read as a brain and not as a cube-aspect brick. Absent, the view falls back
+     *  to its resolution-invariant reference box, which is shape-only. */
+    mppZ?: number | null;
     /** Per-channel name/color/LUT for multichannel (non-RGB) images, when known. */
     channelInfo?: IChannelInfo[] | null;
 }

package/lib/contracts/plot-type-contribution.contract.d.ts

@@ -0,0 +1,172 @@
+/**
+ * How a plot mode gets into the plot-type selector without this library knowing
+ * what it is.
+ *
+ * A package contributes a mode by providing a {@link PlotTypeContribution} on the
+ * {@link PLOT_TYPE_CONTRIBUTIONS} multi-provider token, the same way
+ * `TOOLBAR_TOOLS` contributes toolbar tools. Nothing registers at import time:
+ * installing a package makes a mode available, and adding its provider turns it
+ * on. A plain object works, so the contributing package needs no Angular
+ * compiler and no decorators:
+ *
+ *     { provide: PLOT_TYPE_CONTRIBUTIONS, useValue: myContribution, multi: true }
+ *     { provide: PLOT_TYPE_CONTRIBUTIONS, useFactory: () => makeContribution(), multi: true }
+ *
+ * Provide nothing and the selector, the render path and the panel area behave
+ * exactly as they did before this extension point existed.
+ *
+ * WHY A CONTRIBUTED MODE RIDES ON A BUILT-IN ONE
+ * A contributed mode does not bring a renderer. It names a built-in
+ * {@link ContributedPlotTypeDescriptor.baseType} — in v1 only `PlotType.IMAGE`,
+ * the OpenSeadragon view — and the visualizer plots exactly as if that type had
+ * been selected: same backend, same toolbar, same region tools, same wheel
+ * handling. The contribution then draws over it through the
+ * {@link PlotModeViewport} and talks to the viewer through the public
+ * {@link IVisualizer}. That keeps every rendering decision in one place and means
+ * a contribution can never be half-supported by some code path that switches on
+ * the plot type.
+ *
+ * WHAT THE VISUALIZER GUARANTEES
+ *  1. Contributed descriptors are appended after the built-in ones and curated by
+ *     the same `productionLabel` / test-mode / `requires*` rules.
+ *  2. Selecting one plots with `baseType`'s backend, then calls `activate(ctx)`
+ *     once the viewport is ready.
+ *  3. Leaving the mode — another type, an image switch (or any re-render of the
+ *     base view), or the visualizer being destroyed — calls `session.deactivate()`
+ *     exactly once, before the next mode draws. If the mode is still selected
+ *     when the new image has plotted, a fresh session is activated for it.
+ *  4. `panel` is shown only while a session is live.
+ *  5. A thrown error or rejected promise from `activate`, `deactivate`, `mount`
+ *     or a mount's teardown is caught and logged; none escapes, so a contribution
+ *     cannot break the viewer. Failing to start (`activate`, `mount`, or a panel
+ *     component throwing while it is created / first rendered) falls back
+ *     to `baseType`. Failing to clean up falls back when that same mode is being
+ *     re-activated (base re-render, image switch) — immediately if it already is
+ *     live again — and is only logged when the user has moved to another mode; the
+ *     user explicitly selecting it again gets a fresh attempt.
+ *  6. {@link PLOT_TYPE_CONTRIBUTIONS} has no factory: no providers, no modes.
+ */
+import { InjectionToken, Type } from '@angular/core';
+import type { Observable } from 'rxjs';
+import type { IImageInfo } from './image.contract';
+import type { PlotType, PlotTypeDescriptor, PlotTypeId } from './plot-type';
+import type { IVisualizer } from './visualizer.contract';
+/** A rectangle in level-0 image pixels. */
+export interface PlotModeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Selector metadata for a contributed plot mode. */
+export interface ContributedPlotTypeDescriptor {
+    /** Unique id, namespaced, e.g. 'dianne'. Must not clash with PlotType values. */
+    type: string;
+    /** Test-mode label, e.g. 'Digital Pathology - DIANNE'. */
+    label: string;
+    /** Default-selector label; omit to make the mode test-only (same rule as built-ins). */
+    productionLabel?: string;
+    /** 'pi pi-…' class or asset path, same as PlotTypeDescriptor.icon. */
+    icon?: string;
+    /** Always '2d' in v1. */
+    dimensions: '2d';
+    /** Built-in type whose backend renders the base image. v1 supports PlotType.IMAGE (OSD). */
+    baseType: PlotType;
+    /** Same gates as PlotTypeDescriptor, evaluated in addition to the base type's own. */
+    requiresGrayscale?: boolean;
+    requiresStack?: boolean;
+    /** Hidden until a `SpatialDataset` is published on SPATIAL_DATA_PORT (an overlay of spatial observations). */
+    requiresSpatialData?: boolean;
+    /** Hidden unless the published dataset carries `observations.z`. */
+    requiresSpatial3d?: boolean;
+}
+/** The base view's viewport, as a contributed mode sees it. */
+export interface PlotModeViewport {
+    /** Element the mode's overlay canvas/SVG attaches to; fills the plot area. */
+    getOverlayContainer(): HTMLElement | null;
+    /** Level-0 image px -> client px, and the reverse. */
+    dataToClient(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    clientToData(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    /** Screen px per image px at the current zoom. */
+    dataLengthToScreen(len: number): number;
+    isReady(): boolean;
+    /** Visible image rect in level-0 px, emitted on every redraw frame (pan/zoom animation).
+     *  A new subscriber first receives the current rect when the viewport is ready. */
+    frame$: Observable<PlotModeRect>;
+    /** Same rect, emitted once the viewport settles (existing getViewportChange$ semantics).
+     *  A new subscriber first receives the current rect when the viewport is ready. */
+    settled$: Observable<PlotModeRect>;
+}
+/** Everything a contributed mode gets to work with while it is active. */
+export interface PlotModeContext {
+    /** Full public visualizer API: regions, region overlay (tool modes), undo, etc. */
+    visualizer: IVisualizer;
+    viewport: PlotModeViewport;
+    /** Current image info from IMAGE_STATE_PORT (null until an image is loaded). */
+    imageInfo$: Observable<IImageInfo | null>;
+}
+/** A live activation of a contributed mode. */
+export interface PlotModeSession {
+    /** Called when the user leaves the mode, the image changes, or the visualizer is destroyed. */
+    deactivate(): void;
+}
+/**
+ * The mode's side panel, shown in the visualizer's right-hand panel area while
+ * a session is live. Two forms:
+ *
+ *  - `component`: an Angular component, rendered through `NgComponentOutlet`
+ *    with {@link PLOT_MODE_CONTEXT} and {@link PLOT_MODE_SESSION} in its
+ *    injector. Needs an AOT-compiled (partial-Ivy) component.
+ *  - `mount`: framework-agnostic. The visualizer hands over an empty host
+ *    element after `activate` resolves; the function renders into it and returns
+ *    a teardown. The teardown is called exactly once when the mode deactivates,
+ *    before `session.deactivate()`, and the host element is then removed.
+ */
+export type PlotModePanel = {
+    title: string;
+    component: Type<unknown>;
+} | {
+    title: string;
+    mount(host: HTMLElement, ctx: PlotModeContext, session: PlotModeSession): () => void;
+};
+/** A plot mode contributed to the selector. A plain object is enough. */
+export interface PlotTypeContribution {
+    descriptor: ContributedPlotTypeDescriptor;
+    /** Called after the base backend has plotted the image in this mode. */
+    activate(ctx: PlotModeContext): PlotModeSession | Promise<PlotModeSession>;
+    /**
+     * Optional side panel, rendered in the visualizer's right-hand panel area while the
+     * mode is active. A component panel can inject PLOT_MODE_CONTEXT and PLOT_MODE_SESSION.
+     */
+    panel?: PlotModePanel;
+}
+/**
+ * Multi-provider token for contributed plot modes.
+ *
+ * Deliberately has no `factory`: unregistered means no contributed modes, and the
+ * library behaves exactly as before. The visualizer injects it `{ optional: true }`
+ * and treats null as empty.
+ */
+export declare const PLOT_TYPE_CONTRIBUTIONS: InjectionToken<readonly PlotTypeContribution[]>;
+/** The active mode's context, in a component panel's injector. */
+export declare const PLOT_MODE_CONTEXT: InjectionToken<PlotModeContext>;
+/** The active mode's session, in a component panel's injector. */
+export declare const PLOT_MODE_SESSION: InjectionToken<PlotModeSession>;
+/**
+ * One entry in the plot-type selector: a built-in {@link PlotTypeDescriptor}
+ * as-is, or a contributed descriptor completed with its base type's `source`.
+ * Every entry therefore carries the same fields the selector curates by.
+ */
+export interface PlotTypeOption extends Omit<PlotTypeDescriptor, 'type'> {
+    type: PlotTypeId;
+    /** Set only for a contributed mode: the built-in type that renders it. */
+    baseType?: PlotType;
+}
+/** The selector entry for a contributed mode, given its base type's descriptor. */
+export declare function contributedPlotTypeOption(d: ContributedPlotTypeDescriptor, base: PlotTypeDescriptor): PlotTypeOption;

package/lib/contracts/plot-type.d.ts

@@ -31,16 +31,38 @@ export declare enum PlotType {
     /** WebGPU 2D scatter of region centroids (napari-js analog of Plotly SCATTER). */
     NAPARI_SCATTER = "napari-scatter",
     /** WebGPU 3D scatter of the downsampled voxel cloud (napari-js analog of Plotly SCATTER3D). */
-    NAPARI_SCATTER3D = "napari-scatter3d"
+    NAPARI_SCATTER3D = "napari-scatter3d",
+    /** Spatial-omics observations (Visium spots, segmented cells) drawn over the tissue image and
+     *  coloured by an annotation column or a gene. Needs a `SpatialDataset` on `SPATIAL_DATA_PORT`,
+     *  so it is gated by `requiresSpatialData` and never appears for an image-only host. */
+    SPATIAL_OMICS = "spatial-omics",
+    /** Spatial-omics observations as a 3D point cloud, for assays whose observations carry a z —
+     *  serial sections registered into a common frame (e.g. the Allen CCF), or a genuinely
+     *  volumetric assay. Gated by `requiresSpatial3d`, a strictly narrower gate than
+     *  {@link SPATIAL_OMICS}: a single-plane dataset has no z to render. */
+    SPATIAL_OMICS_3D = "spatial-omics-3d"
 }
+/**
+ * A value the plot-type selector can hold: a built-in {@link PlotType}, or the
+ * `type` of a contributed mode (`ContributedPlotTypeDescriptor.type`, see
+ * `plot-type-contribution.contract.ts`). Everything that decides HOW to render
+ * keeps taking a {@link PlotType}; a contributed id is resolved to its
+ * `baseType` first, so no rendering switch ever sees one.
+ */
+export type PlotTypeId = PlotType | string;
+/** Whether an id names a built-in plot type (as opposed to a contributed one). */
+export declare function isBuiltinPlotType(id: PlotTypeId | null | undefined): id is PlotType;
 /** How many spatial dimensions a plot type renders in. */
 export type PlotDimensions = '2d' | '3d';
 /**
  * Where a plot type pulls its data from:
  *  - `image`   — the loaded pixel matrices / z-stack (HEATMAP, SURFACE, …)
  *  - `regions` — the drawn/derived regions (SCATTER of region centroids, …)
+ *  - `spatial` — a `SpatialDataset` supplied through `SPATIAL_DATA_PORT`: N
+ *    observations (spots/cells) with categorical + continuous columns and a
+ *    lazily-fetched feature matrix, drawn over the tissue image they came from.
  */
-export type PlotDataSource = 'image' | 'regions';
+export type PlotDataSource = 'image' | 'regions' | 'spatial';
 /**
  * Backend-neutral metadata about a plot type. Drives UI affordances (which
  * types are 3D, which need an image stack, how to label them in a dropdown)
@@ -75,6 +97,17 @@ export interface PlotTypeDescriptor {
      *  surface, intensity profile, isosurface) — only meaningful for grayscale.
      *  Image/Heatmap render RGB fine; Scatter uses regions. */
     requiresGrayscale?: boolean;
+    /** True when the type renders a `SpatialDataset` (`source: 'spatial'`) and is
+     *  therefore meaningless without one. The selector hides it until a dataset is
+     *  published on `SPATIAL_DATA_PORT` — the same shape of gate as
+     *  {@link requiresStack} for a z-stack, so a host with no spatial data never
+     *  sees the mode. */
+    requiresSpatialData?: boolean;
+    /** True when the type needs observations with a z coordinate, not merely a
+     *  `SpatialDataset`. Narrower than {@link requiresSpatialData}: most spatial
+     *  assays are a single plane, so this hides the 3D mode unless the published
+     *  dataset actually carries `observations.z`. */
+    requiresSpatial3d?: boolean;
 }
 /**
  * Single source of truth for plot-type metadata. LINE is intentionally absent —
@@ -95,6 +128,23 @@ export declare function isNapariSurface(type: PlotType): boolean;
 export declare function isNapariScatter(type: PlotType): boolean;
 /** napari-js 3D scatter (voxel point cloud). */
 export declare function isNapariScatter3d(type: PlotType): boolean;
+/** Spatial-omics observations over the tissue image. */
+export declare function isSpatialOmics(type: PlotType): boolean;
+/** Spatial-omics observations as a 3D point cloud. */
+export declare function isSpatialOmics3d(type: PlotType): boolean;
+/**
+ * Whether the renderer, rather than the shell, should handle wheel zoom.
+ *
+ * The shell's wheel listener applies a FIXED step per event, which is far too sensitive for a
+ * renderer that reads the scroll delta: it works out at 30% per event against napari-js's 3%, and
+ * ignores the device normalization and easing the renderer does. So every plot type drawn by a
+ * renderer that owns the wheel has to opt out here.
+ *
+ * The image view always did. The spatial-omics modes did NOT, despite being drawn by the same
+ * napari-js viewer — the shell gated on an `isHeatmap` flag that defaults to true and only goes
+ * false for the 3D Plotly scenes, so it silently took the wheel for them too.
+ */
+export declare function rendererOwnsWheel(type: PlotType): boolean;
 /** Any napari-js 3D plot type (volume, isosurface, surface, or 3D scatter). Resolution is a runtime
  *  decimate factor (Full / ½ / ¼ / ⅛) — see the service's `resolutionScale`. */
 export declare function isNapari3d(type: PlotType): boolean;

package/lib/contracts/ports/spatial-data.port.d.ts

@@ -0,0 +1,90 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { SpatialColumn, SpatialDataset, SpatialEmbedding, SpatialPolygons } from '../spatial-dataset.contract';
+/**
+ * Spatial-omics data access, inverted as a port so the visualization library
+ * never learns how the data is stored or served — exactly like
+ * `TILE_ACCESS_PORT` for tiles and `REGION_IO_PORT` for annotations. The host
+ * supplies an adapter; the library consumes typed arrays.
+ *
+ * WHY A PORT AND NOT A READER
+ * ---------------------------
+ * The interchange format for this data (SpatialData Zarr v3 + AnnData
+ * conventions + GeoParquet shapes) needs three parsers, and its expression
+ * matrix is stored observation-major — so reading a single gene's column means
+ * touching every row. A server can pre-index that once; a browser cannot. So
+ * the library takes vectors it can render and leaves ingest to whoever owns the
+ * data. `SpatialDataHttpService` is a ready-made adapter for the wire format
+ * the bundled example server speaks; a host with its own backend implements
+ * this interface instead.
+ *
+ * LAZINESS IS THE POINT
+ * ---------------------
+ * `getDataset$()` yields only what is cheap to hold: coordinates plus column
+ * and feature *metadata*. Every accessor below fetches one vector at a time,
+ * for the one column or gene currently being displayed.
+ */
+export interface SpatialDataPort {
+    /**
+     * The dataset currently being visualized, or null when none is selected.
+     * Emits again when the host switches datasets, so the view can rebuild.
+     */
+    getDataset$(): Observable<SpatialDataset | null>;
+    /**
+     * Values for one annotation column, index-aligned with the observations.
+     * The column must be one advertised in `SpatialDataset.columns`; reject
+     * (don't resolve empty) when it isn't, so a typo surfaces instead of
+     * rendering as "no data".
+     *
+     * Implementations should cache — colouring by cluster, then by a gene, then
+     * back by cluster must not refetch.
+     */
+    getColumn(name: string): Promise<SpatialColumn>;
+    /**
+     * One feature's (gene's) expression vector, index-aligned with the
+     * observations. Rejects for an unknown feature.
+     */
+    getFeatureVector(name: string): Promise<Float32Array>;
+    /**
+     * One embedding's coordinates, index-aligned with the observations.
+     *
+     * The name must be one advertised in `SpatialDataset.embeddings`; rejects otherwise, for the
+     * same reason `getColumn` does — a typo should surface rather than render as an empty plot.
+     *
+     * Optional: a host with no embeddings simply omits it, and the UI offers no embedding views.
+     */
+    getEmbedding?(name: string): Promise<SpatialEmbedding>;
+    /**
+     * Typeahead over feature names, for datasets too wide to inline the list
+     * (`SpatialFeatureMeta.names` absent). Optional: a host whose panel is small
+     * enough to inline every name need not implement it — the UI falls back to
+     * filtering `names` locally.
+     */
+    searchFeatures?(query: string, limit?: number): Promise<string[]>;
+    /**
+     * Per-observation boundary geometry, when the dataset advertises
+     * `polygons`. Optional — a spot-based assay (Visium) has no segmentation.
+     */
+    getPolygons?(): Promise<SpatialPolygons>;
+    /**
+     * The reference volume's voxels: a uint8 scalar field, x-fastest, of exactly
+     * `width * height * depth` bytes as the dataset's {@link SpatialVolumeMeta}
+     * declares.
+     *
+     * Optional, and only meaningful when the dataset advertises a volume. Separate
+     * from `getDataset$()` because it is megabytes: a host that never opens the 3D
+     * mode should never pay for it.
+     */
+    getVolume?(): Promise<Uint8Array>;
+    /**
+     * Server-side "which observations fall inside this polygon", for datasets
+     * too large to hit-test client-side. Optional: without it the library
+     * point-in-polygons the resident coordinates itself, which is fine into the
+     * 10^5 range. Coordinates are in the same space as the observations.
+     */
+    queryRoi?(polygon: {
+        x: number[];
+        y: number[];
+    }): Promise<Uint32Array>;
+}
+export declare const SPATIAL_DATA_PORT: InjectionToken<SpatialDataPort>;