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

package/lib/models/bezier.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Bezier-curve helpers (no external dependency).
+ *
+ * JIT supports true bezier regions: a polygon's vertices are the editable
+ * *anchors*, and the smooth curve through them is derived here with the
+ * Catmull-Rom construction — the same algorithm paper.js uses in
+ * `path.smooth()`. The curve interpolates every anchor and
+ * each anchor's two handles are colinear (a smooth tangent).
+ *
+ * The OSD overlay renders the curve as a true cubic SVG path + draggable handles
+ * (see {@link bezierAnchorHandles}); GeoJSON export flattens the *same* cubics
+ * into a dense point list (see {@link bezierCurve}) so a viewer without bezier
+ * support (e.g. QuPath, which just draws the coordinate list) still shows the
+ * smooth shape. Using one algorithm for both keeps what JIT draws identical to
+ * what it exports.
+ *
+ * Pure functions: no DOM, no service state. Coordinates are image pixels.
+ */
+export interface CurvePoints {
+    xs: number[];
+    ys: number[];
+}
+/** A vertex's two cubic-bezier control points (absolute coords) plus whether
+ *  each side has a handle (open-path endpoints have only one). */
+export interface AnchorHandle {
+    in: [number, number];
+    out: [number, number];
+    hasIn: boolean;
+    hasOut: boolean;
+}
+/**
+ * Per-anchor cubic-bezier control points using the Catmull-Rom construction
+ * (tension 1: control = anchor ± (next − prev) / 6). Matches paper.js
+ * `path.smooth()`: the resulting cubic interpolates every anchor and the two
+ * handles of each anchor are colinear. Coordinates are in the input space.
+ */
+export declare function bezierAnchorHandles(xs: number[], ys: number[], closed: boolean): AnchorHandle[];
+/** The Catmull-Rom handles as **relative** offsets `[dx, dy]` per anchor — used
+ *  to initialise a region's editable handles when bezier is turned on. */
+export declare function defaultHandleOffsets(xs: number[], ys: number[], closed: boolean): {
+    in: number[][];
+    out: number[][];
+};
+/** Absolute handles from stored relative offsets (anchor + offset). */
+export declare function handlesFromOffsets(xs: number[], ys: number[], inOff: number[][], outOff: number[][], closed: boolean): AnchorHandle[];
+/** A region's handles: from its stored (editable) offsets when present, else the
+ *  Catmull-Rom default. The single source of truth for both rendering and export. */
+export declare function resolveHandles(xs: number[], ys: number[], closed: boolean, inOff?: number[][], outOff?: number[][]): AnchorHandle[];
+/**
+ * Flatten a cubic bezier (defined by explicit per-anchor handles) into a dense
+ * point list by sampling each segment. The curve passes through every anchor; a
+ * closed ring returns to its first point.
+ */
+export declare function bezierCurveFromHandles(xs: number[], ys: number[], handles: AnchorHandle[], closed: boolean): CurvePoints;
+/**
+ * Flatten the smooth Catmull-Rom bezier through the anchors (no custom handles).
+ * Falls back to the anchors when there are too few to form a curve.
+ */
+export declare function bezierCurve(xs: number[], ys: number[], closed: boolean): CurvePoints;

