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

package/lib/spatial-controls/spatial-controls.component.d.ts

@@ -0,0 +1,257 @@
+import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
+import { IVisualizer, ISpatialControls } from '../contracts/visualizer.contract';
+import { SpatialDataset } from '../contracts/spatial-dataset.contract';
+import { ColormapNode, SpatialViewState } from '../contracts/display-types';
+import { SpatialSelectionMask } from '../spatial/spatial-selection';
+import * as i0 from "@angular/core";
+/** One legend row for a categorical colouring. */
+export interface SpatialLegendEntry {
+    label: string;
+    color: string;
+}
+/**
+ * Spatial-omics controls: a non-modal, resizable, draggable dialog for choosing
+ * what the observation markers are coloured by, and how they are drawn.
+ *
+ * Depends only on {@link ISpatialControls}, reached through the `VISUALIZER`
+ * contract token — never a concrete backend — mirroring how
+ * `ChannelHistogramComponent` depends only on `CHANNEL_HISTOGRAM_API`. When no
+ * host has bound `SPATIAL_DATA_PORT`, `getSpatialControls()` returns null and
+ * the dialog renders an explanatory empty state rather than dead controls.
+ *
+ * The legend swatches and the continuous colour bar are built with the SAME
+ * functions the renderer uses (`categoryColors` → `resolveCategoryColors`,
+ * `spatialContinuousLut`), so the key cannot drift from what is on screen.
+ */
+export declare class SpatialControlsComponent implements OnInit, OnDestroy {
+    private readonly viz;
+    /** The embedded chart, so a dialog resize can re-fit it. */
+    private charts?;
+    /**
+     * Re-fit the chart after the dialog is resized.
+     *
+     * Plotly does not follow a container resize on its own — its `responsive`
+     * option listens for WINDOW resizes only, so dragging the dialog's handle
+     * reaches it through nothing. PrimeNG tells us when the drag ends, which is a
+     * far more direct signal than watching boxes, and firing once on release means
+     * no relayout churn during the drag.
+     */
+    onResizeEnd(): void;
+    /** Dialog visibility, two-way bound so a toolbar button can open it. */
+    visible: boolean;
+    /** Set while the 3D cloud is the active mode. Changes what the ROI selection
+     *  MEANS — a screen-space lasso cutting through the cloud's full depth rather
+     *  than a shape in tissue coordinates — so the hint below it says so. */
+    is3d: boolean;
+    visibleChange: EventEmitter<boolean>;
+    readonly clipOptions: {
+        label: string;
+        value: [number, number];
+    }[];
+    /** Null when the host bound no `SPATIAL_DATA_PORT`. */
+    controls: ISpatialControls | null;
+    dataset: SpatialDataset | null;
+    view: SpatialViewState;
+    /** Colour-by column choices — "None" plus every column the dataset declares. */
+    columnOptions: {
+        label: string;
+        value: string | null;
+    }[];
+    selectedColumn: string | null;
+    /** Virtual-scrolled only past this many options: the scroller earns its
+     *  complexity for a few thousand names, and for eight it adds only overhead —
+     *  a virtual viewport that short swallows the clicks it is meant to forward. */
+    readonly geneVirtualScrollFrom = 200;
+    /**
+     * Gene picker: a filterable dropdown rather than a free-text typeahead, so the
+     * options are visible before anything is typed and each keystroke narrows a list
+     * the user can see.
+     *
+     * `geneOptions` is the full name list when the dataset inlines it (a targeted
+     * panel: 8 for the ABC demo, 300–5,000 for Xenium/CosMx). A whole-transcriptome
+     * dataset does not ship its ~31k names, so there the list is what the port's last
+     * search returned and filtering is server-side — same control either way.
+     */
+    geneOptions: {
+        label: string;
+        value: string;
+    }[];
+    /**
+     * Every gene the dataset inlined, whether or not it is currently an option.
+     *
+     * Held as plain strings and searched per keystroke. A whole-transcriptome dataset
+     * inlines ~18k names — cheap to keep, ruinous to hand a dropdown all at once — so
+     * {@link geneOptions} is only ever the best few hundred of these.
+     */
+    private geneNames;
+    selectedGene: string | null;
+    /** True when the options come from the port per keystroke rather than a resident
+     *  list, which changes what an empty list means (nothing matched *yet*). */
+    genesAreRemote: boolean;
+    geneSearchFailed: boolean;
+    /** Categorical key, or null when the active colouring is continuous. */
+    legend: SpatialLegendEntry[] | null;
+    /** CSS gradient for a continuous colouring, or null when categorical. */
+    colorBarCss: string | null;
+    /** Current selection — drives the count, the Clear button and the muting. */
+    selection: SpatialSelectionMask;
+    /** The legend row whose category is currently selected, for highlighting. */
+    selectedCategory: number | null;
+    /** An ROI selection that matched nothing, so the UI can say so rather than
+     *  looking like the button did nothing. */
+    selectionMissed: boolean;
+    /**
+     * Whether the Distribution section is expanded. Collapsed by default: the
+     * panel's primary job is the colour controls, and the chart roughly doubles
+     * its height.
+     */
+    chartsOpen: boolean;
+    /** Per-instance id for the collapsible body, so `aria-controls` points at one
+     *  element and expanding the second panel cannot scroll the first one's chart. */
+    readonly chartsBodyId: string;
+    /**
+     * The dataset's imaged section positions, or null when its z is continuous
+     * rather than sectioned. Read once per dataset — the scan walks the z of every
+     * observation, so it must not sit in a template getter.
+     */
+    sections: Float32Array | null;
+    /**
+     * Colormap tree for the continuous colour scale, and the node currently picked
+     * from it. The library's own `COLORMAP_OPTIONS`, shown with the same swatches
+     * the image's colormap picker uses — choosing a gradient is a visual decision,
+     * so a list of names would be the wrong control.
+     */
+    colormapOptions: ColormapNode[];
+    selectedColormapNode: ColormapNode | null;
+    private colormap;
+    private reverse;
+    /** Guards the gene typeahead and the legend/colour-bar rebuild: both are async
+     *  and both are driven by input the user changes faster than they resolve. */
+    private geneSearchToken;
+    private keyToken;
+    private readonly subs;
+    constructor(viz: IVisualizer);
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    onVisibleChange(value: boolean): void;
+    /** Column dropdown. Choosing a column supersedes any gene selection. */
+    onColumn(name: string | null): void;
+    /**
+     * A keystroke in the gene dropdown's filter box.
+     *
+     * With the names resident the dropdown filters them itself and this only clears a
+     * stale failure. Without them there is nothing to filter, so the query goes to the
+     * port and its answer BECOMES the option list — the same control, filtering one
+     * hop further away.
+     */
+    onGeneFilter(query: string): Promise<void>;
+    /** A gene was picked; it supersedes any column selection. */
+    onGene(name: string | null): void;
+    /** Select every observation inside the drawn regions (their union). */
+    selectFromRegions(): void;
+    /** Legend click: select one category. Clicking the active row clears it, so a
+     *  second click is an undo rather than a no-op. */
+    selectCategory(index: number): Promise<void>;
+    /**
+     * Expand or collapse the distribution section.
+     *
+     * Expanding SCROLLS it into view, because the panel is taller than the viewport
+     * once this section is open and the chart is its last row: expanding it drew a
+     * chart ~300 px below the fold, which reads as the section being empty. The
+     * scroll is deferred a task so the chart's own deferred first draw has given the
+     * body its height.
+     */
+    toggleCharts(): void;
+    clearSelection(): void;
+    /** True while a selection is active — everything else renders muted. */
+    get hasSelection(): boolean;
+    onPointScale(value: number | undefined): void;
+    onOpacity(value: number | undefined): void;
+    onLogScale(on: boolean): void;
+    /**
+     * Set when the active categorical colouring has more categories than the 3D
+     * cloud can keep apart, so the points are drawing FLAT.
+     *
+     * Said in the panel rather than left to a console warning: `subclass` (338) is
+     * served precisely because the density volumes and the 2D view can render it, and
+     * a user who picks it in the cloud and sees one colour deserves to know both why
+     * and what to do instead.
+     */
+    get exceedsCloudPalette(): boolean;
+    /** The ceiling itself, for the message. */
+    readonly cloudPaletteLimit = 95;
+    onGeneMap(on: boolean): void;
+    /** 3D: smooth the per-section sheets along z into a continuous volume. */
+    onGeneMapVolume(on: boolean): void;
+    /** 3D: restrict the sheets to one imaged section. */
+    onGeneMapOneSection(on: boolean): void;
+    onGeneMapSection(value: number | undefined): void;
+    get geneMapOneSection(): boolean;
+    /** "12 of 53" for the gene map's own section, 1-based like the cloud's. */
+    get geneMapSectionLabel(): string;
+    onGeneMapSmoothing(value: number | undefined): void;
+    onGeneMapOpacity(value: number | undefined): void;
+    /**
+     * What the 3D gene map is currently showing, said plainly — the sheets are a
+     * measurement and the volume is an estimate, and the panel has to be the place
+     * that says which one is on screen.
+     */
+    get geneMapVolumeNote(): string;
+    /** True while a gene is the colour source — the only thing a gene map can map. */
+    get canMapGene(): boolean;
+    onShowVolume(on: boolean): void;
+    onVolumeOpacity(value: number | undefined): void;
+    onShowPoints(on: boolean): void;
+    /** The "one section at a time" switch: null restores the whole stack. */
+    onOneSection(on: boolean): void;
+    onPointSection(value: number | undefined): void;
+    /** True while the cloud is restricted to a single section. */
+    get oneSection(): boolean;
+    /** Highest section index the slider can reach. */
+    get lastSection(): number;
+    /** "12 of 53" — 1-based, because the sections are slides, not array slots. */
+    get sectionLabel(): string;
+    /** Whether this dataset has sections to pick from at all. */
+    get isSectioned(): boolean;
+    onDensityVolume(on: boolean): void;
+    onDensitySmoothing(value: number | undefined): void;
+    /** What the density volumes are actually showing, said plainly — an estimate is
+     *  only honest if the reader knows it is one, and which clusters are in view. */
+    get densityNote(): string;
+    /** Mirrors the renderer's cap, for the note only. */
+    private static readonly DENSITY_MAX_CLUSTERS;
+    onClip(value: [number, number]): void;
+    reset(): void;
+    /**
+     * Description of the active column, when it has one. Surfaced because a
+     * DERIVED column (k-means clusters, QC totals computed at conversion) must not
+     * read as though it came with the data.
+     */
+    get activeDescription(): string | null;
+    /** Label for the current colouring, for the key's heading. */
+    get colorByLabel(): string;
+    /** True when the active colouring is a categorical column (drives the key). */
+    get isCategorical(): boolean;
+    /** Whether log/clip apply — they are continuous-only knobs. */
+    get isContinuous(): boolean;
+    private columnLabel;
+    /** Rebuild the legend or colour bar for the current colouring. */
+    private refreshKey;
+    /**
+     * The continuous colour scale's colormap. Clearing it goes back to following
+     * the image's, which is the default.
+     */
+    onContinuousColormap(node: ColormapNode | null): void;
+    /** The tree node holding a colormap value, so the picker shows what is in use. */
+    private colormapNodeFor;
+    /**
+     * `linear-gradient(...)` sampling the active colormap at 16 stops.
+     *
+     * Resolved exactly the way the renderer resolves it — 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 no key.
+     */
+    private buildColorBar;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialControlsComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialControlsComponent, "spatial-controls", never, { "visible": { "alias": "visible"; "required": false; }; "is3d": { "alias": "is3d"; "required": false; }; }, { "visibleChange": "visibleChange"; }, never, never, false, never>;
+}

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

