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

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

@@ -7,7 +7,9 @@ import { PlotType, PlotTypeDescriptor } from './plot-type';
 import { ViewerCapabilities } from './capabilities.contract';
 import { IRegionOverlay } from './region-overlay.contract';
 import { IHistogram } from './channel-histogram-api.contract';
-import { ColormapNode, IWandOptions, IBrushOptions } from './display-types';
+import { ColormapNode, IWandOptions, IBrushOptions, SpatialViewState, SpatialColorBy } from './display-types';
+import { SpatialDataset, SpatialEmbedding } from './spatial-dataset.contract';
+import { SpatialSelectionMask } from '../spatial/spatial-selection';
 /**
  * Backend-neutral visualization contract. Plotly is one implementation;
  * OpenSeadragon is another (for the image plot type). The abstraction renders
@@ -270,6 +272,98 @@ export interface IIntensityControls {
      *  backend, or null if no image extent is known yet. */
     addProfileLine(): Region | null;
 }
+/** A categorical column resolved for charting: labels, codes and map colours. */
+export interface SpatialCategoricalView {
+    name: string;
+    categories: string[];
+    /** `#rrggbb` per category, index-aligned with {@link categories}. */
+    colors: string[];
+    /** Per-observation category index, or `NO_CATEGORY`. */
+    codes: Uint16Array;
+}
+/**
+ * Controls for the SPATIAL_OMICS plot type: what the observation markers are
+ * coloured by, and how they are drawn. Capability-gated like
+ * {@link IIsosurfaceControls} — `getSpatialControls()` returns null unless a
+ * host has bound `SPATIAL_DATA_PORT`.
+ *
+ * The view state is backend-neutral (it lives in the shared store, like the
+ * colormap), so these controls work whichever backend is on screen.
+ */
+export interface ISpatialControls {
+    /** The dataset being visualized, or null. Drives the column/gene pickers and
+     *  the legend. */
+    getDataset$(): Observable<SpatialDataset | null>;
+    /** Current display state (colour source, point scale, opacity, scaling). */
+    getViewState$(): Observable<SpatialViewState>;
+    /** Synchronous read, for seeding a control's initial value. */
+    viewState(): SpatialViewState;
+    /** Patch the display state; the markers rebuild without remounting the scene. */
+    setViewState(partial: Partial<SpatialViewState>): void;
+    /** Colour by an annotation column. Rejects for an unknown column. */
+    colorByColumn(name: string): void;
+    /** Colour by a gene; its vector is fetched on demand. */
+    colorByFeature(name: string): void;
+    /** Clear the colour source — every observation renders in one neutral colour. */
+    clearColorBy(): void;
+    /** Typeahead over feature names, for datasets too wide to inline the list. */
+    searchFeatures(query: string, limit?: number): Promise<string[]>;
+    /** Per-category display colours for a categorical column, index-aligned with
+     *  its `categories` — the legend's swatches, resolved the same way the
+     *  renderer resolves them so the two cannot disagree. */
+    categoryColors(name: string): Promise<string[]>;
+    /**
+     * The values behind a colour source, index-aligned with the observations.
+     * Rejects for a categorical column — there is nothing continuous to chart.
+     */
+    continuousValues(source: SpatialColorBy): Promise<Float32Array>;
+    /**
+     * A categorical column's categories, per-observation codes and display
+     * colours — everything a grouped violin/box needs, with the colours resolved
+     * the same way the map resolves them.
+     */
+    categoricalView(column: string): Promise<SpatialCategoricalView>;
+    /**
+     * One embedding's coordinates — a UMAP, t-SNE or PCA plane over the same observations.
+     *
+     * Optional, and absent when the data source serves none: `SpatialDataPort.getEmbedding`
+     * is itself optional, so a panel must be able to ask whether this exists rather than
+     * calling it and catching.
+     */
+    getEmbedding?(name: string): Promise<SpatialEmbedding>;
+    /** Names of the categorical columns available to group by. */
+    categoricalColumns(): string[];
+    /**
+     * The z positions of the sections the dataset was imaged at, ascending — or
+     * null when its z is continuous rather than sectioned (so there are no sections
+     * to offer) or when there is no dataset.
+     *
+     * Lets a panel offer "one section at a time" for the 3D cloud only where that
+     * means something, and label the chosen one. Scanned once per dataset.
+     */
+    sampledSections(): Float32Array | null;
+    /** The current selection. Empty means "nothing selected", in which case the
+     *  whole tissue renders normally rather than everything being muted. */
+    getSelection$(): Observable<SpatialSelectionMask>;
+    /**
+     * Select every observation inside the currently-drawn regions (their union).
+     * Reuses the existing ROI tools — rectangle, polygon, freehand, wand, brush —
+     * so there is no separate marquee to learn. Returns how many were selected.
+     */
+    selectFromRegions(): number;
+    /** Select every observation in one category of a categorical column — the
+     *  legend click. Rejects for an unknown or continuous column. */
+    selectCategory(column: string, categoryIndex: number): Promise<number>;
+    /**
+     * Select an explicit set of observations, replacing any current selection.
+     *
+     * For a linked plot: lassoing points in an embedding is a selection OF observations,
+     * and every other view — the map, the distributions — reads the same mask, so brushing
+     * one lights up the rest. Returns how many were selected.
+     */
+    selectIndices(indices: Iterable<number>): number;
+    clearSelection(): void;
+}
 /** Display options (colormap/LUT, reverse scale, image metadata). */
 export interface IDisplayOptions {
     getColormap(): Observable<ColormapNode | null>;
@@ -321,6 +415,10 @@ export interface IVisualizer extends IDataRenderer, IRegionStore, IToolControlle
      *  the capability-gated replacement for the deprecated top-level
      *  `setSurfaceDragMode`/`resetSurfaceCamera`. */
     getSurface3dControls(): ISurface3dControls | null;
+    /** Spatial-omics controls when a `SPATIAL_DATA_PORT` is bound, else null.
+     *  Optional: only the routing service implements it, since the state is shared
+     *  rather than owned by any one backend. */
+    getSpatialControls?(): ISpatialControls | null;
     /** Binned intensity histogram for a channel from the currently-displayed
      *  pixels, or null when none are available. Feeds the Channels & Histogram
      *  pane. */

package/lib/implementations/napari-js/napari-axes-labels.d.ts

@@ -20,14 +20,16 @@ export interface AxesLabelCamera3D {
     };
 }
 /**
- * Project a world point through a column-major 4×4 MVP to CSS-pixel screen coordinates.
- * Returns `visible: false` when the point is at/behind the camera (w ≤ 0). Pure — unit-tested.
+ * Re-exported from napari-js, which owns the projection now.
+ *
+ * This used to be a local copy: the same column-major multiply, perspective divide and y-flip
+ * that {@link NapariVisualizerService.getSpatialScreenProjection} ALSO carried, written twice
+ * with two different behind-the-eye conventions. The renderer owns the camera and the clip
+ * convention, so it owns the projection; kept as a named export here only so the overlays that
+ * import it from this module do not all have to change.
  */