package/lib/models/class-preset.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Preset annotation classes (jit-ui#70).
+ *
+ * A class is a flat `{ name, color }` pair (v1: no hierarchy, no special-class semantics).
+ * The `PresetSet` is the per-user, server-persisted source of truth for region colours;
+ * see `class-color.util.ts` for the deterministic colour-resolution engine.
+ */
+export type PresetSource = 'user' | 'default' | 'auto';
+export interface ClassPreset {
+    /** The class name — matched against `Region.label`. */
+    name: string;
+    /** Hex colour, `#RRGGBB`. */
+    color: string;
+    /** Reserved for a future per-class overlay-visibility toggle. */
+    visible?: boolean;
+    /** Provenance; `'auto'` = added by opt-in fallback promotion. */
+    source?: PresetSource;
+}
+export type MatchMode = 'exact' | 'normalized';
+export interface PresetSet {
+    /** Ordered list of preset classes. */
+    classes: ClassPreset[];
+    /** Colours used for classes not in `classes` (assigned deterministically). */
+    fallbackPalette: string[];
+    /** Opt-in (default false): add an unknown class to `classes` the first time it is seen. */
+    autoPromote: boolean;
+    /** Label matching against `Region.label` (default `'exact'`). */
+    matchMode: MatchMode;
+}
+/**
+ * Fallback palette for classes not present in the preset set — reasonably distinct hues.
+ * Colours are assigned by a stable hash of the class name, so the same unknown class always
+ * gets the same colour with no stored state.
+ */
+export declare const DEFAULT_FALLBACK_PALETTE: string[];
+/** A fresh default preset set (deep-copied so callers can mutate safely). */
+export declare function defaultPresetSet(): PresetSet;
+/** True when the set has no usable classes (e.g. the server returned an empty/blank record). */
+export declare function isEmptyPresetSet(set: PresetSet | null | undefined): boolean;

package/lib/models/geometry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure geometry helpers extracted from PlotlyService.
+ *
+ * No DOM access, no service state, no `this` — every function is testable
+ * in isolation. Keep it that way: this module is the dumping ground for
+ * shape/mask/SVG-path utilities the wand, vertex eraser, and region editor
+ * share. If a helper grows a `this.shapes` reference, it doesn't belong here.
+ */
+/** A bbox-relative binary mask (1 = filled, 0 = empty). */
+export interface BBoxMask {
+    bx: number;
+    by: number;
+    bw: number;
+    bh: number;
+    mask: Uint8Array;
+}
+/** Parsed single-subpath polygon vertices. */
+export interface PolygonVertices {
+    xpoints: number[];
+    ypoints: number[];
+}
+/**
+ * Parse a single-subpath `M x,y L x,y ... Z` path into vertex arrays.
+ *
+ * Returns null for paths we can't safely round-trip (multi-subpath, curves,
+ * fewer than three vertices). The wand only adopts shapes it produced or
+ * that Plotly's drawclosedpath produces, both of which are single-subpath
+ * polygons.
+ */
+export declare function parseSvgPathPolygon(path: string): PolygonVertices | null;
+/**
+ * Build a closed SVG path string `M x,y L x,y L ... Z` from vertex arrays.
+ * Returns '' for fewer than three vertices (degenerate).
+ */
+export declare function polygonToSvgPath(xpoints: number[], ypoints: number[]): string;
+/**
+ * Build an SVG path string from vertex arrays. Closed polygons end with `Z`,
+ * open polylines do not. Returns '' for fewer than two vertices (degenerate).
+ */
+export declare function verticesToSvgPath(xs: number[], ys: number[], closed: boolean): string;
+/**
+ * Compare two Plotly shape objects for "same region" — used by the wand to
+ * avoid appending duplicates when the user pushes the same find result more
+ * than once. Polygons compare by SVG path string, rectangles compare by
+ * (x0, y0, x1, y1).
+ */
+export declare function shapesEqual(a: any, b: any): boolean;
+/** Returns true if the two bbox-relative masks share at least one set pixel. */
+export declare function masksOverlap(a: BBoxMask, b: BBoxMask): boolean;
+/**
+ * Allocate a fresh accumulator covering both masks and OR them in. The
+ * resulting mask's bbox is the smallest rectangle containing both inputs.
+ */
+export declare function unionMasks(a: BBoxMask, b: BBoxMask): BBoxMask;
+/**
+ * Simplify a closed ring with the Douglas–Peucker algorithm (jit-ui#85):
+ * drop every vertex that lies within `epsilon` pixels (the "altitude
+ * threshold") of the line between its kept neighbours. Anchored at vertex 0
+ * (the ring is closed by appending it). Rings of ≤ 3 vertices, or a
+ * non-positive epsilon, are returned unchanged. Output keeps the closed-ring
+ * convention (no repeated closing point).
+ */
+export declare function simplifyRing(xs: number[], ys: number[], epsilon: number): {
+    xs: number[];
+    ys: number[];
+};

package/lib/models/region.d.ts

@@ -0,0 +1,132 @@
+import { ShapeSelection } from './shape';
+export declare class Region {
+    /** Stable, unique identity for selection and equality. Minted by
+     *  PlotlyService when a region first enters the system. Never derived
+     *  from array index — name collisions across delete/add cycles must
+     *  not break PrimeNG row selection. */
+    id: number;
+    name: string;
+    bounds?: Rectangle | Polygon | MultiPolygon | null;
+    /** profile = an intensity-profile line ROI; rendered/dragged like a region but
+     *  excluded from the Regions tab and exports. Use `isProfile()` to test it —
+     *  it's the canonical marker that separates intensity lines (owned by the
+     *  intensity tool, sampled into the inset) from annotation regions (owned by
+     *  the Region Editor). Both backends (Plotly, OSD) honour it. */
+    kind?: 'profile';
+    color?: string;
+    label?: string;
+    /** True when the user set this region's colour explicitly (Region Editor Color
+     *  column). Preset colour resolution (jit-ui#70) skips overridden regions so a
+     *  manual colour is not clobbered when presets are (re)applied on load/import. */
+    colorOverridden?: boolean;
+    filename?: string;
+    /** Zero-based z-slice this region belongs to within a stack — mirrors
+     *  QuPath's `geometry.plane.z` (a missing plane / default plane reads back as
+     *  0). Used to place/filter ROIs per slice; 0 for a plain single-plane image
+     *  or a region drawn without a slice context (jit-ui#93). */
+    z: number;
+    shapeColor?: string | undefined;
+    bytesPerPixel: number;
+    /**
+     * resolution is the resolution at which the region
+     * was found. In order to get it in the full image
+     * coordinates it will normally be 0. However if
+     * there is a mistake with the resolution it may not
+     * be. We return the resolution here in order to be
+     * sure what it is. The server may need to be changed
+     * to ensure that results regions are always returned
+     * at resolution = 0
+     */
+    resolution: number;
+    cropped: boolean;
+    tileNumber: number;
+    tileCoordinates: number[] | null;
+    /** True for intensity-profile line ROIs (the intensity tool's lines). These are
+     *  NOT annotation regions: they never appear in the Region Editor and editor
+     *  operations (select/save/delete) must never touch them. */
+    isProfile(): boolean;
+    toString(): string;
+    /**
+     * Returns a ShapeSelection object that can be used to
+     * create a shape in Plotly.
+     * @param showRegionLabel
+     * @return ShapeSelection
+     */
+    getShape(showRegionLabel?: boolean): ShapeSelection;
+    isRectangle(bnds: any): bnds is Rectangle;
+    isPolygon(bnds: any): bnds is Polygon;
+}
+export declare class Rectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare class Polygon {
+    npoints: number;
+    xpoints: number[];
+    ypoints: number[];
+    coordinates: number[][];
+    /** false for open polylines; true (default) for closed polygons */
+    closed: boolean;
+    /**
+     * When true the vertices are treated as bezier-spline **anchors** and the
+     * region is rendered/exported as a smooth curve through them. The vertices
+     * stay the editable anchors — toggling this flag is the toBezier
+     * (`true`) / toPolygon (`false`), which only add/remove the curve, never move
+     * the anchors. GeoJSON keeps the flattened curve as the geometry (so QuPath
+     * renders it) plus the anchors + handles + flag in properties (so JIT
+     * round-trips the editable bezier).
+     */
+    bezier: boolean;
+    /**
+     * Per-anchor cubic-bezier control-point offsets, **relative** to their anchor
+     * (so they translate with it). Present only for bezier regions; initialised
+     * from the Catmull-Rom construction (a smooth curve) when bezier is turned on,
+     * then individually editable by dragging the handles. `handlesIn[i]` /
+     * `handlesOut[i]` are `[dx, dy]` for vertex `i`.
+     */
+    handlesIn?: number[][];
+    handlesOut?: number[][];
+    /**
+     * Interior rings (holes) — jit-ui#85. Each ring is a list of `[x, y]`
+     * image-pixel pairs in the SAME closed-polygon convention as the exterior
+     * (`coordinates`): no repeated closing point. Present only on closed polygons.
+     * A point inside the exterior **and** inside any hole is OUTSIDE the region
+     * (even-odd rule). Absent/empty == a solid polygon (the prior behaviour), so
+     * every existing region is unaffected.
+     */
+    holes?: number[][][];
+    /**
+     * Per-hole bézier control-point offsets, parallel to {@link holes} (one entry per ring, each a
+     * list of `[dx, dy]` per ring vertex, **relative** to the vertex). Present only when `bezier` is
+     * on for a donut — seeded from the Catmull-Rom default and individually editable, exactly like
+     * the exterior {@link handlesIn}/{@link handlesOut}. So a donut smoothed to a bézier curves its
+     * holes too (jit-ui#102).
+     */
+    holeHandlesIn?: number[][][];
+    holeHandlesOut?: number[][][];
+}
+/**
+ * A region whose geometry is several disjoint parts — e.g. the result of merging
+ * two non-touching regions, or the inverse of a blob (jit-ui#85). Each part is a
+ * closed {@link Polygon} that may carry its own holes, so a MultiPolygon
+ * represents "sparse bits, some with donut holes" as a single region. Maps 1:1
+ * onto a GeoJSON `MultiPolygon` (and QuPath's geometry).
+ *
+ * A single-part MultiPolygon is equivalent to that Polygon; callers should
+ * prefer a plain {@link Polygon} for one connected part.
+ */
+export declare class MultiPolygon {
+    /** One or more disjoint closed polygons (each may have holes). */
+    polygons: Polygon[];
+}
+export type Bounds = Rectangle | Polygon | {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    npoints?: number;
+    xpoints?: number[];
+    ypoints?: number[];
+};

package/lib/models/shape.d.ts

@@ -0,0 +1,44 @@
+import { Region } from './region';
+import { Datum, Font, Shape, ShapeLabel, ShapeLine, XAxisName, YAxisName } from 'plotly.js-dist-min';
+export declare class ShapeSelection implements Shape {
+    /** Stable, unique identity carried alongside the shape so it round-trips
+     *  through Plotly's relayout untouched. Plotly preserves unknown
+     *  properties on shape objects, so this survives the same way `legend`
+     *  and `fileName` already do. */
+    id: number;
+    name: string;
+    fillcolor: string;
+    label: Partial<ShapeLabel>;
+    layer: 'below' | 'above';
+    legendgroup: string;
+    legendgrouptitle: {
+        text: string;
+        font?: Partial<Font>;
+    };
+    legendrank: number;
+    line: Partial<ShapeLine>;
+    opacity: number;
+    path: string;
+    showlegend: boolean;
+    templateitemname: string;
+    type: 'rect' | 'circle' | 'line' | 'path';
+    visible: boolean | 'legendonly';
+    x0: Datum;
+    x1: Datum;
+    xanchor: number | string;
+    xref: 'paper' | XAxisName;
+    xsizemode: 'scaled' | 'pixel';
+    y0: Datum;
+    y1: Datum;
+    yanchor: number | string;
+    yref: 'paper' | YAxisName;
+    ysizemode: 'scaled' | 'pixel';
+    editable: boolean;
+    legend: any;
+    fileName: string | undefined;
+    kind?: 'profile';
+    /**
+     * Returns a Region object based on the shape type.
+     */
+    getRegion(): Region;
+}

package/lib/plot.utilities.d.ts

@@ -0,0 +1,107 @@
+import { Rectangle, Region } from './models/region';
+import { ShapeSelection } from './models/shape';
+export declare const COLORMAP_OPTIONS: {
+    label: string;
+    data: null;
+    children: {
+        label: string;
+        data: {
+            value: string;
+            src: string;
+        };
+    }[];
+}[];
+export declare const CONFIG: {
+    displaylogo: boolean;
+    responsive: boolean;
+    displayModeBar: boolean;
+    scrollZoom: boolean;
+};
+export declare const CONFIG_SURFACE: {
+    displaylogo: boolean;
+    responsive: boolean;
+    displayModeBar: boolean;
+    scrollZoom: boolean;
+};
+export declare class PlotUtilities {
+    /**
+     * Rounds all the point coordinates of a path ('M13.54,54.566L35.44,33.3L36.22,89.6Z')
+     * becomes 'M14,55L35,33L36,90Z'
+     * @param path
+     */
+    roundPathCoordinates(path: string): string;
+    /**
+     * Transform a 1d array into a matrix given a given width
+     * @param array Uint8Array
+     * @param elementsPerSubArray
+     */
+    arrayToMatrix(array: any[] | Uint8Array, elementsPerSubArray: number): any[];
+    /**
+     * coordinates are of the bottom left and upper right corners of the rectangle, The coordinates
+     * are taken given a yAxis that is up side down (as for all images). If Zoom is out of the image boundary,
+     * it will return the image size coordinates for the new rectangle.
+     * @param coordinates plotly coordinates ([Xaxis.range[0], xAxis.range[1], yAxis.range[0], yaxis.range[1]])
+     * @param trueImageSize true image size [0, x, 0, y]
+     */
+    getRectangle(coordinates: number[], trueImageSize: number[]): Rectangle;
+    /**
+     * given a dom object (found by id), return a Rectangle of the bounding element.
+     * @param div
+     */
+    getDomRectangle(div: string): Rectangle;
+    /**
+     * snap region  to closest pixel in the coordinate (round the coordinates of the region)
+     * @param shape
+     * @private
+     */
+    snapRegion(shape: ShapeSelection): ShapeSelection;
+    /**
+     * Given a figure (path or rectangle), returns a polygon
+     * @param fig
+     */
+    getPolygon(fig: any): any;
+    /**
+     * TESTED
+     * Rounds a list of numbers
+     * @param a
+     */
+    round(a: number[]): number[];
+    /**
+     * TESTED
+     * Returns true of zoom is the same as image size
+     * @param rect Rectangle area
+     * @param trueImgSize
+     * @return true if rect is out of image size boundary
+     */
+    isZoomSameAsImgSize(rect: Rectangle, trueImgSize: number[]): boolean;
+    /**
+     * Save the json string to a file
+     * @param jsonString
+     */
+    saveToFile(jsonString: any, baseName?: string): void;
+    /**
+     * Function that imports ROIs from a geojson object
+     * @param geoJsonStr
+     * @return Region[]
+     */
+    importROIsFromGeoJson(geoJsonStr: string): Region[];
+    /**
+     * Function that returns a geojson object from a Plotly ROI
+     * @param rois
+     * @return FeatureCollection<Geometry, GeoJsonProperties>
+     */
+    exportROIsToGeoJson(rois: Region[]): string;
+    /**
+     * Convert GeoJSON interior rings into the neutral hole representation
+     * (`number[][]` per ring, no repeated closing point). Degenerate rings (< 3
+     * distinct points) are dropped. jit-ui#85.
+     */
+    /**
+     * Build a closed {@link Polygon} from a GeoJSON ring set: `rings[0]` is the
+     * exterior (closing point dropped), `rings[1..]` are interior holes. jit-ui#85.
+     */
+    private polygonFromRings;
+    private ringsToHoles;
+    rgbToHex(r: number, g: number, b: number): string;
+    hexToRgb(hex: string | undefined): number[];
+}

package/lib/processing/image-converter.service.d.ts

@@ -0,0 +1,28 @@
+import { ProcessingImage } from './processing-image';
+import * as i0 from "@angular/core";
+/**
+ * Converts between various image representations. Bridges image-js, browser
+ * canvas/image elements, and the neutral {@link ProcessingImage}. Generic image
+ * plumbing — no app/pipeline coupling.
+ */
+export declare class ImageConverterService {
+    /**
+     * Convert an image-js Image instance to ProcessingImage.
+     * image-js stores pixel data in a typed array with shape (width*height*channels).
+     */
+    fromImageJs(image: any): ProcessingImage;
+    /** Convert from an HTMLCanvasElement. */
+    fromCanvas(canvas: HTMLCanvasElement): ProcessingImage;
+    /** Convert from an HTMLImageElement. */
+    fromHtmlImage(img: HTMLImageElement): ProcessingImage;
+    /** Convert ProcessingImage to a 2D array suitable for Plotly heatmap (grayscale). */
+    toPlotlyHeatmapZ(image: ProcessingImage): number[][];
+    /** Convert ProcessingImage to Plotly RGB arrays [r[][], g[][], b[][]]. */
+    toPlotlyRgbArrays(image: ProcessingImage): {
+        r: number[][];
+        g: number[][];
+        b: number[][];
+    };
+    static ɵfac: i0.ɵɵFactoryDeclaration<ImageConverterService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ImageConverterService>;
+}

package/lib/processing/image-crop.d.ts

@@ -0,0 +1,18 @@
+import { ProcessingImage } from './processing-image';
+/** Crop options in source-image pixels. Out-of-range values are clamped. */
+export interface CropImageOptions {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    /** Power-of-two downsample level applied to the crop (0 = full resolution). */
+    level?: number;
+}
+/**
+ * Crop a rectangular region out of a {@link ProcessingImage} (browser-side, the
+ * counterpart of the JIT server's Slide Crop), optionally downsampling the crop
+ * by `2^level`. The rectangle is in source pixels and clamped to the image, so
+ * out-of-range values snap to the valid region rather than throwing. Always
+ * returns a 4-channel (RGBA) image.
+ */
+export declare function cropImage(image: ProcessingImage, opts?: CropImageOptions): ProcessingImage;

package/lib/processing/processing-image.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unified image container used throughout the processing pipeline.
+ * Decouples pipeline logic from any specific library's image format.
+ */
+export declare class ProcessingImage {
+    readonly width: number;
+    readonly height: number;
+    readonly channels: number;
+    readonly data: Uint8ClampedArray;
+    /** Create from browser ImageData. */
+    static fromImageData(imageData: ImageData): ProcessingImage;
+    constructor(width: number, height: number, channels: number, data: Uint8ClampedArray);
+    /** Convert to browser-native ImageData (RGBA). */
+    toImageData(): ImageData;
+    /** Convert to Blob for saving/downloading. */
+    toBlob(mime?: string): Promise<Blob>;
+}

package/lib/provide-visualization.d.ts

@@ -0,0 +1,34 @@
+import { Provider } from '@angular/core';
+/**
+ * A self-contained, isolated visualization backend chain for a component subtree.
+ *
+ * The chain services are `providedIn: 'root'` singletons, so by default the whole
+ * app shares one viewer's state (regions, image, channels, render handles) — which
+ * is correct for the single main viewer. A consumer that needs a SECOND, independent
+ * viewer (e.g. a modal that mounts `<visualizer>` over the live main view
+ * and must not clobber its regions/image) drops this into its component `providers`:
+ *
+ * ```ts
+ * @Component({
+ *   ...,
+ *   providers: [
+ *     ...provideVisualization(),                 // isolated chain instance
+ *     // plus the host ports + config for THIS viewer:
+ *     { provide: IMAGE_STATE_PORT, useClass: MyImageStateAdapter },
+ *     { provide: TILE_ACCESS_PORT, useClass: MyTileAccessAdapter },
+ *     { provide: REGION_IO_PORT,   useClass: MyRegionIoAdapter },
+ *     { provide: VIZ_CONFIG,       useValue: { slideCropServer: '' } },
+ *   ],
+ * })
+ * ```
+ *
+ * Component-scoped providers shadow the root singletons for that subtree, so the
+ * embedded viewer gets its own router/Plotly/OSD/stores/tools while the rest of the
+ * app keeps the default root instance.
+ *
+ * Lists EVERY stateful service in the chain. Stateless collaborators (HttpClient,
+ * MessageService, WandService) deliberately resolve to root — they hold no
+ * per-viewer state, so sharing them is correct and keeps this list minimal. When a
+ * new stateful service joins the rendering chain, add it here too.
+ */
+export declare function provideVisualization(): Provider[];

package/lib/region-editor/mask-raster.d.ts

@@ -0,0 +1,61 @@
+import { Region } from '../models/region';
+/** A single closed ring (+ optional holes) in image-pixel coordinates. A region
+ *  rasterizes as the union of its parts. Plain data so it survives a
+ *  `postMessage` structured clone into the mask worker. */
+export interface MaskPart {
+    xpoints: number[];
+    ypoints: number[];
+    holes?: number[][][];
+}
+/** A bbox-relative binary mask, as returned by `WandService.rasterizePolygon`. */
+export interface BBoxMask {
+    bx: number;
+    by: number;
+    bw: number;
+    bh: number;
+    mask: Uint8Array;
+}
+/** Polygon-fill function (the wand's scanline rasterizer), injected so this
+ *  module stays free of Angular/DOM and can run inside a worker. */
+export type RasterizeFn = (xpoints: number[], ypoints: number[], imageWidth: number, imageHeight: number, holes?: number[][][]) => BBoxMask | null;
+/**
+ * The largest mask we will allocate, in pixels. A single-channel 8-bit mask is
+ * one byte per pixel, so this is also its byte size. Whole-slide level-0 images
+ * (e.g. 119040×90112 ≈ 1.07e10 px) blow past both the JS typed-array length cap
+ * (~4.29e9) and available memory, so masks for images larger than this are
+ * rasterized at a proportionally downscaled resolution. ~100 MP ≈ 100 MB.
+ */
+export declare const MAX_MASK_PIXELS = 100000000;
+/** Downscale factor (≤ 1) to keep `width * height` within {@link MAX_MASK_PIXELS}.
+ *  1 when the image already fits. */
+export declare function maskScaleFor(width: number, height: number): number;
+/** Multiply every coordinate (and hole coordinate) of a region's parts by
+ *  `scale`, for rasterizing into a downscaled mask. Returns the parts unchanged
+ *  when `scale` is 1. */
+export declare function scaleParts(parts: MaskPart[], scale: number): MaskPart[];
+/** Flatten a region's geometry to plain rings. Rectangles become a 4-point ring;
+ *  polygons keep their points + holes; multi-polygons expand to one part each. */
+export declare function regionToParts(region: Region): MaskPart[];
+/** A rasterized label mask plus the PNG bit depth it should be encoded at. */
+export interface LabelMask {
+    data: Uint8Array | Uint16Array;
+    /** 8 for ≤255 distinct values, 16 for a multi-class mask with >255 regions. */
+    bitDepth: 8 | 16;
+}
+/**
+ * Rasterize regions (as plain parts) to a full image-size label mask (row-major,
+ * `W * H` samples; pixel `(x, y)` at `y * W + x`). Background is 0.
+ *
+ * - `'binary'` — every region pixel is 255 (standard 8-bit black/white mask:
+ *   `> 0` = foreground; also directly viewable).
+ * - `'multiclass'` — each region gets a distinct 1-based id (its index + 1).
+ *   Stays 8-bit for ≤255 regions; promotes to 16-bit beyond that. Ids are
+ *   distinct up to the 16-bit ceiling (65535 regions); a selection larger than
+ *   that exceeds the PNG's representable range and ids wrap (not a realistic
+ *   hand-annotation case, but called out so the limit is explicit).
+ *
+ * Later regions paint over earlier ones where they overlap. `onProgress` is
+ * called after each region (1-based) so a caller can drive a progress bar.
+ * Returns null when nothing rasterises (no regions, zero/insane size).
+ */
+export declare function regionsToMask(regions: MaskPart[][], imageWidth: number, imageHeight: number, mode: 'binary' | 'multiclass', rasterize: RasterizeFn, onProgress?: (done: number, total: number) => void): LabelMask | null;

package/lib/region-editor/mask-worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Factory for the mask-export Web Worker, isolated in its own module so the
+ * `import.meta.url` reference (required by the bundler to locate the worker) is
+ * never pulled into the ts-jest CommonJS compile of the component — the unit
+ * tests `jest.mock` this module instead.
+ */
+export declare function createMaskWorker(): Worker;