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

package/lib/implementations/plotly/plotly.service.d.ts

@@ -1,64 +1,57 @@
 import { Image } from 'image-js';
 import { HttpClient } from '@angular/common/http';
-import { Polygon, Rectangle, Region } from '../../models/region';
-import { IImageInfo, IImageMetadata } from '../../contracts/image.contract';
+import { Region } from '../../models/region';
+import { IImageInfo } from '../../contracts/image.contract';
 import { TileAccessPort } from '../../contracts/ports/tile-access.port';
 import { ImageStatePort } from '../../contracts/ports/image-state.port';
 import { Observable } from 'rxjs';
 import { MessageService } from 'primeng/api';
-import { ShapeSelection } from '../../models/shape';
-import { WandService, WandOptions } from '../../toolbar/wand/wand.service';
-import { WandToolService } from '../../toolbar/wand/wand-tool.service';
-import { BrushToolService, BrushOptions } from '../../toolbar/brush/brush-tool.service';
+import { WandService } from '../../toolbar/wand/wand.service';
+import { CanvasToolManager } from '../../toolbar/tool-kit/canvas-tool-manager';
 import { SamToolService } from '../../toolbar/segmentation/sam-tool.service';
 import { SamPointToolService } from '../../toolbar/segmentation/sam-point-tool.service';
 import { CellSegmentToolService } from '../../toolbar/segmentation/cell-segment-tool.service';
 import { ICellSegmenter } from '../../contracts/cell-segmenter.contract';
-import { VertexEraserToolService } from '../../toolbar/vertex-eraser/vertex-eraser-tool.service';
-import { ZoomToBoxToolService } from '../../toolbar/zoom-to-box/zoom-to-box-tool.service';
 import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
-import { IVisualizer, IntensityProfile, IIsosurfaceControls, IIntensityControls } from '../../contracts/visualizer.contract';
+import { IViewerBackend, IntensityProfile, IIsosurfaceControls, IIntensityControls, PixelData } from '../../contracts/visualizer.contract';
 import { IHistogram } from '../../contracts/channel-histogram-api.contract';
 import { ViewerCapabilities } from '../../contracts/capabilities.contract';
 import { IRegionOverlay } from '../../contracts/region-overlay.contract';
+import { PlotlyLoaded } from './plotly-image-loader';
+import { IntensityProfileService } from '../../intensity/intensity-profile.service';
 import { ICoordinateTransform } from '../../contracts/coordinate-transform.contract';
 import { VisualizerStore } from '../../store/visualizer-store.service';
 import { RegionStore } from '../../store/region-store.service';
+import { BaseStoreVisualizer } from '../base-store-visualizer';
+import { ColormapNode } from '../../contracts/display-types';
 import * as i0 from "@angular/core";
 export { PlotType } from '../../contracts/plot-type';