@@ -0,0 +1,27 @@
+import { Observable } from 'rxjs';
+import { SpatialSelectionMask } from '../spatial/spatial-selection';
+import * as i0 from "@angular/core";
+/**
+ * The set of currently-selected spatial observations, shared the way
+ * `RegionStore` shares regions: one store, many writers (an ROI selection, a
+ * legend click, a future chart brush), one reader per consumer.
+ *
+ * Deliberately thin — every rule about WHICH observations are selected lives in
+ * the pure `spatial-selection.ts`; this only holds the answer and announces it.
+ */
+export declare class SpatialSelectionStore {
+    private readonly selection$;
+    /** Emits on every change, including a clear. */
+    getSelection$(): Observable<SpatialSelectionMask>;
+    /** Synchronous read, for a renderer building its first frame. */
+    current(): SpatialSelectionMask;
+    /** True when nothing is selected — the state in which nothing is muted. */
+    isEmpty(): boolean;
+    /** Replace the selection. An empty result is published like any other, so a
+     *  "selected nothing" ROI visibly clears rather than silently keeping the
+     *  previous selection on screen. */
+    set(selection: SpatialSelectionMask): void;
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialSelectionStore, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SpatialSelectionStore>;
+}

package/lib/store/visualizer-store.service.d.ts

