@jax-data-science/sci-image-visualizer 0.1.0

package/lib/implementations/osd/histogram-sampler.d.ts

@@ -0,0 +1,85 @@
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+/**
+ * Histogram + auto-window sampling for the OSD backend (refactoring plan,
+ * Step 4 — a pure move out of the visualizer service). Owns the per-slice
+ * 8-bit histograms (sampled from displayed tiles) and the native-bit-depth
+ * histograms (fetched from the server `/histogram` endpoint). Read-only with
+ * respect to the tile/display pipeline.
+ */
+/** The descriptor fields the samplers read (structurally satisfied by the
+ *  service's TileDescriptor). */
+export interface SampledDescriptor {
+    width: number;
+    height: number;
+    tileSize: number;
+    channels?: number;
+    levels?: Array<{
+        width: number;
+        height: number;
+    }>;
+}
+export interface HistogramSamplerHost {
+    /** Real Bio-Formats levels (per-channel tiles exist only there). */
+    realLevels(): number;
+    /** Channel count for the multichannel sampler. */
+    channelCount(d: SampledDescriptor): number;
+    /** Grayscale (intensity histogram + auto-window) vs RGB (R/G/B histograms). */
+    isGrayscale(): boolean;
+    /** Histograms landed — nudge the pane to re-read (its retry window may have
+     *  lapsed). */
+    onChannelHistogramsSampled(): void;
+    /** A grayscale auto-window was measured from full-res tiles — seed the
+     *  Intensity channel (or re-invalidate if the user already windowed). */
+    onGrayWindowSampled(min: number, max: number): void;
+}
+export declare class HistogramSampler {
+    private http;
+    private api;
+    private host;
+    /** 256-bin intensity histogram per z-slice, from sampled tiles. */
+    private sliceHistograms;
+    /** Native-bit-depth histograms from `/histogram`, keyed `${z}|${channel}`. */
+    private nativeHistograms;
+    /** Per-app-load cache-buster for `/histogram` — the server marks the
+     *  response cacheable for 24h, and a hard refresh can't bust a post-load
+     *  XHR. A token stable within a session but new on each full load keeps the
+     *  in-session dedup (via `nativeHistograms`) while always reflecting the
+     *  live backend after a reload. */
+    private readonly histCacheBuster;
+    constructor(http: HttpClient, api: string, host: HistogramSamplerHost);
+    /** The sampled histogram for one channel of slice z, or null until the
+     *  async sampling resolves (or if it was skipped). */
+    get(z: number, channelIndex: number): IHistogram | null;
+    /** Drop everything (teardown / image switch). */
+    clear(): void;
+    /**
+     * Per-channel intensity histograms for multichannel images: sample each
+     * channel's single-band tiles at the coarsest real level and bin the
+     * luminance. Fire-and-forget.
+     */
+    computeMultiChannelHistograms(d: SampledDescriptor, infoB64: string, z: number): Promise<void>;
+    /**
+     * Compute a per-image intensity window [min,max] for grayscale auto-ranging,
+     * mirroring the heatmap's auto-stretch. Two constraints force the sampling
+     * strategy:
+     *  - The window MUST be in the same value space as the displayed tiles: the
+     *    `/preview` endpoint is server-normalized while `/tile` serves raw
+     *    un-normalized 8-bit — a window from the preview wouldn't match.
+     *  - It must read FULL-RESOLUTION tiles, not a downsampled overview:
+     *    averaging sparse low values (label masks) toward 0 wipes the signal.
+     * So we sample the full-res level across the whole image — bounded to 64
+     * tiles (a huge grayscale image samples the coarsest overview for histograms
+     * only). Fire-and-forget; failures leave the window unset (identity 0..255).
+     */
+    computeImageWindow(d: SampledDescriptor, infoB64: string, z: number): Promise<void>;
+    /**
+     * Native-bit-depth histogram for >8-bit images, from the server `/histogram`
+     * endpoint (the 8-bit canvas tiles can't carry 16-bit values). Cached per
+     * slice+channel for the session.
+     */
+    native$(infoB64: string, z: number, channel: number, bins: number): Observable<IHistogram | null>;
+    /** Fetch + cache one channel's native histogram from `GET /histogram`. */
+    private fetchNative;
+}