-export declare class PlotlyService implements IVisualizer {
+export declare class PlotlyService extends BaseStoreVisualizer implements IViewerBackend {
     private tiles;
     private state;
     messageService: MessageService;
-    private http;
-    private wandService;
-    private wandTool;
-    private brushTool;
     private samTool;
     private samPointTool;
     private cellSegmentTool;
     private cellSegmenter;
-    private vertexEraserTool;
-    private zoomToBoxTool;
-    private store;
-    private regionStore;
+    private intensity;
     /**
      * Plotly is the full-featured data backend: it supports every feature,
      * including 3D scenes, live scalar colormaps, pixel readback and the
-     * server-side high-def zoom re-fetch. (OpenSeadragon's stub advertises only
-     * image display.)
+     * server-side high-def zoom re-fetch. (OpenSeadragon, the tiled image
+     * backend, advertises only image display.)
      */
     readonly capabilities: ViewerCapabilities;
-    private shapes;
-    private previousShapes;
-    private isRegionSavedOn;
+    /** Plotly's render projection of the shared RegionStore (the shape dicts) and
+     *  the selection ↔ active-shape mapping (see PlotlyShapeProjection). */
+    private readonly shapeProjection;
+    /** Step/box zoom, autoscale and the high-def zoom re-fetch (see PlotlyZoomController). */
+    private readonly zoom;
     private imageLength;
     private screenHeight;
     private plotDiv;
-    private isRealZoom;
     private scaleratio;
     private trueImgSize;
-    private zoomCoordinates;
     private fileName;
     private dragMode;
     private urls;
@@ -72,7 +65,6 @@ export declare class PlotlyService implements IVisualizer {
      * "can't access property isGrayscale" and aborted the load.
      */
     imageInfo: IImageInfo;
-    private plotUtilities;
     private plotType;
     private onPlotMouseDown;
     /** Pixel data cached for wand sampling. data[zIndex] is a 2-D matrix. */
@@ -81,141 +73,93 @@ export declare class PlotlyService implements IVisualizer {
     private cachedImageHeight;
     private cachedImageRatios;
     private cachedIsGrayscale;
+    /** A serverless multichannel stack's raw channel planes, per loaded slice: the channels'
+     *  histograms, and what its `image` trace is composited from. */
+    private cachedChannelPlanes?;
+    /** The channel display of a colour image's `image` traces (see PlotlyImageRecolor). */
+    private readonly recolor;
+    /** The pending per-frame recolour (requestAnimationFrame handle), if any. */
+    private recolorFrame;
+    /** A recoloured slice is being encoded; `recolorAgain`: an edit came in meanwhile. */
+    private recoloring;
+    private recolorAgain;
+    /** Recolours the slice a stack's slider brings on screen. */
+    private onSliderChange;
     /** Data-space coordinate of the cached frame's pixel (0,0). [0,0] for the full
-     *  image; a crop's top-left when zoomed (so the intensity profile samples the
+     *  image; a crop's top-left after a high-def zoom (so the tools sample the
      *  zoom-level pixels at the right offset/resolution). */
     private cachedFrameOrigin;
-    /** Last visible image-pixel rectangle from the active backend's viewport (set by
-     *  the OSD viewport-change hook via refreshIntensitySamplingForRoi). New profile lines are
-     *  placed within it so they land on-screen when zoomed in; null → use full image. */
-    private lastVisibleRoi;
     /** events */
     private onRelayoutEvent;
-    private stackLoading$;
-    private stackLoadingProgress$;
+    /** Bumped by every render of the plot div (plot, a high-def zoom re-render,
+     *  purge, reset). A high-def zoom drops its crop if another render (or the
+     *  hand-over of the div to another backend) happened while it was fetching. */
+    private renderGen;
+    /** Slice fetch + decode, the stack pool and its loading flag/progress. */
+    private readonly loader;
     private zIndex;
     private autoscaleEvent;
-    /** Bright, well-separated colours cycled as the user adds profile-line ROIs.
-     *  The matching inset trace is drawn in the same colour. */
-    private readonly PROFILE_PALETTE;
-    /** Palette cursor for profile lines (never reset on delete, so colours keep
-     *  cycling across the session). */
-    private profileColorSeq;
-    private intensityProfile$;
-    /** ISOSURFACE band as a 0–255 slider position, mapped onto the volume's real
-     *  intensity range at render time (see mapIsoBand). Defaults to the full range
-     *  so the first render shows the whole structure regardless of how bright or
-     *  dark the volume is; the user then narrows the band to isolate intensities. */
-    private isoMin;
-    private isoMax;
-    /** Actual intensity range of the volume on screen ([min,max] over the loaded
-     *  frames). The slider spans 0–255, but a given stack often occupies only a
-     *  sub-range, so we clamp the iso band into this range (with a small margin)
-     *  to guarantee non-degenerate surfaces — both on first render and on live
-     *  slider moves. Null until an isosurface volume has been measured. */
-    private isoDataRange;
+    /** The ISOSURFACE band, mapped onto the measured volume (see PlotlyIsosurfaceControls). */
+    private readonly iso;
     private imageCached;
-    private imageCachedSubscription;
-    private filenameSubscription;
-    /** Drives the intensity inset off region adds/drags/deletes (both backends). */
-    private regionUpdateSubscription?;
-    /** Live (per-frame, non-coalesced) region edits — so the inset tracks an OSD
-     *  line ROI live during a drag (OSD batches regionUpdate$ until release). */
-    private regionLiveEditSubscription?;
+    private imageCachedSubscription?;
+    private filenameSubscription?;
     private channelSub?;
-    private wandHost;
-    private eraserHost;
+    /** What this backend's canvas tools read and write (one host for every tool). */
+    private readonly toolHost;
+    /** This backend's own wand, brush, eraser, zoom-to-box and SAM point tools. */
+    protected readonly canvasTools: CanvasToolManager;
     /** This backend's region renderer (lazily created in getRegionOverlay). */
     private regionOverlay?;
     private readonly coordinateTransform;
-    constructor(tiles: TileAccessPort, state: ImageStatePort, messageService: MessageService, http: HttpClient, wandService: WandService, wandTool: WandToolService, brushTool: BrushToolService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, vertexEraserTool: VertexEraserToolService, zoomToBoxTool: ZoomToBoxToolService, store: VisualizerStore, regionStore: RegionStore);
+    constructor(tiles: TileAccessPort, state: ImageStatePort, messageService: MessageService, http: HttpClient, wandService: WandService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, store: VisualizerStore, regionStore: RegionStore, intensity: IntensityProfileService);
+    /**
+     * Subscribe to the shared stores (cached flag, filename, live channel recolor,
+     * profile-inset refresh). Idempotent and self-healing, like OSD's
+     * ensureColormapSubscription: this service is a root singleton, but
+     * `unsubscribe()` (called on VisualizerComponent destroy) tears these down and
+     * the constructor never runs again. So `load()`/`plot()` call this to
+     * re-establish them after a component teardown/recreate.
+     */
+    private ensureSubscriptions;
     getTrueImageSize(): {
         width: number;
         height: number;
     } | null;
     /**
-     * Load image
-     * @param imageInfo
-     * @param zIndex index of the image to load
-     * @return an object with data and ratio keys
-     */
-    load(imageInfo: IImageInfo, zIndex: number): Promise<{
-        data: any[];
-        ratios: number[];
-        sizes: number[];
-        filename: string;
-    }>;
-    /**
-     *
-     * @param plotDiv
-     * @param imageLoaded object with data, ratios and sizes key
-     * @param imageInfo ImageInfo object
-     * @param screenHeight size of the available screen height
-     * @param plotType type of plotting
+     * Load slice `zIndex`, or the whole shown stack (see PlotlyImageLoader).
+     * `signal` aborts the requests: the load then rejects with an `AbortError`.
      */
+    load(imageInfo: IImageInfo, zIndex: number, signal?: AbortSignal): Promise<PlotlyLoaded>;
     /**
-     * @param inPlace when true, updates the existing plot via Plotly.react
-     *   instead of Plotly.purge + Plotly.newPlot. Used by the multi-tier
-     *   diagram swap (small → large) so the canvas doesn't briefly blank
-     *   between phases.
+     * Plot a loaded image (see {@link load}) as `plotType`. `inPlace` updates the
+     * existing plot via Plotly.react instead of purge + newPlot — the multi-tier
+     * swap (small → large) — so the canvas doesn't briefly blank between phases.
      */
     plot(plotDiv: string, imageLoaded: any, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
-    /**
-     * Function used to plot a grayscale heatmap
-     * @param plotDiv
-     * @param urls
-     * @param images
-     * @param trueImgSize array containing the following : [x0, x1, y0, y1]
-     * @param ratios
-     * @param screenHeight
-     * @return Promise true when plotting is finished
-     */
+    /** Grayscale heatmap, one trace per z-plane. */
     private plotHeatmap;
-    /**
-     * Function used to plot a grayscale surface
-     * @param plotDiv
-     * @param urls
-     * @param images
-     * @param trueImgSize array containing the following : [x0, x1, y0, y1]
-     * @param ratios
-     * @param screenHeight
-     * @return Promise true when plotting is finished
-     */
+    /** Grayscale surface. */
     private plotSurface;
+    /** RGB image (`width` × `height` pixels), one trace per z-plane, in the current channel
+     *  display: `target.frames` are the raw frames, `planes` a serverless multichannel stack's raw
+     *  channel planes per frame. An image that follows the channel states draws a `source` per
+     *  slice (see PlotlyImageRecolor). */
+    private plotRGBHeatmap;
     /**
-     * Function used to plot an RGB heatmap
-     * @param plotDiv
-     * @param urls
-     * @param images
-     * @param trueImgSize
-     * @param width
-     * @param height
-     * @param ratios
-     * @param screenHeight
-     * @return Promise
+     * Render `traces` into the plot div and wire the relayout/click events. In
+     * place (`Plotly.react`) for the multi-tier small → large swap — `Plotly.purge`
+     * + `Plotly.newPlot` blanks the canvas for ~100ms, which looks like a
+     * regression to "loading" before the sharper version appears. The layout is
+     * built after the per-plot state (screen height, slice count) is set.
      */
-    private plotRGBHeatmap;
+    private renderPlot;
     /**
      * Assemble the normalised input the pluggable trace builders consume.
      * Pure data only — no Plotly handles — so the builders stay backend-neutral.
      */
     private buildTraceInput;
-    /** Min/max intensity over every voxel of the loaded frames (RGB → luminance),
-     *  used to keep the iso band inside the data. Returns null for empty input. */
-    private measureIntensityRange;
-    /** Map the 0–255 slider band onto the volume's actual intensity range. The
-     *  slider is fixed 0–255, but a stack often occupies only a narrow sub-range
-     *  (e.g. this EDOF volume is ~2–50 with structure near 6–10). Mapping spreads
-     *  the data across the whole slider so every intensity is easy to reach and
-     *  the band always lands inside the data — a small inset keeps the extreme
-     *  surfaces off the exact data edges, which are degenerate and draw nothing. */
-    private mapIsoBand;
-    /**
-     * Update the isosurface intensity bounds. When isosurface is on screen this
-     * restyles `isomin`/`isomax` in place for a live update (no volume rebuild).
-     * Slider values are mapped onto the volume's real range so the surfaces always
-     * have data to cross (matching the initial render).
-     */
+    /** Update the isosurface intensity band (see PlotlyIsosurfaceControls). */
     setIsoRange(isoMin: number, isoMax: number): void;
     /** Plotly renders isosurfaces, so it exposes the isosurface controls (itself). */
     getIsosurfaceControls(): IIsosurfaceControls | null;
@@ -225,160 +169,60 @@ export declare class PlotlyService implements IVisualizer {
      * Mirrors the structure of the dedicated heatmap/surface renderers.
      */
     private plotViaRegistry;
-    /** Plain 2D chart axes (intensity profile / line plots). */
-    private getChartLayout;
-    /** Image-aligned 2D axes without the z-plane slider (region scatter). */
-    private getOverlayLayout;
-    /** 3D scene for volumetric plot types (scatter3d, isosurface). */
-    private getVolumeLayout;
     /** Plot types this backend advertises (drives the UI selector). */
     getPlotTypeDescriptors(): PlotTypeDescriptor[];
     /** This backend's region renderer. Plotly draws shapes natively, so the
      *  overlay is a thin adapter over this service's drag modes. */
     getRegionOverlay(): IRegionOverlay;
-    /** Emits the full set of intensity profiles (one per profile-line region)
-     *  whenever a profile line is added, moved, or removed. */
-    getIntensityProfile$(): Observable<IntensityProfile[]>;
     /** Plotly renders the line ROIs + inset, so it exposes the intensity controls. */
     getIntensityControls(): IIntensityControls | null;
-    /**
-     * Render the floating intensity-profile inset chart into `divId` — one line
-     * trace per ROI, each drawn in its ROI's colour. Kept here (not in the diagram
-     * component) so the consumer never touches Plotly directly.
-     */
+    /** Render the floating intensity-profile inset (see plotly-intensity-inset.ts),
+     *  so the consumer never touches Plotly directly. */
     renderIntensityInset(divId: string, profiles: IntensityProfile[]): void;
-    /**
-     * Region shapes (filtered/redrawn for the current file). The profile-line ROIs
-     * are ordinary store regions (tagged `kind: 'profile'`), so they are already
-     * part of `this.shapes` — no separate append is needed.
-     */
+    /** Region shapes for the image on screen (profile lines included: they are
+     *  ordinary store regions). */
     private currentRenderShapes;
     /**
-     * IIntensityControls: add another intensity-profile line as a neutral Region
-     * (tagged `kind: 'profile'`). It is a horizontal open 2-point polyline spanning
-     * the image width, staggered vertically so successive lines stay distinct, in
-     * the next bright palette colour. Added to the shared store so both backends
-     * (Plotly + OpenSeadragon) render and drag it; excluded from the Regions tab
-     * and exports by its kind.
+     * IIntensityControls: add another profile line (see IntensityProfileService).
+     * It is a store region, so a Plotly plot on screen draws it from the store's
+     * region-update event, like the OSD/napari overlays.
      */
     addProfileLine(): Region | null;
-    /** The profile-line ROIs currently in the store (kind === 'profile'). */
-    private getProfileRegions;
-    /** Recompute and broadcast a profile for every profile-line region (id + colour
-     *  tagged so the inset trace matches its line). */
-    private emitProfiles;
-    /**
-     * Sample the intensity profile for a profile-line region: extract its two
-     * polygon endpoints and reuse the shared `computeIntensityProfile` sampling.
-     */
-    private computeIntensityProfileForRegion;
     /**
-     * Supply pixel frames for intensity sampling (used by the OSD/image backend,
-     * whose cached frames may be empty). Optionally also sets the data/pixel ratios.
+     * Point the pixel tools at these frames (e.g. a high-def zoom crop whose pixel
+     * (0,0) sits at image `origin`), and sample the intensity profiles from them.
      */
     setSamplingFrames(frames: any[], ratios: number[], origin?: [number, number]): void;
-    /**
-     * Populate the sampling cache for the intensity profiles when OpenSeadragon is
-     * the active backend (the Image plot type). In OSD mode Plotly never rendered,
-     * so `cachedImageFrames`/`trueImgSize` are unset — fetch the current slice's
-     * preview (the same pixels the heatmap would sample) so the line ROIs have
-     * pixel data and a placement extent. Re-emits the profiles once loaded.
-     */
-    ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
-    /**
-     * {@link IIntensitySampling} stub — the viewport-change signal is OpenSeadragon's
-     * (it re-samples on OSD zoom/pan). Plotly's own high-def zoom updates the
-     * sampling cache inline, so it never emits here; returns EMPTY so a uniform
-     * `IVisualizer` consumer can subscribe regardless of the active backend.
-     */
-    getViewportChange$(): Observable<{
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }>;
-    /**
-     * Re-fetch the given image-pixel ROI at the display resolution and use it as
-     * the intensity-sampling source, so the profile reflects the data at the
-     * current zoom level. Shared by both backends: the OSD viewport-change hook
-     * calls it on zoom/pan; Plotly's own high-def zoom (triggerZoom) updates the
-     * same cache inline. `roi` is in full-image pixel coordinates.
-     */
-    refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
-    /**
-     * Sample the active frame's intensity (grayscale value or RGB luminance)
-     * along the line ROI. Returns distance-along-line positions and values.
-     */
-    private computeIntensityProfile;
-    /** Physical pixel size (microns/pixel) for the current image, if known.
-     *  mpp is constant across frames/channels, so the first metadata entry that
-     *  carries a positive mppX wins. Returns nulls when the image is unscaled. */
-    private currentMpp;
-    /**
-     * autoscale the plot
-     */
+    /** No viewport signal: Plotly's own high-def zoom re-samples the profiles inline. */
+    getIntensitySampling(): null;
+    /** No navigator and no smoothing toggle (OpenSeadragon/napari-js view options). */
+    getOsdViewOptions(): null;
+    /** Plotly renders no decimated volumes (napari-js's Resolution control). */
+    getVolumeResolution(): null;
+    /** Autoscale the plot (see PlotlyZoomController). */
     autoscale(): void;
-    /**
-     * relayout the plot
-     */
+    /** Re-apply the image layout at the current height, over the zoom box if any. */
     relayout(trueImageSize?: number[]): void;
     private setEvents;
     private relayoutEventHandler;
     reloadAndPlot(): void;
-    setWandMode(active: boolean, options?: WandOptions): void;
-    setWandOptions(options: WandOptions): void;
-    clearActiveWandRegion(): void;
-    setBrushMode(active: boolean, options?: BrushOptions): void;
-    setBrushOptions(options: BrushOptions): void;
-    setVertexEraserMode(active: boolean): void;
-    setVertexEraserRadius(radius: number): void;
-    setZoomToBoxMode(active: boolean): void;
-    /** Bind the shared zoom-to-box tool to this (Plotly) backend's host. */
-    private bindZoomToBoxHost;
-    /** Box-prompted SAM: segment the drawn rectangles. The SAM tool reuses the
-     *  wand host (cached frame + coordinate transform + region store). */
+    /** Box-prompted SAM: segment the drawn rectangles against our tool host
+     *  (cached frame + coordinate transform + region store). */
     segmentRectangles(): Promise<number>;
     segmentRectanglesCellpose(): Promise<number>;
     setSamModel(id: string): void;
-    setSamPointMode(active: boolean): void;
-    commitSamPoints(): void;
-    clearSamPoints(): void;
-    /**
-     * Tool-host callback: apply the zoom-to-box selection. Stack mode does a
-     * pure axis-range relayout; non-stack mode goes through the high-def
-     * triggerZoom pipeline so the image is re-fetched at the new resolution.
-     */
-    /** Overlay-pixel -> Plotly data coords via the axis objects (subtracting the
-     *  plot margin offset). The zoom-to-box tool calls this through its host. */
-    private zoomBoxPixelToData;
-    private applyZoomToBox;
     /** The plot element the tool canvas overlays attach to. */
     getOverlayContainer(): HTMLElement | null;
     /** Plotly coordinate transform (screen <-> data via the axis objects). */
     getCoordinateTransform(): ICoordinateTransform;
-    /** Pixel data the wand needs for sampling. null = no image loaded. */
-    private getCachedImageData;
-    /** Build Plotly shape dicts from the store's regions (the render projection). */
-    private regionsToShapeDicts;
-    /** Rebuild the dict working-set from the store (after an image switch, or when
-     *  regions changed while another backend was rendering). */
-    private syncShapesFromStore;
     /**
-     * Make the shared store authoritative for the current dict working-set: convert
-     * `this.shapes` to neutral regions and replace the store's list (the store
-     * mints ids, applies class colours, syncs its per-image cache and emits the
-     * region-update event). Store-minted ids are written back onto the dicts so the
-     * two representations stay aligned. Profile-line ROIs are ordinary regions
-     * (tagged `kind: 'profile'`) and round-trip through here too.
-     */
-    private commitShapesToStore;
-    /**
-     * Push the current `this.shapes` to Plotly, mirror them into the shared store
-     * (which syncs its cache + emits the region-update event), and refresh the
-     * local previous-shapes buffer. The wand/eraser tools call this after mutating
-     * the shapes array directly.
+     * Pixel data the wand needs for sampling. null = no image loaded.
+     *
+     * The traces draw cell (i, j) over `origin + [i, i + 1)·ratio` (see `firstCellCentre`), as OSD
+     * and napari draw their pixels, so the frame starts at the cached origin: a click anywhere on a
+     * cell floors to that cell, and traced outlines run along the cells' edges.
      */
-    applyShapesChange(): void;
+    private getCachedImageData;
     /** Active frame index in the cached image stack. */
     private activeFrameIndex;
     /** Capability-gated 3D scene controls (Plotly renders the 3D plot types). */
@@ -388,91 +232,31 @@ export declare class PlotlyService implements IVisualizer {
     };
     setSurfaceDragMode(mode: string): void;
     resetSurfaceCamera(): void;
-    private triggerZoom;
+    /** Re-render a high-def zoom crop in the plot type on screen. Without this the
+     *  re-fetch always fell back to a heatmap, so zooming in contour (or any
+     *  registry type) reverted to heatmap. */
+    private renderZoomCrop;
     setPlotType(plotType: PlotType): void;
     private setImageInfo;
-    getShapes(): any[];
-    /**
-     * Framework-neutral view of the current regions — delegates to the shared
-     * RegionStore (the single source of truth). The canonical accessor on the
-     * `IVisualizer` contract; consumers should prefer this over `getShapes()`
-     * (which exposes Plotly-shaped dicts).
-     */
-    getRegions(): Region[];
     /**
      * Switch the active image. The shared RegionStore owns the per-image region
      * cache (snapshot outgoing / restore incoming / clear selection / emit); we
      * delegate to it, then re-project the store's regions into Plotly's dict
      * working-set. Re-projecting unconditionally (even when the store no-ops for
      * the same image) means Plotly also picks up regions another backend (OSD)
-     * added while it was off-screen. Called from `plot()` and from the router
-     * before any backend renders.
+     * added while it was off-screen. The switch is not redrawn onto the plot on
+     * screen — that still shows the outgoing image, and the next plot draws the
+     * incoming one's shapes. Called from `plot()` and from the router before any
+     * backend renders.
      */
     setActiveImage(imageInfo: IImageInfo): void;
-    /** Test/dev hook — drop the entire per-image cache (logout / project switch). */
-    clearRegionsByImageKey(): void;
-    /**
-     * Get all the selected regions as polygons. Open polylines (closed === false)
-     * are excluded — they're annotation-only and cannot be used as filled regions
-     * for image processing. Delegates to the shared store.
-     */
-    getRegionPolygons(): any[];
-    isRectangle(bnds: any): bnds is Rectangle;
-    isPolygon(bnds: any): bnds is Polygon;
-    /**
-     * Set plot regions. Delegates the state change to the shared RegionStore
-     * (id/name minting, classification colours, append de-duplication, per-image
-     * cache and the region-update event all live there), then re-projects the
-     * store's regions into Plotly's dict working-set and renders.
-     *
-     * When `isRegionSaveOn` is false the regions are shown transiently — rendered
-     * without altering the stored working-set (preserves the prior behaviour).
-     */
-    setRegions(regions: Region[], showRegionLabel?: boolean, isRegionSaveOn?: boolean, fillColor?: string, append?: boolean): void;
-    /** The shapes-relayout payload: region shapes (profile-line ROIs included, as
-     *  they are ordinary regions) plus the active-shape fill colour. */
-    private shapesRelayout;
-    /** Push the current dict working-set to Plotly (no-op when another backend
-     *  owns the div). */
-    private renderShapes;
-    getShowShapeLabel(): boolean;
-    /**
-     * Set previous saved shapes
-     */
-    plotPreviousShapes(): void;
-    setPreviousShapes(shapes: ShapeSelection[]): void;
-    getPreviousShapes(): ShapeSelection[];
-    undo(): void;
-    redo(): void;
-    canUndo(): boolean;
-    canRedo(): boolean;
-    getCanUndo$(): Observable<boolean>;
-    getCanRedo$(): Observable<boolean>;
-    resetUndoHistory(): void;
-    enterStackMode(slices: Map<number, Region[]>, initialZ?: number, saveLayout?: 'combined' | 'per-slice-file'): void;
-    exitStackMode(): void;
-    isStackMode(): boolean;
-    getStackSaveLayout(): 'combined' | 'per-slice-file';
-    setDisplaySlice(z: number): void;
-    getSliceRegions(): Region[];
-    getStackSaveSlices(): Map<number, Region[]>;
+    /** The plot div while it hosts a live Plotly graph, else null. `plotDiv`
+     *  stays set after purgePlot() hands the div to another backend (OSD,
+     *  napari-js), and Plotly.relayout/restyle throw on a non-Plotly div. */
+    private liveGd;
+    /** The live state an image-aligned layout is built from. */
+    private layoutContext;
     private getHeatmapLayout;
-    private shapesToRedraw;
-    /**
-     * Unused (will be used when surface plot is added)
-     * @param xRange
-     * @param yRange
-     * @param zRatio
-     * @private
-     */
-    private getSurfaceLayout;
-    private getSteps;
-    /**
-     * Fetch an image via Angular HttpClient so that auth interceptors (Bearer token)
-     * are applied, then decode it with image-js. This avoids raw browser fetch()
-     * calls that bypass the interceptor chain and fail behind an OAuth2 proxy.
-     */
-    private loadImage;
     /**
      * Get the currently displayed image as an image-js Image instance.
      * Used by the processing pipeline to obtain the input image.
@@ -483,21 +267,10 @@ export declare class PlotlyService implements IVisualizer {
      * This captures whatever is actually rendered — including zoomed regions.
      * Returns { width, height, channels, data } or null if no plot is displayed.
      */
-    getDisplayedPixelData(): {
-        width: number;
-        height: number;
-        channels: number;
-        data: Uint8ClampedArray;
-    } | null;
-    /**
-     * Region of the original image that the displayed `z` grid covers, in
-     * full-image pixel coords. On a server zoom (`triggerZoom`) the trace `z` is
-     * replaced with the high-def crop and the axes are relaid out to the crop's
-     * original-image bounds (`imageSize`), so the live axis ranges ARE that
-     * rectangle; when the whole image is in view the ranges span `trueImgSize`.
-     * Reading the ranges therefore yields the crop origin + extent without
-     * tracking zoom state separately. Falls back to the full image, then `null`.
-     */
+    getDisplayedPixelData(): PixelData | null;
+    /** The image rect the displayed `z` grid covers, in full-image pixel coords —
+     *  read off the live axis ranges (a high-def zoom relays them out to the crop),
+     *  else the whole image (see axesSourceRect). */
     getDisplayedSourceRect(): {
         x: number;
         y: number;
@@ -517,74 +290,37 @@ export declare class PlotlyService implements IVisualizer {
     downloadImage(): void;
     resetAxes(): void;
     setDragMode(mode: string | false): void;
-    /** {@link IDataRenderer} stub — Plotly has no overview navigator (it's an
-     *  OpenSeadragon feature), so toggling it is a no-op here. */
-    setNavigatorVisible(_visible: boolean): void;
-    /** {@link IDataRenderer} stub — image smoothing is an OpenSeadragon canvas-drawer
-     *  setting; the Plotly image/heatmap traces don't expose it, so it's a no-op. */
-    setImageSmoothingEnabled(_enabled: boolean): void;
     zoomIn(): void;
-    /**
-     * Delete every currently selected shape. Falls back to the single
-     * `_activeShapeIndex` when no multi-selection is active (covers the case
-     * where Plotly clicked a shape without going through the table).
-     */
-    deleteActiveShape(): void;
     zoomOut(): void;
     isStackLoading$(): Observable<boolean>;
     setStackLoading(stackLoading: boolean): void;
     getStackLoadingProgress$(): Observable<number>;
-    getColormapOptions(): any;
-    setColormap(colormap: any): void;
-    getColormap(): Observable<any>;
-    setReverseScale(reverscale: any): void;
-    getReverseScale(): Observable<boolean>;
-    setImageMeta(imageMeta: IImageMetadata[]): void;
-    getImageMeta(): Observable<IImageMetadata[]>;
+    setColormap(colormap: ColormapNode): void;
+    setReverseScale(reverscale: boolean): void;
     setShowStack(showstack: boolean): void;
     getAutoscaleEvent(): Observable<any>;
-    getRegionUpdateEvent(): Observable<any[]>;
-    /**
-     * Stream of the indices of currently selected regions — owned by the shared
-     * RegionStore so the selection is consistent across backends and the Region
-     * Editor table. Empty = nothing selected.
-     */
-    getSelectedShapeIndices$(): Observable<number[]>;
-    /**
-     * Programmatically select regions (or clear with []). The shared store owns
-     * the selection state (validates/dedupes/emits); here we additionally point
-     * Plotly's `_activeShapeIndex` at the last selected shape so it gets the edit
-     * handles. No visual change to non-active shapes — Plotly's own active-shape
-     * rendering is the only highlight.
-     */
-    setSelectedShapeIndices(indices: number[]): void;
-    /**
-     * Select a specific region (IRegionStore.selectRegion). Sets the shared store
-     * selection by identity and points Plotly's active-shape at the matching
-     * rendered shape so its edit handles appear.
-     */
-    selectRegion(region: Region): void;
-    /**
-     * Read Plotly's `_activeShapeIndex` and push it as the selection. Called from
-     * the relayout handler and the post-click tick — Plotly doesn't fire a
-     * dedicated active-shape event for clicks, so we sample. The store no-ops if
-     * the selection is unchanged.
-     */
-    private maybeEmitActiveShapeIndex;
     setZIndex(zIndex: number): void;
-    getShapeColor(): string;
-    getFillColor(): string;
-    getClassificationColors(): Map<string, string>;
-    setClassificationColor(label: string, color: string): void;
     /**
      * Unsubscribe Subscriptions
      */
     unsubscribe(): void;
     /** Live-apply the channel display window (zmin/zmax) + reverse/invert to the
-     *  heatmap. No-op when no Plotly plot is mounted (OSD owns the div). */
+     *  heatmap — or, for a colour image's `image` trace, recomposite it per channel
+     *  (PlotlyImageRecolor). No-op when no Plotly plot is mounted (OSD owns the div). */
     private applyChannelDisplay;
+    /**
+     * Recolour the slice on screen on the next frame: a slider drag in the dialog
+     * emits per step, and coalescing them keeps one recomposite per frame — and
+     * none while the previous one is still encoding (see recolorShownFrame).
+     */
+    private scheduleRecolor;
+    /** Restyle trace `index`'s `source` into the current channel display, unless it shows it
+     *  already. One picture at a time: an edit made while one encodes is drawn after it, in the
+     *  state current by then. */
+    private recolorShownFrame;
     /** Binned intensity histogram for a channel from the cached source frames
-     *  (raw, pre-LUT). Grayscale cells are numbers; RGB cells are [r,g,b]. */
+     *  (raw, pre-LUT). Grayscale cells are numbers; RGB cells are [r,g,b]; a
+     *  serverless multichannel stack bins the channel's own raw plane. */
     getHistogram(channelIndex: number, _bins: number): IHistogram | null;
     /** Async histogram stream — Plotly renders heatmap frame data (already in
      *  memory, 8-bit luminance), so this just wraps the synchronous 8-bit
@@ -593,11 +329,10 @@ export declare class PlotlyService implements IVisualizer {
     /** Data export (16-bit TIFF) is an OSD-tile-path feature backed by the server.
      *  Plotly renders heatmaps from frame data, so there's nothing to export here. */
     exportData(): void;
-    importRegions(geoJsonStr: string): Region[];
+    /** As the base class, but the file is named after the image on screen. */
     exportRegions(regions: Region[]): void;
-    getGeoJsonString(regions: Region[]): string;
     getStackLoadingProgress(): Observable<number>;
     isStackLoading(): Observable<boolean>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<PlotlyService, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, null, null, null, null]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PlotlyService, [null, null, null, null, null, null, null, null, { optional: true; }, null, null, null]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<PlotlyService>;
 }