-export declare function projectPoint(mvp: ArrayLike<number>, p: [number, number, number], vw: number, vh: number): {
-    x: number;
-    y: number;
-    visible: boolean;
-};
+import { projectPoint } from 'napari-js';
+export { projectPoint };
 export declare class NapariAxesLabels {
     private readonly host;
     private readonly camera3d;

package/lib/implementations/napari-js/napari-region-overlay.d.ts

@@ -1,7 +1,14 @@
 import { IRegionOverlay, RegionToolMode } from '../../contracts/region-overlay.contract';
 import { RegionStore } from '../../store/region-store.service';
-/** The slice of the napari Viewer the overlay needs (coord transforms + control gating). */
-interface OverlayViewer {
+/**
+ * The slice of the napari Viewer the overlay needs (coord transforms + control gating).
+ *
+ * Exported because the 3D spatial mode supplies a SCREEN-SPACE implementation of it: there the
+ * drawn shape is a lasso in canvas pixels, not a rectangle in image space, so "world" is the
+ * canvas itself and both transforms collapse to identity. That lets the 3D view reuse this whole
+ * overlay — every tool, the handles, the store round-trip — with no 3D-specific drawing code.
+ */
+export interface OverlayViewer {
     canvasToWorld(clientX: number, clientY: number): [number, number];
     worldToCanvas(worldX: number, worldY: number): [number, number];
     setControlsEnabled(enabled: boolean): void;
@@ -45,11 +52,39 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
      *  rectangle corner. `anchor` is the fixed opposite corner for a rectangle resize. */
     private edit;
     constructor(host: HTMLElement, viewer: OverlayViewer, store: RegionStore);
+    /**
+     * Whether a region tool currently owns the pointer.
+     *
+     * Exposed so the spatial views can tell a bare click on the cloud (select the
+     * class under the cursor) from a click that belongs to a drawing gesture —
+     * placing a polygon vertex is also a click that does not move, and it must not
+     * change the selection behind the shape being drawn.
+     */
+    get toolActive(): boolean;
     setMode(mode: RegionToolMode): void;
     setSelectedBezier(bezier: boolean): void;
+    /**
+     * How finely a drawn vertex may be placed, in world units.
+     *
+     * One by default, because for an image the world IS pixels and a region should align to
+     * them. A dataset whose coordinates are not pixels sets it finer — seqFISH's whole
+     * sample spans about 5 x 7 units, where whole-unit vertices leave roughly six by eight
+     * placeable positions and no ROI can be drawn at all.
+     */
+    private worldQuantum;
+    setWorldQuantum(quantum: number): void;
     destroy(): void;
-    /** Pointer client coords → rounded image coords. */
+    /** Pointer client coords → world coords, snapped to {@link worldQuantum}. */
     private toImage;
+    /**
+     * World units spanned by one screen pixel, measured through the viewer's own transform.
+     *
+     * Read from the transform rather than from the camera, so it holds for both the 2D and
+     * the 3D screen-space adapters without either having to expose a zoom. Falls back to 1
+     * if the transform gives nothing usable, which keeps the established pixel behaviour
+     * rather than collapsing the threshold to zero and recording a point per event.
+     */
+    private worldPerCanvasPixel;
     /** Image coords → SVG-local px (the svg overlays the canvas at the same client rect). */
     private toLocal;
     private readonly onPointerDown;
@@ -112,4 +147,3 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     private drawDraft;
     private styleDraft;
 }
-export {};

package/lib/implementations/napari-js/napari-scale-bar.d.ts

@@ -8,8 +8,13 @@
 /** Format a length given in micrometres, picking the unit that suits its magnitude (jit-service
  *  normalises whatever unit Bio-Formats reports to µm). */
 export declare function formatUm(um: number): string;
-/** The slice of the napari Camera the scale bar reads (zoom = CSS px per world/image pixel). */
-interface ScaleBarCamera {
+/**
+ * The slice of the napari Camera the scale bar reads (zoom = CSS px per world/image pixel).
+ *
+ * Exported so the 3D spatial view can satisfy it with a shim: an orbit camera has no `zoom`, but
+ * px-per-world-unit AT THE PIVOT DEPTH is well defined, and that is what a 3D scale bar means.
+ */
+export interface ScaleBarCamera {
     readonly zoom: number;
     readonly changed: {
         connect(listener: () => void): () => void;
@@ -28,4 +33,3 @@ export declare class NapariScaleBar {
     private update;
     destroy(): void;
 }
-export {};

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

@@ -0,0 +1,32 @@
+/**
+ * Cursor tooltip naming the observation under the pointer, for the spatial-omics
+ * views — the same overlay-in-the-host pattern as {@link NapariScaleBar}.
+ *
+ * A 34-entry legend cannot be read back from a dot: several classes get similar
+ * colours, and matching one to a swatch by eye is the job a tooltip removes. It
+ * shows what the cloud is CURRENTLY coloured by, so it always agrees with the
+ * legend beside it.
+ *
+ * Deliberately not PrimeNG's `pTooltip`: that binds to an element, and these
+ * points are pixels in a WebGPU canvas with no DOM of their own.
+ */
+export declare class NapariSpatialTooltip {
+    private readonly host;
+    private readonly el;
+    private readonly primary;
+    private readonly secondary;
+    /** Gap between the cursor and the box, so the box never sits under the arrow. */
+    private static readonly OFFSET;
+    constructor(host: HTMLElement);
+    /**
+     * Show `lines` at a point given in HOST-relative pixels.
+     *
+     * Flips to the other side of the cursor near an edge rather than being clipped
+     * by the host — a tooltip half outside the plot is worse than one on the left.
+     */
+    show(lines: readonly string[], hostX: number, hostY: number): void;
+    hide(): void;
+    /** True while the box is on screen — for tests, and to skip redundant hides. */
+    get visible(): boolean;
+    dispose(): void;
+}