@@ -4,6 +4,7 @@ import { ClassPreset, PresetSet } from '../models/class-preset';
 import { PreferencesPort } from '../contracts/ports/preferences.port';
 import { IImageMetadata } from '../contracts/image.contract';
 import { IChannelState } from '../contracts/channel-histogram-api.contract';
+import { SpatialViewState } from '../contracts/display-types';
 import * as i0 from "@angular/core";
 /**
  * Backend-neutral store for the **visualization session** — the state that
@@ -43,6 +44,10 @@ export declare class VisualizerStore {
     private readonly savePresets$;
     private presetsLoaded;
     private readonly activeTool$;
+    /** Spatial-omics display state (colour source, point size, alpha, scaling).
+     *  Held here, next to the colormap/channel state, so the active backend reacts
+     *  to an edit exactly as it does for an image. */
+    private readonly spatialView$;
     constructor(http?: HttpClient | null, prefsPort?: PreferencesPort | null);
     /**
      * Resolve the colormap tree's LUT keys (e.g. "GREYS_LUT") to their colour
@@ -122,6 +127,14 @@ export declare class VisualizerStore {
     resetPresets(): void;
     /** Force a (debounced) write-back of the current preset set. */
     persistPresets(): void;
+    getSpatialView$(): Observable<SpatialViewState>;
+    /** Synchronous read, for a renderer building its first frame. */
+    currentSpatialView(): SpatialViewState;
+    /** Patch the spatial view state; emits once with the merged value. */
+    setSpatialView(partial: Partial<SpatialViewState>): void;
+    /** Reset to defaults — e.g. when a different dataset is selected, where the
+     *  previous colour column almost certainly does not exist. */
+    resetSpatialView(): void;
     getActiveTool$(): Observable<string | null>;
     getActiveTool(): string | null;
     setActiveTool(tool: string | null): void;