package/lib/implementations/osd/openseadragon-visualizer.service.d.ts

@@ -0,0 +1,476 @@
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { Image } from 'image-js';
+import { VisualizerStore } from '../../store/visualizer-store.service';
+import { RegionStore } from '../../store/region-store.service';
+import { IImageInfo } from '../../contracts/image.contract';
+import { TileAccessPort } from '../../contracts/ports/tile-access.port';
+import { VizConfig } from '../../contracts/viz-config';
+import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
+import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from '../../contracts/visualizer.contract';
+import { ViewerCapabilities } from '../../contracts/capabilities.contract';
+import { IRegionOverlay } from '../../contracts/region-overlay.contract';
+import { BaseStoreVisualizer } from '../base-store-visualizer';
+import { SimpleSliceAccessService } from '../simple-slice-access.service';
+import { WandToolService } from '../../toolbar/wand/wand-tool.service';
+import { BrushToolService } from '../../toolbar/brush/brush-tool.service';
+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 { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import * as i0 from "@angular/core";
+/** One pyramid level from `GET /tiles/info`. */
+interface TileLevel {
+    res: number;
+    width: number;
+    height: number;
+}
+/** Tile-source descriptor returned by `GET /tiles/info`. */
+interface TileDescriptor {
+    width: number;
+    height: number;
+    tileSize: number;
+    z: number;
+    channels: number;
+    /** True only for genuine multi-channel composites (indexed/LUT-bearing
+     *  fluorescence stacks) the client should split into per-channel layers. The
+     *  server sets it; an RGB photo read as separated planes has channels>1 but
+     *  multichannel=false, so it stays a single composite tile source. */
+    multichannel?: boolean;
+    /** Real Bio-Formats resolution levels at the front of `levels`; the remaining
+     *  levels are synthetic composited overviews (no per-channel tiles). */
+    realLevels?: number;
+    /** Per-channel metadata (name/color/bitDepth/min-maxAllowed) for native 16-bit
+     *  windowing + histogram; null for plain 8-bit/RGB sources. */
+    channelInfo?: Array<{
+        name?: string;
+        color?: string;
+        bitDepth?: number;
+        minAllowed?: number;
+        maxAllowed?: number;
+    }> | null;
+    levels: TileLevel[];
+    /** Physical pixel size in µm (0 when the format doesn't report it). */
+    mppX?: number;
+    mppY?: number;
+}
+/** What `load()` hands to `plot()`. */
+interface OsdLoaded {
+    descriptor: TileDescriptor | null;
+    infoB64: string;
+    z: number;
+    /** Mirrors the loaded image's filename — the diagram's render pipeline
+     *  guards on `loaded.filename === phaseInfo.fileName` before calling plot(). */
+    filename: string | undefined;
+    /** Simple (non-tiled) image: `plot()` opens {@link url} directly via OSD's
+     *  single-image source — no tile pyramid, no server. Set when the image
+     *  carries `tiled === false` (see {@link IImageInfo.tiled}). */
+    simple?: boolean;
+    /** The directly-loadable image URL (`blob:`/`data:`/`http`) for simple mode. */
+    url?: string;
+}
+/**
+ * OpenSeadragon visualization backend.
+ *
+ * Renders the *image* plot type as a natively-tiled, zoomable raster, backed by
+ * the jit-service tile endpoints (`GET /tiles/info` + `GET /tile`, which reuse
+ * the Bio-Formats ROI renderer). Plotly keeps the scientific/data plot types
+ * (scalar heatmap, surface, contour, scatter, line, scatter3d, isosurface) —
+ * hence this backend advertises only `ImageDisplay`.
+ *
+ * Wired: load → descriptor, plot → mount viewer with a custom tile source,
+ * zoom/pan → viewport API. NOT wired yet (follow-ups): region overlays + tools
+ * (a positioned canvas/SVG overlay or Annotorious), pixel readback, and the
+ * per-tile LUT/contrast params. Not registered in DI providers — `PlotlyService`
+ * is still the only active backend; this proves the contract supports a second
+ * implementation against real endpoints.
+ */
+export declare class OpenSeadragonVisualizerService extends BaseStoreVisualizer implements IVisualizer {
+    private http;
+    private tiles;
+    private wandTool;
+    private brushTool;
+    private samTool;
+    private samPointTool;
+    private cellSegmentTool;
+    private cellSegmenter;
+    private eraserTool;
+    private zoomToBoxTool;
+    private simpleStack;
+    /** OSD's strength is displaying a large zoomable image — nothing else here. */
+    readonly capabilities: ViewerCapabilities;
+    private readonly api;
+    private viewer;
+    private overlay;
+    private scaleBar;
+    private descriptor;
+    /** Base64 RawFileInfo + current z-slice, kept so setZIndex can rebuild the
+     *  tile source and swap slices live (stack navigation). */
+    private infoB64;
+    private currentZ;
+    /** True while the current image is "simple" (tiled:false — self-contained
+     *  per-slice URLs, no tile server; e.g. a numbered image series assembled
+     *  client-side into a stack). setZIndex swaps the single-image source for
+     *  the new slice's URL instead of updating a tiled z-param. */
+    private simpleMode;
+    /** urls[] for the current simple-mode image, so setZIndex can look up the
+     *  slice being scrubbed to (via {@link SimpleSliceAccessService.urlFor}).
+     *  Unused (and left stale, harmlessly) in tiled mode. */
+    private simpleUrls;
+    /** preview blob URL → full-res upscaled blob URL (see toFullResUrl), so
+     *  re-visiting a simple-mode slice doesn't re-upscale. Revoked on file change. */
+    private readonly simpleFullResUrls;
+    /** Skip the full-res upscale above this longest-side dimension — a folder
+     *  stack is per-file previews (well under this); this only guards against an
+     *  accidental enormous canvas allocation. */
+    private readonly SIMPLE_UPSCALE_MAX_DIM;
+    private coordTransform;
+    private wandHost;
+    private eraserHost;
+    /** Wand sampling matrix read back from the rendered viewport; cached until
+     *  the viewport changes (see readbackViewport). */
+    private viewportPixels;
+    /** The DOM id of the element OSD is mounted in (shared with Plotly); the
+     *  on-canvas tools attach their overlays here. */
+    private plotDiv;
+    /** Current file name, tagged onto wand-created shapes. */
+    private currentFileName;
+    /** 256-entry RGB LUT for the active colormap, applied to grayscale tiles via
+     *  the tile-invalidated pixel pipeline (mirrors Plotly's heatmap colorscale).
+     *  Null while options resolve; recoloring is skipped until it's built. */
+    private colorLut;
+    /** Only grayscale images get a colormap (RGB tiles pass through untouched). */
+    private isGrayscaleImage;
+    private colormapSub;
+    /** Latest per-channel display state (window/gamma/visibility) from the store,
+     *  read synchronously by recolorTile. Channel 0 drives grayscale windowing;
+     *  R/G/B (indices 0-2) drive RGB per-channel windowing. */
+    private channelStates;
+    /** True for multichannel fluorescence (channelCount > 1, not RGB): tiles are
+     *  composited client-side from per-channel single-band fetches (see
+     *  recolorMultiChannelTile) rather than recolored in place. */
+    private isMultiChannel;
+    /** Count of real Bio-Formats resolution levels (per-channel tiles exist only
+     *  here). For multichannel images the tile source is built from these alone so
+     *  every displayed tile supports a per-channel fetch. */
+    private realLevels;
+    /** Inverted background (white = zero): inverts the display value before the
+     *  LUT (grayscale) / per channel (RGB). */
+    private invertBg;
+    /** Bearer token for OSD's own tile fetches (HttpClient calls get it via the
+     *  interceptor; OSD's loader does not, so we pass it as an ajax header). */
+    private authHeaders;
+    /** Whether the overview navigator (minimap) is shown. Read at viewer creation;
+     *  a consumer that doesn't want it (e.g. a small embedded preview) sets it off
+     *  via {@link setNavigatorVisible} before the first render. */
+    private navigatorVisible;
+    /** Image smoothing (bilinear). `false` → nearest-neighbour, so zoomed-in pixels
+     *  render as crisp blocks (pixel inspection). Defaults to `false` so the image
+     *  opens showing raw pixels. Read at viewer creation; toggled via
+     *  {@link setImageSmoothingEnabled}. */
+    private smoothingEnabled;
+    /** Overall deadline for the /tiles/info poll loop. An uncached whole-slide
+     *  image (e.g. .ndpi) is cached server-side first (GCS->PVC), which can take
+     *  several minutes — we poll (short requests; the cache-progress overlay
+     *  shows the wait) until it's ready. Generous because each poll is cheap; on
+     *  expiry the render pipeline gives up and the router falls back to Plotly. */
+    private readonly tilesInfoTimeoutMs;
+    /** Per-channel fit-view tile budget (tiles at the coarsest real level × channels).
+     *  Above it, a multichannel image renders server-composited instead of per-channel
+     *  — its full-res reads (it has no overview pyramid) would be too many × N channels.
+     *  64 (e.g. a 4x4 single-FOV z-stack × 4ch) stays per-channel; a whole-slide
+     *  (hundreds–thousands) falls back. */
+    private readonly MAX_MULTICHANNEL_FIT_TILES;
+    /** Pixel display pipeline (window/gamma/invert/colormap + additive tint) —
+     *  shared by tile recoloring and the composite export so they stay identical
+     *  (see DisplayPipeline). Host closures read the service's live fields. */
+    private readonly display;
+    /** Histogram + auto-window sampling (see HistogramSampler). Constructed in
+     *  the ctor body because it captures the resolved API base URL. */
+    private sampler;
+    /** Stack-slice cache + background preloader (see SliceCache — refactoring
+     *  plan Step 3). The host accessors are live closures, so the cache always
+     *  reads the service's current viewer/descriptor/z — exactly the fields the
+     *  moved code used to read directly. */
+    private readonly cache;
+    constructor(http: HttpClient, tiles: TileAccessPort, wandTool: WandToolService, brushTool: BrushToolService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, eraserTool: VertexEraserToolService, zoomToBoxTool: ZoomToBoxToolService, store: VisualizerStore, regionStore: RegionStore, simpleStack: SimpleSliceAccessService, config: VizConfig);
+    private readonly stackLoading$;
+    private readonly stackLoadingProgress$;
+    private readonly autoscaleEvent$;
+    /** Visible image region (full-image pixel coords) emitted when the view
+     *  settles, so the intensity inset can re-sample at the current zoom level. */
+    private readonly viewportChange$;
+    private readonly intensityProfile$;
+    /**
+     * Subscribe to the shared VisualizerStore colormap/reverse so OSD recolors in
+     * lock-step with Plotly. Idempotent and self-healing: this service is a root
+     * singleton, but `unsubscribe()` (called on VisualizerComponent destroy)
+     * tears the subscription down — and the constructor never runs again. So
+     * `plot()` calls this to re-establish it after a component teardown/recreate
+     * (e.g. switching images), otherwise colormap changes would be silently
+     * dropped on every image after the first switch.
+     */
+    private ensureColormapSubscription;
+    /** Seed the Intensity channel with a measured auto-window while it's still
+     *  at full range (never clobber the user's manual window); if the user
+     *  already windowed, just re-invalidate so painted tiles pick the LUT up. */
+    private seedGrayWindow;
+    /**
+     * Fetch the tile-source descriptor for the selected file. The `info` param is
+     * the base64 RawFileInfo the rest of the API uses; the GET goes through the
+     * auth interceptor (Bearer). We also grab a token here for OSD's own tile
+     * fetches (its loader bypasses HttpClient).
+     */
+    load(imageInfo: IImageInfo, zIndex: number): Promise<OsdLoaded>;
+    /** Build the `plot()` payload for a simple (tiled:false) image: a single-level
+     *  descriptor sized from `trueImageSize`, plus the directly-loadable URL —
+     *  resolved and fetched via {@link SimpleSliceAccessService} (shared with
+     *  napari-js; see its docs for why this can't be a raw `fetch()`/`<img>`). */
+    private loadSimple;
+    /**
+     * OSD's `{type:'image'}` source sizes its coordinate world to the image's
+     * NATURAL pixels. A folder-stack slice is a server `/preview` whose pixel size
+     * needn't match the full-resolution image — it may be downscaled (large
+     * images) OR larger than the dimensions `/metadata` reports. Either way OSD's
+     * world would differ from the full-res ROI coordinate space (QuPath geojson,
+     * in level-0 pixels): a smaller preview renders ROIs oversized, a larger one
+     * renders them undersized/offset. Resample the preview to EXACTLY the
+     * full-resolution dimensions (blurry but positionally exact — scaling up or
+     * down as needed) so OSD's world matches the ROI coordinate space, while still
+     * using OSD's reliable single-image renderer. Cached per preview URL (revoked
+     * on file change); a no-op when the preview is already exactly full-res (small
+     * images, in-memory pipeline blobs), when the dims are unknown, or when
+     * they're implausibly large (guards against an enormous canvas). (jit-ui#93)
+     */
+    private toFullResUrl;
+    /** Load a URL into an HTMLImageElement (resolves once decoded). Uses
+     *  document.createElement rather than `new Image()` because this file's
+     *  `Image` import is image-js's decoder, not the DOM element. */
+    private loadImageEl;
+    private revokeSimpleFullResUrls;
+    /** Mount the viewer with a custom tile source pointing at `GET /tile`. */
+    plot(plotDiv: string, imageLoaded: any, imageInfo: IImageInfo, _screenHeight: number, _plotType: PlotType, inPlace?: boolean): Promise<boolean>;
+    /**
+     * Fit-to-home once `el` first has a non-zero size. If it's already sized we
+     * rely on the timed refits the caller scheduled; otherwise a one-shot
+     * ResizeObserver runs `refit` the moment the container is laid out (then
+     * disconnects), so the initial fit doesn't depend on the render's start time
+     * relative to the diagram container's layout. No-op without a container or
+     * ResizeObserver (the timed refits remain the fallback). One-shot + only
+     * attached on a fresh mount, so slice-scrub re-opens keep the user's zoom.
+     */
+    private fitWhenContainerSized;
+    /**
+     * Custom tile source built from the descriptor. OSD numbers levels
+     * coarsest-first; the backend numbers resolutions full-res-first, so
+     * `res = (levels-1) - osdLevel`. Overriding getLevelScale/getNumTiles lets us
+     * honour Bio-Formats' actual per-level dimensions (not assume power-of-two).
+     */
+    private buildTileSource;
+    /** Re-apply the display pipeline (window/gamma/colour/invert) after a state change.
+     *  Multichannel invalidates ONLY the visible slice's channel images — invalidating
+     *  the whole world would re-process every hidden/preloaded slice's tiles (hundreds),
+     *  flooding OSD with "[CacheRecord] … InvalidStateError" and wasting work on tiles
+     *  that aren't on screen. The other cached slices are marked stale and re-tinted
+     *  lazily when revealed. Composite/grayscale invalidate the world as before. */
+    private invalidateDisplay;
+    private destroyViewer;
+    /** This backend's region renderer (the SVG overlay), once a plot is mounted. */
+    getRegionOverlay(): IRegionOverlay | null;
+    /** OSD renders only the image type — no isosurface, so no controls. */
+    getIsosurfaceControls(): IIsosurfaceControls | null;
+    /** OSD renders only the image type — no 3D scenes, so no controls. */
+    getSurface3dControls(): ISurface3dControls | null;
+    /** OSD renders only the image type — no LINE intensity ROIs, so no controls. */
+    getIntensityControls(): IIntensityControls | null;
+    private toOverlayMode;
+    reloadAndPlot(): void;
+    reset(): void;
+    relayout(_trueImageSize?: number[]): void;
+    resetAxes(): void;
+    autoscale(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setDragMode(mode: string | false): void;
+    setShowStack(_showstack: boolean): void;
+    /** Show/hide the overview navigator. Stored for the next viewer creation, and
+     *  applied live when a viewer is already mounted (hides/reveals its element —
+     *  the navigator instance itself only exists when created with showNavigator). */
+    setNavigatorVisible(visible: boolean): void;
+    /** Toggle bilinear smoothing vs nearest-neighbour (crisp pixels). Stored for the
+     *  next viewer creation, and applied live (with a redraw) to a mounted viewer. */
+    setImageSmoothingEnabled(enabled: boolean): void;
+    /**
+     * Swap the displayed z-slice live. Slices are kept as separate tiled images in
+     * the world, so switching is just an opacity toggle: a previously-visited slice
+     * shows instantly (its decoded + recolored tiles are still resident), and a
+     * never-seen slice is added once. The region overlay, coordinate transform,
+     * scale bar, colormap pipeline and current zoom/pan all persist — the x/y
+     * geometry is identical across slices.
+     *
+     * Simple mode (tiled:false — a numbered image series assembled client-side,
+     * each slice its own complete image with no shared tile server) has no
+     * pyramid to toggle opacity on, so it re-opens the viewer on the new
+     * slice's URL instead. preserveViewport (viewer option, see plot()) keeps
+     * the current zoom/pan across that reopen.
+     */
+    setZIndex(zIndex: number): void;
+    setStackLoading(stackLoading: boolean): void;
+    isStackLoading(): Observable<boolean>;
+    getStackLoadingProgress(): Observable<number>;
+    getTrueImageSize(): {
+        width: number;
+        height: number;
+    } | null;
+    getCurrentImage(): Promise<Image | null>;
+    /**
+     * The currently displayed pixels — the rendered viewport (what the user sees,
+     * including the current zoom and any colormap recolor), as RGBA. Feeds the
+     * processing-pipeline dialog's "use current view". Returns null until tiles
+     * are drawn.
+     */
+    getDisplayedPixelData(): PixelData | null;
+    /**
+     * Image-pixel rectangle the drawer canvas (what {@link getDisplayedPixelData}
+     * reads) currently covers. Unlike {@link emitViewportChange}, this is NOT
+     * clamped to the image bounds: the canvas maps 1:1 to the viewport rectangle,
+     * so leaving it unclamped keeps `canvasPx -> imagePx` an exact affine map
+     * (clamping would skew coordinates near the image edges). Routed through world
+     * item 0 (see {@link viewportRectToImage}) for multi-layer accuracy.
+     */
+    getDisplayedSourceRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    downloadImage(): void;
+    setPlotType(_plotType: PlotType): void;
+    setSurfaceDragMode(_mode: string): void;
+    resetSurfaceCamera(): void;
+    getAutoscaleEvent(): Observable<any>;
+    /** Visible image region (full-image pixel coords), emitted when the view
+     *  settles. The intensity inset re-samples this region at the zoom resolution. */
+    getViewportChange$(): Observable<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** {@link IIntensitySampling} stub — intensity sampling lives in the Plotly
+     *  backend (it owns pixel readback). OSD feeds it only via getViewportChange$;
+     *  the sampling-cache priming itself is a no-op here. */
+    ensureIntensitySampling(_imageInfo: IImageInfo, _zIndex: number): Promise<void>;
+    /** {@link IIntensitySampling} stub — see {@link ensureIntensitySampling}. */
+    refreshIntensitySamplingForRoi(_x: number, _y: number, _width: number, _height: number, _zIndex: number): void;
+    /** Compute the current viewport's image-pixel rectangle (clamped to the image)
+     *  and broadcast it. */
+    private emitViewportChange;
+    /** OSD targets the image display; the scalar/3D plot types belong to Plotly. */
+    getPlotTypeDescriptors(): PlotTypeDescriptor[];
+    getIntensityProfile$(): Observable<IntensityProfile[]>;
+    /** OSD only renders the image type; the LINE intensity inset is Plotly-only. */
+    renderIntensityInset(_divId: string, _profiles: IntensityProfile[]): void;
+    setWandMode(active: boolean, options?: any): void;
+    setWandOptions(options: any): void;
+    clearActiveWandRegion(): void;
+    setBrushMode(active: boolean, options?: any): void;
+    setBrushOptions(options: any): void;
+    setVertexEraserMode(active: boolean): void;
+    setVertexEraserRadius(radius: number): void;
+    setZoomToBoxMode(active: boolean): void;
+    /** Box-prompted SAM: segment the drawn rectangles. The SAM tool reuses the
+     *  wand host (viewport readback + coordinate transform + region store). */
+    segmentRectangles(): Promise<number>;
+    segmentRectanglesCellpose(): Promise<number>;
+    setSamModel(id: string): void;
+    setSamPointMode(active: boolean): void;
+    commitSamPoints(): void;
+    clearSamPoints(): void;
+    /** Build the wand/eraser host objects bound to this backend. Both tools run
+     *  over OSD via the shared coordinate transform + a viewport pixel readback,
+     *  and read/write regions directly on the shared RegionStore (neutral model). */
+    private buildToolHosts;
+    /** The element the on-canvas tool overlays attach to (OSD is mounted here). */
+    private getOverlayContainer;
+    /** Size the navigator from the CURRENT container (navigatorSizeRatio of the
+     *  viewer element) and keep it pinned to the corner. OSD computes the size
+     *  once in the Viewer constructor — before the host flex layout settles —
+     *  and never corrects it, leaving a stale-size element whose visible minimap
+     *  floats above the bottom-right corner. */
+    private resizeNavigator;
+    /** Force the docked toolbar to repaint after an OSD zoom. Chrome leaves it
+     *  laid-out-but-unpainted (the canvas's compositing churn strands the toolbar's
+     *  raster). A synchronous display toggle re-rasters it with no visible gone-frame
+     *  and no layout shift. Located via the DOM since this service doesn't own the
+     *  toolbar; a no-op when there's no toolbar (e.g. embedded without one). */
+    private nudgeToolbarRepaint;
+    /** Host for the (shared) zoom-to-box tool: convert overlay pixels to image
+     *  coords via the viewport, and fit the viewport to the chosen rectangle. */
+    private zoomBoxHost;
+    /** Fit the OSD viewport to an image-space rectangle (coords ordered
+     *  [xMin, xMax, yMax, yMin]). */
+    private applyZoomToBox;
+    /**
+     * Read back the *currently rendered* OSD canvas as the wand's pixel matrix.
+     * The matrix covers only the visible viewport at screen resolution, so when
+     * the user is zoomed into a sub-region the wand samples that region's detail
+     * (rather than the whole image at preview resolution). `originX/originY` and
+     * `ratios` map image coords <-> readback-pixel coords for the wand's
+     * data/ratio/origin model. Cached until the viewport changes.
+     */
+    private readbackViewport;
+    /**
+     * Recolor a grayscale tile through the active colormap LUT, using OSD's
+     * tile-invalidated pixel pipeline (OSD 5+/6). Maps each pixel's grayscale
+     * value (r==g==b) to the LUT's RGB. No-op for RGB images or until the LUT is
+     * built. Handler is async — OSD awaits it (raiseEventAwaiting).
+     */
+    private recolorTile;
+    /**
+     * Tint a single channel's tile in place. Each channel is its own OpenSeadragon
+     * TiledImage (a single-band grayscale tile); OSD composites the N images
+     * additively ('lighter') in its drawer — so this just maps the tile's intensity
+     * through the channel's window/gamma and its pseudo-colour. Synchronous (no
+     * cross-tile fetch) → no race, no seams. Channel is parsed from the tile URL.
+     */
+    private recolorChannelTile;
+    /** Per-channel histogram for the Channels & Histogram pane, from the current
+     *  slice's sampled tiles (grayscale → channel 0; RGB → R/G/B). Null until the
+     *  async sampling resolves or if it was skipped. */
+    getHistogram(channelIndex: number, _bins: number): IHistogram | null;
+    /** Native bit depth of a channel from the tile descriptor (8 when unknown). */
+    private channelBitDepth;
+    /**
+     * Async histogram for the Channels & Histogram pane. For >8-bit images it
+     * fetches the **native** distribution from the server `/histogram` endpoint
+     * (the 8-bit canvas tiles can't carry 16-bit values) and caches it per
+     * slice+channel; for 8-bit/RGB it returns the existing client-sampled 8-bit
+     * histogram. Read-only — it never touches the tile/display pipeline.
+     */
+    getHistogram$(channelIndex: number, bins: number): Observable<IHistogram | null>;
+    /**
+     * Export the underlying image data as a data-preserving multi-band TIFF at
+     * native bit depth via `GET /export/tiff` (the server reads the raw 16-bit
+     * planes — the client never sees them). Sends only the visible channels; the
+     * existing 8-bit composite PNG export is unaffected.
+     */
+    exportData(): Promise<void>;
+    /**
+     * Export the current slice as a publication-ready PNG composited with the
+     * active display settings (window / gamma / colormap or per-channel pseudo-
+     * colours / invert). Picks the largest pyramid level under a pixel cap (the
+     * coarser overview for huge whole-slides), fetches that level's tile grid,
+     * stitches it into one canvas, runs the shared display pipeline, and saves it.
+     */
+    exportComposite(): Promise<void>;
+    /** True if any pixel in the RGBA buffer is non-transparent. */
+    private hasOpaque;
+    unsubscribe(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<OpenSeadragonVisualizerService, [null, null, null, null, null, null, null, { optional: true; }, null, null, null, null, null, null]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<OpenSeadragonVisualizerService>;
+}
+export {};

package/lib/implementations/osd/osd-coordinate-transform.d.ts

@@ -0,0 +1,17 @@
+import { ICoordinateTransform } from '../../contracts/coordinate-transform.contract';
+/**
+ * OpenSeadragon implementation of {@link ICoordinateTransform}. "Data coords"
+ * here are image-pixel coordinates (OSD's native shape space), obtained from the
+ * viewport API. This is the reason the tools can run over OSD at all: the
+ * viewport gives a clean screen<->image mapping that holds across pan/zoom.
+ */
+export declare class OsdCoordinateTransform implements ICoordinateTransform {
+    private viewer;
+    constructor(viewer: any);
+    isReady(): boolean;
+    clientToData(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    dataLengthToScreen(dataLength: number): number;
+}

package/lib/implementations/osd/osd-coords.d.ts

@@ -0,0 +1,16 @@
+/** Viewer-element pixel -> image (data) coordinates. */
+export declare function elementToImage(viewer: any, x: number, y: number): {
+    x: number;
+    y: number;
+};
+/** Image (data) coordinates -> viewer-element pixel point. */
+export declare function imageToElement(viewer: any, x: number, y: number): {
+    x: number;
+    y: number;
+};
+/** Image-space rectangle -> viewport rectangle (for fitBounds). */
+export declare function imageRectToViewport(viewer: any, x: number, y: number, w: number, h: number): any;
+/** Viewport rectangle -> image (data) rectangle. Routes through world item 0 so
+ *  it stays accurate when the world holds multiple images (stack slices /
+ *  per-channel layers); falls back to the viewport when the world is empty. */
+export declare function viewportRectToImage(viewer: any, vpRect: any): any;

package/lib/implementations/osd/osd-lib.d.ts

@@ -0,0 +1,19 @@
+import * as OpenSeadragon from 'openseadragon';
+/**
+ * The real OpenSeadragon object, normalized for the packaged (FESM) build.
+ *
+ * OpenSeadragon ships as plain CommonJS (`module.exports = OpenSeadragon`, no
+ * `__esModule` flag). Bundled into this library's FESM and re-bundled by a
+ * consuming app, `import * as OpenSeadragon` resolves to a synthesized ES
+ * namespace whose only reliable slot is `.default` (the real `module.exports`).
+ * The factory itself and every static member (Viewer, Point, Rect, TileSource, …)
+ * live on that object, NOT on the namespace — so `OpenSeadragon(...)` or
+ * `new OpenSeadragon.Point()` against the namespace fail once packaged
+ * ("is not a function" / "not a constructor"). Normalize ONCE here and import
+ * { OSD } wherever a runtime VALUE is needed; import the `openseadragon` namespace
+ * directly only for its TYPES (e.g. `OpenSeadragon.Viewer`).
+ *
+ * (plotly.js-dist-min needs no equivalent: it sets `__esModule`, so webpack gives
+ * it real named exports and plain member access works.)
+ */
+export declare const OSD: typeof OpenSeadragon;