package/lib/toolbar/toolbar.component.d.ts

@@ -30,6 +30,13 @@ export declare class ToolbarComponent implements OnChanges {
     zIndex: number;
     /** True for any 2D (non Surface-3D) plot type. */
     isHeatmap: boolean;
+    /**
+     * Region tools apply even though this is a 3D view, because they draw a
+     * SCREEN-SPACE lasso (the 3D spatial cloud). Separate from {@link isHeatmap},
+     * which means "2D view" and also drives the zoom tools and the 3D camera
+     * controls — flipping that would show 2D pan/zoom and hide the orbit controls.
+     */
+    is3dRegions: boolean;
     activeDragMode: string | null;
     activeSurface3dMode: string;
     /** Whether the napari 3D axes/scale gizmo is currently shown (drives the toggle's look). */
@@ -83,6 +90,8 @@ export declare class ToolbarComponent implements OnChanges {
     isoRangeChange: EventEmitter<number[] | undefined>;
     /** Open the Channels & Histogram dialog (brightness/contrast, colormap, …). */
     openChannelHistogram: EventEmitter<void>;
+    /** Open the spatial-omics controls (colour-by, legend, point display). */
+    openSpatialControls: EventEmitter<void>;
     openRegionEditor: EventEmitter<void>;
     selectStackOption: EventEmitter<{
         name: string;
@@ -190,6 +199,11 @@ export declare class ToolbarComponent implements OnChanges {
     /** The Image plot type renders as a natively pan/zoom-able raster, so the
      *  generic zoom/pan tools are hidden. */
     get isImageView(): boolean;
+    /** Either spatial-omics mode is active, so its controls are worth offering.
+     *  The 3D cloud needs the panel MORE than the 2D view does, not less: colouring,
+     *  the legend and category show/hide are the only way to make sense of a
+     *  million overlapping points. */
+    get isSpatialMode(): boolean;
     /** A plot-type icon is a PrimeNG font glyph (e.g. `pi pi-image`) rather than an
      *  SVG asset path — drives which element the selector item template renders. */
     isPiIcon(icon: string | undefined): boolean;
@@ -197,8 +211,10 @@ export declare class ToolbarComponent implements OnChanges {
      *  (jit-ui#102). Gates the polygon / add-vertex / delete-vertex / Bézier-convert tools. */
     get supportsRegionVertexTools(): boolean;
     /** Plot types that scrub a z-stack live (the renderer swaps the slice in place): the OSD Image
-     *  view, the napari-js WebGPU image, and the napari-js surface — which rebuilds the height field
-     *  from the picked slice (jit-ui#102). Drives the per-slice slider. */
+     *  view, the napari-js WebGPU image, the napari-js surface — which rebuilds the height field
+     *  from the picked slice (jit-ui#102) — and the 2D spatial-omics view, where a 3D dataset's
+     *  registered volume is the image and the slider picks the section whose observations are
+     *  drawn. Drives the per-slice slider. */
     get showsLiveSliceScrubber(): boolean;
     /** Any napari-js WebGPU plot type. The single-image/stack toggle + slice-number field are
      *  Plotly-only stack controls, so they're hidden for napari (jit-ui#102). */
@@ -214,5 +230,5 @@ export declare class ToolbarComponent implements OnChanges {
     get isIntensityCapable(): boolean;
     showHelp(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<ToolbarComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarComponent, "plotting-toolbar", never, { "imageInfo": { "alias": "imageInfo"; "required": false; }; "plotTypeOptions": { "alias": "plotTypeOptions"; "required": false; }; "selectedPlotType": { "alias": "selectedPlotType"; "required": false; }; "isoRange": { "alias": "isoRange"; "required": false; }; "maxIndex": { "alias": "maxIndex"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "isHeatmap": { "alias": "isHeatmap"; "required": false; }; "activeDragMode": { "alias": "activeDragMode"; "required": false; }; "activeSurface3dMode": { "alias": "activeSurface3dMode"; "required": false; }; "axesVisible": { "alias": "axesVisible"; "required": false; }; "wireframeActive": { "alias": "wireframeActive"; "required": false; }; "resolutionScale": { "alias": "resolutionScale"; "required": false; }; "wandSensitivity": { "alias": "wandSensitivity"; "required": false; }; "brushSize": { "alias": "brushSize"; "required": false; }; "vertexEraserRadius": { "alias": "vertexEraserRadius"; "required": false; }; "canUndo": { "alias": "canUndo"; "required": false; }; "canRedo": { "alias": "canRedo"; "required": false; }; "stackOptions": { "alias": "stackOptions"; "required": false; }; "tools": { "alias": "tools"; "required": false; }; "imageSmoothingEnabled": { "alias": "imageSmoothingEnabled"; "required": false; }; "samModels": { "alias": "samModels"; "required": false; }; "samModelId": { "alias": "samModelId"; "required": false; }; "contributedTools": { "alias": "contributedTools"; "required": false; }; "toolModelIds": { "alias": "toolModelIds"; "required": false; }; }, { "selectPlotType": "selectPlotType"; "addProfileLine": "addProfileLine"; "toggleImageSmoothing": "toggleImageSmoothing"; "isoRangeChange": "isoRangeChange"; "openChannelHistogram": "openChannelHistogram"; "openRegionEditor": "openRegionEditor"; "selectStackOption": "selectStackOption"; "zScrub": "zScrub"; "zSlide": "zSlide"; "zIndexInput": "zIndexInput"; "reloadAndPlot": "reloadAndPlot"; "downloadImage": "downloadImage"; "autoscaleImage": "autoscaleImage"; "toggleDragMode": "toggleDragMode"; "zoomIn": "zoomIn"; "zoomOut": "zoomOut"; "toggleSurface3dMode": "toggleSurface3dMode"; "resetSurfaceCamera": "resetSurfaceCamera"; "toggleAxes": "toggleAxes"; "toggleWireframe": "toggleWireframe"; "selectResolution": "selectResolution"; "deleteRegion": "deleteRegion"; "undoRegion": "undoRegion"; "redoRegion": "redoRegion"; "segmentRegions": "segmentRegions"; "segmentCellpose": "segmentCellpose"; "runTool": "runTool"; "toolModelChange": "toolModelChange"; "openToolParams": "openToolParams"; "samModelChange": "samModelChange"; "wandSensitivityChange": "wandSensitivityChange"; "brushSizeChange": "brushSizeChange"; "vertexEraserRadiusChange": "vertexEraserRadiusChange"; }, never, ["*"], false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarComponent, "plotting-toolbar", never, { "imageInfo": { "alias": "imageInfo"; "required": false; }; "plotTypeOptions": { "alias": "plotTypeOptions"; "required": false; }; "selectedPlotType": { "alias": "selectedPlotType"; "required": false; }; "isoRange": { "alias": "isoRange"; "required": false; }; "maxIndex": { "alias": "maxIndex"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "isHeatmap": { "alias": "isHeatmap"; "required": false; }; "is3dRegions": { "alias": "is3dRegions"; "required": false; }; "activeDragMode": { "alias": "activeDragMode"; "required": false; }; "activeSurface3dMode": { "alias": "activeSurface3dMode"; "required": false; }; "axesVisible": { "alias": "axesVisible"; "required": false; }; "wireframeActive": { "alias": "wireframeActive"; "required": false; }; "resolutionScale": { "alias": "resolutionScale"; "required": false; }; "wandSensitivity": { "alias": "wandSensitivity"; "required": false; }; "brushSize": { "alias": "brushSize"; "required": false; }; "vertexEraserRadius": { "alias": "vertexEraserRadius"; "required": false; }; "canUndo": { "alias": "canUndo"; "required": false; }; "canRedo": { "alias": "canRedo"; "required": false; }; "stackOptions": { "alias": "stackOptions"; "required": false; }; "tools": { "alias": "tools"; "required": false; }; "imageSmoothingEnabled": { "alias": "imageSmoothingEnabled"; "required": false; }; "samModels": { "alias": "samModels"; "required": false; }; "samModelId": { "alias": "samModelId"; "required": false; }; "contributedTools": { "alias": "contributedTools"; "required": false; }; "toolModelIds": { "alias": "toolModelIds"; "required": false; }; }, { "selectPlotType": "selectPlotType"; "addProfileLine": "addProfileLine"; "toggleImageSmoothing": "toggleImageSmoothing"; "isoRangeChange": "isoRangeChange"; "openChannelHistogram": "openChannelHistogram"; "openSpatialControls": "openSpatialControls"; "openRegionEditor": "openRegionEditor"; "selectStackOption": "selectStackOption"; "zScrub": "zScrub"; "zSlide": "zSlide"; "zIndexInput": "zIndexInput"; "reloadAndPlot": "reloadAndPlot"; "downloadImage": "downloadImage"; "autoscaleImage": "autoscaleImage"; "toggleDragMode": "toggleDragMode"; "zoomIn": "zoomIn"; "zoomOut": "zoomOut"; "toggleSurface3dMode": "toggleSurface3dMode"; "resetSurfaceCamera": "resetSurfaceCamera"; "toggleAxes": "toggleAxes"; "toggleWireframe": "toggleWireframe"; "selectResolution": "selectResolution"; "deleteRegion": "deleteRegion"; "undoRegion": "undoRegion"; "redoRegion": "redoRegion"; "segmentRegions": "segmentRegions"; "segmentCellpose": "segmentCellpose"; "runTool": "runTool"; "toolModelChange": "toolModelChange"; "openToolParams": "openToolParams"; "samModelChange": "samModelChange"; "wandSensitivityChange": "wandSensitivityChange"; "brushSizeChange": "brushSizeChange"; "vertexEraserRadiusChange": "vertexEraserRadiusChange"; }, never, ["*"], false, never>;
 }

package/lib/visualization.module.d.ts

@@ -4,29 +4,33 @@ import * as i2 from "./toolbar/toolbar.component";
 import * as i3 from "./region-editor/region-editor.component";
 import * as i4 from "./hex-color-picker/hex-color-picker.component";
 import * as i5 from "./channel-histogram/channel-histogram.component";
-import * as i6 from "@angular/common";
-import * as i7 from "@angular/forms";
-import * as i8 from "primeng/toolbar";
-import * as i9 from "primeng/button";
-import * as i10 from "primeng/menu";
-import * as i11 from "primeng/dropdown";
-import * as i12 from "primeng/slider";
-import * as i13 from "primeng/treeselect";
-import * as i14 from "primeng/inputnumber";
-import * as i15 from "primeng/dialog";
-import * as i16 from "primeng/contextmenu";
-import * as i17 from "primeng/progressbar";
-import * as i18 from "primeng/toast";
-import * as i19 from "primeng/tooltip";
-import * as i20 from "primeng/ripple";
-import * as i21 from "primeng/table";
-import * as i22 from "primeng/paginator";
-import * as i23 from "primeng/overlaypanel";
-import * as i24 from "primeng/confirmdialog";
-import * as i25 from "primeng/inputtext";
-import * as i26 from "primeng/checkbox";
-import * as i27 from "primeng/radiobutton";
-import * as i28 from "primeng/selectbutton";
+import * as i6 from "./spatial-controls/spatial-controls.component";
+import * as i7 from "./spatial-controls/spatial-charts/spatial-charts.component";
+import * as i8 from "@angular/common";
+import * as i9 from "@angular/forms";
+import * as i10 from "primeng/toolbar";
+import * as i11 from "primeng/button";
+import * as i12 from "primeng/menu";
+import * as i13 from "primeng/dropdown";
+import * as i14 from "primeng/slider";
+import * as i15 from "primeng/treeselect";
+import * as i16 from "primeng/inputnumber";
+import * as i17 from "primeng/dialog";
+import * as i18 from "primeng/contextmenu";
+import * as i19 from "primeng/progressbar";
+import * as i20 from "primeng/toast";
+import * as i21 from "primeng/tooltip";
+import * as i22 from "primeng/ripple";
+import * as i23 from "primeng/table";
+import * as i24 from "primeng/paginator";
+import * as i25 from "primeng/overlaypanel";
+import * as i26 from "primeng/confirmdialog";
+import * as i27 from "primeng/inputtext";
+import * as i28 from "primeng/checkbox";
+import * as i29 from "primeng/multiselect";
+import * as i30 from "primeng/radiobutton";
+import * as i31 from "primeng/selectbutton";
+import * as i32 from "primeng/autocomplete";
 /**
  * Self-contained plotting UI: the {@link VisualizerComponent} (plot surface
  * + render orchestration), its {@link ToolbarComponent}, and the
@@ -40,6 +44,6 @@ import * as i28 from "primeng/selectbutton";
  */
 export declare class VisualizationModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<VisualizationModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<VisualizationModule, [typeof i1.VisualizerComponent, typeof i2.ToolbarComponent, typeof i3.RegionEditorComponent, typeof i4.HexColorPickerComponent, typeof i5.ChannelHistogramComponent], [typeof i6.CommonModule, typeof i7.FormsModule, typeof i8.ToolbarModule, typeof i9.ButtonModule, typeof i10.MenuModule, typeof i11.DropdownModule, typeof i12.SliderModule, typeof i13.TreeSelectModule, typeof i14.InputNumberModule, typeof i15.DialogModule, typeof i16.ContextMenuModule, typeof i17.ProgressBarModule, typeof i18.ToastModule, typeof i19.TooltipModule, typeof i20.RippleModule, typeof i21.TableModule, typeof i22.PaginatorModule, typeof i23.OverlayPanelModule, typeof i24.ConfirmDialogModule, typeof i25.InputTextModule, typeof i26.CheckboxModule, typeof i27.RadioButtonModule, typeof i28.SelectButtonModule], [typeof i1.VisualizerComponent, typeof i3.RegionEditorComponent, typeof i4.HexColorPickerComponent, typeof i5.ChannelHistogramComponent]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<VisualizationModule, [typeof i1.VisualizerComponent, typeof i2.ToolbarComponent, typeof i3.RegionEditorComponent, typeof i4.HexColorPickerComponent, typeof i5.ChannelHistogramComponent, typeof i6.SpatialControlsComponent, typeof i7.SpatialChartsComponent], [typeof i8.CommonModule, typeof i9.FormsModule, typeof i10.ToolbarModule, typeof i11.ButtonModule, typeof i12.MenuModule, typeof i13.DropdownModule, typeof i14.SliderModule, typeof i15.TreeSelectModule, typeof i16.InputNumberModule, typeof i17.DialogModule, typeof i18.ContextMenuModule, typeof i19.ProgressBarModule, typeof i20.ToastModule, typeof i21.TooltipModule, typeof i22.RippleModule, typeof i23.TableModule, typeof i24.PaginatorModule, typeof i25.OverlayPanelModule, typeof i26.ConfirmDialogModule, typeof i27.InputTextModule, typeof i28.CheckboxModule, typeof i29.MultiSelectModule, typeof i30.RadioButtonModule, typeof i31.SelectButtonModule, typeof i32.AutoCompleteModule], [typeof i1.VisualizerComponent, typeof i3.RegionEditorComponent, typeof i4.HexColorPickerComponent, typeof i5.ChannelHistogramComponent, typeof i6.SpatialControlsComponent, typeof i7.SpatialChartsComponent]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<VisualizationModule>;
 }

package/lib/visualizer.component.d.ts

@@ -15,6 +15,7 @@ import { CellSegmentToolService } from './toolbar/segmentation/cell-segment-tool
 import { NumberParamSpec, SelectParamSpec, ToolParamSpec, ToolbarToolContribution } from './contracts/toolbar-tool.contract';
 import { ToolbarToolVisibility } from './contracts/toolbar-config';
 import { VizConfig } from './contracts/viz-config';
+import { SpatialDataPort } from './contracts/ports/spatial-data.port';
 import * as i0 from "@angular/core";
 export declare class VisualizerComponent implements OnInit, OnChanges, AfterViewInit, OnDestroy {
     private state;
@@ -28,6 +29,7 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     private samPointTool;
     private regionOps;
     private vizConfig?;
+    private spatialData?;
     /** Per-instance toast key. MessageService is a global singleton, so two live
      *  `<visualizer>` instances (main viewer + pipeline-dialog preview) sharing
      *  one key would each render the same message — a duplicate toast. A unique
@@ -177,6 +179,8 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     selectedColormap: any;
     /** Channels & Histogram dialog visibility (opened from the toolbar). */
     showChannelHistogram: boolean;
+    /** Spatial-omics controls dialog visibility (toolbar button). */
+    showSpatialControls: boolean;
     /** Region Editor dialog visibility (opened from the toolbar). */
     showRegionEditor: boolean;
     /** Region Editor dialog width. On open it is set to the configured host
@@ -230,6 +234,10 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     private profileDragMoveListener?;
     private profileDragUpListener?;
     private profileResizeListener?;
+    /** True while the 3D spatial cloud is the active mode. The controls drop the ROI
+     *  selection there: region tools are screen-space, and against an orbiting
+     *  camera a drawn rectangle has no fixed meaning in the data. */
+    get isSpatial3dMode(): boolean;
     /** LINE plot type shows the image + draggable line ROI + intensity inset. */
     get isProfileMode(): boolean;
     /** True for the Image plot type, which renders as a natively pan/zoom-able
@@ -239,6 +247,24 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     /** Isosurface band as a 0–255 slider position, mapped onto the volume's real
      *  intensity range by the renderer. Defaults to the full range. */
     isoRange: number[];
+    /** Whether a spatial-omics dataset is currently published on
+     *  `SPATIAL_DATA_PORT` — gates the spatial plot types in the selector. */
+    private hasSpatialDataset;
+    /** Whether that dataset's observations carry a z, gating the 3D spatial mode. */
+    private hasSpatial3dDataset;
+    /** Whether it carries a registered volume. Change detection only: a volume
+     *  appearing is what publishes it as the image, and the plot-type gates then
+     *  see an ordinary grayscale stack. */
+    private hasSpatialVolume;
+    /** Dataset identity + capability shape the last emission was handled at, so a
+     *  switch between two datasets of the same shape is not mistaken for a repeat. */
+    private spatialDatasetKey;
+    /** Dataset + geometry the currently published volume image was built from, so a
+     *  re-emitted dataset doesn't re-fetch megabytes or reset the user's scrub. */
+    private volumeImageKey;
+    /** Blob URLs backing that image — ours to revoke. */
+    private volumeImageUrls;
+    private spatialDatasetSubscription?;
     plotWidthSubscription?: Subscription;
     imageLoadingSubscription?: Subscription;
     imgLoadingMessageSubscription?: Subscription;
@@ -250,7 +276,7 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     private wheelListener?;
     /** Debounced z-slice scrubbing (see SliceScrubber — refactoring plan Step 7). */
     private readonly scrubber;
-    constructor(state: ImageStatePort, plotService: IVisualizer, messageService: MessageService, ngZone: NgZone, cdr: ChangeDetectorRef, session: VisualizerStore, samTool: SamToolService, cellSegmentTool: CellSegmentToolService, samPointTool: SamPointToolService, regionOps: RegionOpsService, vizConfig?: VizConfig | undefined, toolContributions?: readonly ToolbarToolContribution[]);
+    constructor(state: ImageStatePort, plotService: IVisualizer, messageService: MessageService, ngZone: NgZone, cdr: ChangeDetectorRef, session: VisualizerStore, samTool: SamToolService, cellSegmentTool: CellSegmentToolService, samPointTool: SamPointToolService, regionOps: RegionOpsService, vizConfig?: VizConfig | undefined, toolContributions?: readonly ToolbarToolContribution[], spatialData?: SpatialDataPort | undefined);
     /**
      * Plot types offered in the selector for the current image:
      *  - Outside **test mode**, only the curated default set (descriptors with a
@@ -263,12 +289,55 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
      *  - scalar-intensity types (contour, surface, isosurface) hidden for RGB
      *    images — they map a single intensity per pixel. Image and Heatmap render
      *    any image.
+     *  - spatial-omics types hidden until a `SpatialDataset` is published on
+     *    `SPATIAL_DATA_PORT` — the mode has nothing to draw without observations,
+     *    exactly as a volume has nothing to draw without a stack.
      */
+    /**
+     * Track whether a spatial-omics dataset is available. A dataset appearing (or
+     * being cleared) changes which plot types make sense, so it drives the same
+     * recompute + reconcile that the image stream and the test-mode toggle do.
+     *
+     * No-op when the host provides no `SPATIAL_DATA_PORT` — the spatial types then
+     * stay hidden for the life of the component.
+     */
+    private watchSpatialDataset;
+    /**
+     * Publish a dataset's reference volume AS the image, and open the 2D Image view
+     * on it.
+     *
+     * The volume is a 3D image delivered in one file, so for a dataset that has no
+     * section image it is the honest thing to put on screen: the slice bar scrubs z,
+     * and the contrast window, colormaps and region tools all work because the
+     * volume genuinely is the image now. The 3D cloud stays one menu pick away.
+     *
+     * Keyed by dataset + geometry: the dataset stream re-emits on things like a
+     * colour-column change, and rebuilding then would re-fetch the voxels and throw
+     * the user back to the middle slice.
+     */
+    private showVolumeAsImage;
+    /** Forget the published volume image so re-selecting the dataset rebuilds it.
+     *  The URLs deliberately stay alive: the host may still be displaying that image
+     *  at this instant, and revoking under it would break every later tile read. They
+     *  are freed when the next volume replaces them, or on destroy. */
+    private dropVolumeImage;
+    private revokeVolumeImageUrls;
     private computePlotTypeOptions;
     ngOnChanges(changes: SimpleChanges): void;
     /** If the active plot type is no longer in the offered options (e.g. test mode
      *  turned off while a test-only type was active, or a scalar type carried onto
      *  an RGB image), fall back to the default 2D Image view. */
+    /** Whether the live spatial dataset brings pixels of its own — a tissue image it
+     *  registers onto, or a volume that is published as a z-stack image. */
+    private spatialDatasetHasPixels;
+    /**
+     * The host published NO image — a spatial dataset that brings none does this.
+     *
+     * Without handling the empty emission, `imageInfo` keeps the LAST image's metadata: the
+     * selector goes on offering pixel modes for pixels that are gone, and every
+     * `isStack`/`isGrayscale` decision is made against a file that is no longer loaded.
+     */
+    private onImageCleared;
     private reconcileSelectedPlotType;
     ngOnInit(): void;
     ngAfterViewInit(): void;
@@ -302,6 +371,8 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     selectColormap(colormapNode: TreeNode): void;
     /** Open the Channels & Histogram dialog (toolbar button). */
     openChannelHistogram(): void;
+    /** Toolbar → open the spatial-omics controls. */
+    openSpatialControls(): void;
     /** Open the Region Editor dialog (toolbar button). The editor stays linked to
      *  this plotting instance through the root RegionStore singleton, so it works
      *  the same as the former right-panel Regions tab. */
@@ -476,6 +547,6 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     onSelectPlotType(type: PlotType): void;
     /** Deactivate whatever tool is armed and clear every tool mode. */
     private deactivateActiveTool;
-    static ɵfac: i0.ɵɵFactoryDeclaration<VisualizerComponent, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, { optional: true; }]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<VisualizerComponent, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, { optional: true; }, { optional: true; }]>;
     static ɵcmp: i0.ɵɵComponentDeclaration<VisualizerComponent, "visualizer", never, { "toolbarTools": { "alias": "toolbarTools"; "required": false; }; "testMode": { "alias": "testMode"; "required": false; }; }, { "isStackEvent": "isStackEvent"; "isGrayscaleEvent": "isGrayscaleEvent"; }, never, ["*"], false, never>;
 }

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@jax-data-science/sci-image-visualizer",
-  "version": "0.3.3",
+  "version": "0.4.0",
+  "engines": {
+    "node": ">=20.9.0"
+  },
   "description": "Browser-based scientific image visualization for Angular — gigapixel whole-slide (OpenSeadragon), 2D/3D (Plotly) and WebGPU (napari-js) rendering, with region/annotation editing and in-browser SAM segmentation.",
   "keywords": [
     "angular",
@@ -34,9 +37,10 @@
     "access": "public"
   },
   "dependencies": {
+    "@jax-js/jax": "^0.1.24",
     "cellpose-js": "^0.6.0",
     "fast-png": "^6.4.0",
-    "napari-js": "^0.11.1",
+    "napari-js": "^0.14.0",
     "openseadragon": "^6.0.2",
     "plotly.js-dist-min": "^3.0.1",
     "tslib": "^2.3.0"