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

package/lib/region-editor/region-editor.component.d.ts

@@ -0,0 +1,305 @@
+import { OnDestroy, OnInit } from '@angular/core';
+import { OverlayPanel } from 'primeng/overlaypanel';
+import { Region } from '../models/region';
+import { PresetSet, ClassPreset } from '../models/class-preset';
+import { ConfirmationService, MessageService } from 'primeng/api';
+import { IRegionEditorApi } from '../contracts/region-editor-api.contract';
+import { RegionIoPort } from '../contracts/ports/region-io.port';
+import * as i0 from "@angular/core";
+export declare class RegionEditorComponent implements OnInit, OnDestroy {
+    private regionApi;
+    messageService: MessageService;
+    private confirmationService;
+    private regionIo;
+    protected readonly Array: ArrayConstructor;
+    overlayPanel: OverlayPanel;
+    regions: Region[];
+    regionsCopy: Region[];
+    selectedRegions: Region[];
+    showShapeLabel: boolean;
+    shapeColor: string;
+    fillColor: string;
+    displayHelpDialog: boolean;
+    showColorDialog: boolean;
+    /** One colour editor per unique class among the selected regions, shown in the
+     *  "edit colour of selected regions" dialog. Unclassified regions (no label)
+     *  are grouped under a single entry with an empty `label`. */
+    classColorEdits: {
+        label: string;
+        color: string;
+    }[];
+    labelColors: Map<string, string>;
+    selectedLabelColor: string;
+    /** "Edit class on selected rows" popup: chosen existing class, and a new-class name. */
+    bulkClass: string;
+    newBulkClass: string;
+    /** Local mirror of the per-user preset set (chip strip, Class dropdown, dialog). */
+    presetSet: PresetSet;
+    /** Class applied to newly drawn/added regions and to bulk chip-clicks. */
+    activeClass: string | null;
+    showManageDialog: boolean;
+    /** Working copy edited inside the Manage-classes dialog; committed on Apply/Done. */
+    presetDraft: PresetSet | null;
+    /** class name (match-mode keyed) → number of regions currently using it. */
+    classCounts: Map<string, number>;
+    /** Fallback class that a region reverts to when its class is deleted (jit-ui#70). */
+    readonly defaultClassName = "Region";
+    /** Classes as shown in the panel: sorted by region count (desc), then name. */
+    displayClasses: ClassPreset[];
+    readonly matchModeOptions: {
+        label: string;
+        value: string;
+    }[];
+    paginatorFirst: number;
+    paginatorRows: number;
+    readonly rowsPerPageOptions: number[];
+    /** Regions whose Class cell is currently in edit mode.
+     *  Using object identity as the key avoids needing a unique id field. */
+    editingLabelRegions: Set<any>;
+    showSaveAsDialog: boolean;
+    saveAsFilename: string;
+    saveAsFileExists: boolean;
+    /** True while a GeoJSON persist is serializing/uploading — drives the dialog's
+     *  progress bar and Cancel button (parity with the Save-mask dialog). */
+    saveAsBusy: boolean;
+    private _saveAsCheck$;
+    private _saveAsSub?;
+    /** Handle for the deferred-serialize timer so Cancel/destroy can abort it
+     *  before it fires (otherwise the upload would still start). */
+    private _saveAsTimer?;
+    showExportDialog: boolean;
+    exportFilename: string;
+    showSaveMaskDialog: boolean;
+    saveMaskFilename: string;
+    /** Mask type chosen in the Save-mask dialog: a binary foreground/background
+     *  mask, or a multi-class mask with a distinct id per region. */
+    maskMode: 'binary' | 'multiclass';
+    /** True while the mask worker is rasterizing/encoding — drives the progress
+     *  bar and the Cancel button in the dialog. */
+    maskBusy: boolean;
+    /** 0–100 rasterization progress; switches to indeterminate during encoding. */
+    maskProgress: number;
+    maskEncoding: boolean;
+    private maskWorker?;
+    private pendingMaskFilename;
+    /**
+     * PrimeNG p-table multi-selection mode toggle. When true, single-click
+     * selects one row (replacing prior); meta/ctrl-click toggles a row in/out
+     * of the selection. When false, every click toggles. Default true to
+     * match the most common spreadsheet-like UX.
+     */
+    metaKey: boolean;
+    private _updatingFromEditor;
+    private _suppressSelectionSyncToPlot;
+    private _regionSub;
+    private _selectedIdxSub;
+    private _metaSub;
+    private _presetSub;
+    /** Physical pixel size (µm/pixel) of the active image, for region areas in
+     *  µm². Undefined when the format reports no physical size. */
+    private mppX?;
+    private mppY?;
+    constructor(regionApi: IRegionEditorApi, messageService: MessageService, confirmationService: ConfirmationService, regionIo: RegionIoPort);
+    /**
+     * Deep copy of regions for dirty-tracking (`regionsCopy`). Returns plain-object
+     * clones — only structural equality matters here, not prototypes.
+     * TODO: replace with `structuredClone` once verified.
+     */
+    private deepClone;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    /**
+     * Table → Plot: PrimeNG fires onRowSelect/onRowUnselect after updating
+     * `selectedRegions`. Push the selected regions to the contract by identity —
+     * the package maps them to its internal index space (which includes the
+     * intensity-profile lines the editor never sees).
+     */
+    onSelectionChanged(): void;
+    /**
+     * Apply classification colours and refresh the label→colour map for regions
+     * coming from the visualizer. The visualizer hands back neutral `Region`
+     * objects with bounds, colour and label already populated, so the editor no
+     * longer parses any backend-specific shape format — it only fills in a
+     * fallback colour and rebuilds its local label→colour lookup.
+     */
+    private applyRegionColors;
+    /**
+     * Push edits from the editor to the diagram in live-edit mode (no save /
+     * cancel buttons). The `_updatingFromEditor` guard is still used so the
+     * resulting regionUpdateEvent doesn't bounce back as an external change.
+     */
+    private setRegionsFromEditor;
+    /** Set one region's outline colour from the per-row picker and commit live.
+     *  Remembers it as the label's colour so same-class regions added later match
+     *  (jit-ui#85 — the Region Editor's per-region Color column). */
+    changeRegionColor(region: Region, color: string): void;
+    addRectangle(): void;
+    /**
+     * Update the label of the region on enter key pressed (when editing a label cell in the table)
+     * @param region
+     * @param setRegion
+     */
+    labelRegionUpdate(region: Region, setRegion?: boolean): void;
+    xRectUpdate(region: Region, event: any): void;
+    yRectUpdate(region: Region, event: any): void;
+    widthRectUpdate(region: Region, event: any): void;
+    heightRectUpdate(region: Region, event: any): void;
+    onPageChange(event: {
+        first?: number;
+        rows?: number;
+    }): void;
+    /** Select every region in the table (and highlight them on the diagram). */
+    selectAllRegions(): void;
+    deleteSelectedRegions(): void;
+    clearAllRegions(): void;
+    addPolygon(): void;
+    deleteRegion(shapeIdx: number): void;
+    private clampPaginatorFirst;
+    changeShowShapeLabel(showLabel: boolean): void;
+    isEditingLabel(region: any): boolean;
+    startEditLabel(region: any, event?: Event): void;
+    stopEditLabel(region: any, commit: boolean, event?: Event): void;
+    isRectangle(region: Region): boolean;
+    /**
+     * Region area for display: in µm² (or mm²) when the image reports a physical
+     * pixel size, otherwise in px². Empty string for degenerate regions.
+     */
+    regionArea(region: Region): string;
+    /**
+     * Choose the physical pixel size (µm/pixel) for area display from the image
+     * meta. The calibration may sit on any channel entry — not necessarily [0] —
+     * so pick the first entry with a positive mppX (mirrors
+     * PlotlyService.currentMpp). Falls back to square pixels (mppY = mppX) when
+     * only one axis is reported, so a scaled image shows µm²/mm² rather than px².
+     */
+    private pickMpp;
+    /** Pixel area: width·height for rectangles, shoelace formula for polygons.
+     *  Interior rings (holes) are subtracted, so a donut reports the annulus area,
+     *  not the filled exterior (jit-ui#85). */
+    private areaInPixels;
+    /** Polygon area: exterior shoelace minus each interior ring (hole). */
+    private polygonArea;
+    /** Absolute shoelace area of a single ring. */
+    private ringArea;
+    private fmtArea;
+    /**
+     * This method rounds all the rectangle regions lengths to multiple of 512
+     */
+    roundRectangleLengths(): void;
+    /**
+     * Stop key arrow event propagation
+     * @param event
+     */
+    disableArrowKeys(event: any): void;
+    changeShapeColor(event: any): void;
+    showHelp(): void;
+    /** Open the colour dialog for the currently-selected region(s), building one
+     *  colour picker per unique class in the selection. Each picker is seeded with
+     *  the class's current colour (the label→colour map, falling back to the first
+     *  selected region of that class). */
+    openColorDialog(): void;
+    /** Apply each class's chosen colour to the selected regions of that class and
+     *  commit live. Remembers the colour per class so same-class regions added
+     *  later match. */
+    applyColorToSelected(): void;
+    /** Resolve the display colour for a class name (preset colour or deterministic fallback). */
+    colorForName(name?: string): string;
+    /**
+     * Ensure every class label present in the loaded regions exists in the preset
+     * list, auto-adding any that are missing (using the region's already-resolved
+     * colour). This makes classes carried in a loaded/imported GeoJSON show up as
+     * chips + Class-dropdown options (a p-dropdown can't display a value that isn't
+     * an option) and lets the user manage them. The placeholder 'legend' and empty
+     * labels are ignored. (jit-ui#70)
+     */
+    private syncClassesFromRegions;
+    /** Rebuild the per-class region counts shown in the panel. */
+    private recomputeClassCounts;
+    /** Rebuild the panel's display order — most-used classes first, then by name. */
+    private updateDisplayClasses;
+    /** trackBy for the class rows so re-sorting doesn't re-create the pickers. */
+    trackByClassName: (_: number, c: ClassPreset) => string;
+    /** Number of regions currently using a class (keyed by the active match mode). */
+    classCount(name: string): number;
+    /** Recolour a class from its panel swatch and repaint its (non-overridden) regions. */
+    setClassColor(name: string, color: string): void;
+    /** Tooltip for a class's delete button in the panel. */
+    deleteClassTooltip(name: string): string;
+    /** Remove a class. Any regions still using it fall back to the default
+     *  "Region" class, so they aren't orphaned (and the class isn't immediately
+     *  re-added from its regions by syncClassesFromRegions). */
+    deleteClass(name: string): void;
+    /** Regions labelled with any of `removedNames` revert to the default
+     *  {@link defaultClassName} ("Region"): its class colour, override cleared.
+     *  Skips the default itself so deleting "Region" can't self-reassign. (jit-ui#70) */
+    private reassignRegionsToDefaultClass;
+    /** Stamp a class (and its preset/fallback colour) onto one region from the Class
+     *  dropdown; choosing a class opts the region back into the preset colour. */
+    applyPresetToRegion(region: Region, className: string): void;
+    /** Make a class active (used for new regions) and, if rows are selected, apply
+     *  it to them in one commit. */
+    selectActiveClass(name: string): void;
+    /** Apply a class (label + preset/fallback colour) to the current selection and commit. */
+    private applyClassToSelected;
+    /** "Edit class on selected rows" popup — apply the chosen existing class. */
+    applyBulkClass(): void;
+    /** "Edit class on selected rows" popup — add a new class and set it on the selection. */
+    addAndApplyBulkClass(): void;
+    openManageDialog(): void;
+    private clonePresetSet;
+    addPresetClass(): void;
+    removePresetClass(i: number): void;
+    addFallbackColor(): void;
+    removeFallbackColor(i: number): void;
+    /** Commit the draft: drop blank/duplicate names, persist, and recolour
+     *  non-overridden regions with the updated presets. */
+    applyManageDialog(close: boolean): void;
+    resetPresetsToDefaults(): void;
+    exportPresets(): void;
+    importPresets(event: Event): void;
+    importRois(event: Event): void;
+    /**
+     * Regions to serialize on save/export. For a single-file z-stack the store
+     * keeps only the current slice live, so pull EVERY slice's annotations (each
+     * tagged with its zero-based Region.z) to write one combined z-indexed
+     * geojson (jit-ui#93). Otherwise (single-plane image, or a folder stack whose
+     * slices save to their own per-slice files) the current set. (jit-ui#93)
+     */
+    private regionsForSave;
+    exportRois(): void;
+    confirmExport(): void;
+    /** Open the "Save mask" dialog, seeded with `<image-stem>_mask.png`. */
+    openSaveMaskDialog(): void;
+    /**
+     * Rasterize the regions to the chosen mask type and download as a PNG. The
+     * heavy work (full-res rasterize + PNG encode) runs in a Web Worker so the UI
+     * never freezes on large/whole-slide images and the job can be cancelled
+     * (jit-ui#95). The dialog stays open showing a progress bar until done.
+     */
+    confirmSaveMask(): void;
+    /** Cancel an in-progress mask export: terminate the worker and reset state. */
+    cancelSaveMask(): void;
+    /** Worker factory — async so the worker module (and its `import.meta.url`,
+     *  which the CommonJS test compile rejects) is loaded via a dynamic import,
+     *  exactly like the segmentation worker. Overridable in tests. */
+    protected createMaskWorker(): Promise<Worker>;
+    private finishMask;
+    private maskError;
+    private teardownMaskWorker;
+    persistRegions(): void;
+    /**
+     * Save a folder stack's regions as one geojson per slice-file (jit-ui#93).
+     * Groups the store's per-slice regions by slice index and serializes each on
+     * the default plane (z=0) — each slice-file is itself one plane, and the
+     * loader re-derives the slice index from the file's position in the series.
+     * Slices cleared since load are included (empty) so their file is overwritten.
+     */
+    private saveStackSlices;
+    checkSaveAsFileExists(): void;
+    confirmSaveAs(): void;
+    /** Cancel an in-progress GeoJSON persist: abort the deferred serialize and/or
+     *  the in-flight upload, and reset state. */
+    cancelSaveAs(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RegionEditorComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RegionEditorComponent, "region-editor", never, {}, {}, never, never, false, never>;
+}

package/lib/region-ops.service.d.ts

@@ -0,0 +1,92 @@
+import { Region } from './models/region';
+import { WandService } from './toolbar/wand/wand.service';
+import * as i0 from "@angular/core";
+/**
+ * Pure (DOM-free) region set-operations — merge / inverse / ungroup (jit-ui#85).
+ *
+ * Raster-based, reusing the wand/brush mask pipeline
+ * ({@link WandService.rasterizePolygon} → {@link WandService.maskToPolygons}),
+ * so "select + merge" yields the same geometry as brushing regions together:
+ * one engine, one set of behaviours, holes + multi-part results for free.
+ *
+ * Every method takes the current regions plus the image dimensions and returns
+ * new {@link Region}(s); it never mutates the store. Callers commit the result
+ * through the normal region-write path (so undo/redo applies). Coordinates are
+ * image pixels throughout.
+ */
+export declare class RegionOpsService {
+    private wand;
+    /**
+     * Largest raster (in pixels) a region set-op will allocate on the main thread.
+     * Selections whose clipped bbox exceeds this are rasterized at a proportional
+     * downscale (then the traced geometry is scaled back), so merge/inverse stay
+     * responsive on gigapixel slides. ~16 MP keeps the synchronous contour trace
+     * well under a second; the downscale only affects boundary fidelity of very
+     * large-extent selections (small selections keep full resolution).
+     */
+    private static readonly MAX_OP_PIXELS;
+    constructor(wand: WandService);
+    /**
+     * Geometric union of `regions` into a single region: a {@link Polygon} when
+     * the union is one connected piece, a {@link MultiPolygon} when it stays
+     * disjoint, with holes preserved. Returns null when nothing rasterises (e.g.
+     * only open polylines were selected).
+     */
+    merge(regions: Region[], imageWidth: number, imageHeight: number): Region | null;
+    /** Downscale factor (≤ 1) keeping the selection's clipped bbox within
+     *  {@link MAX_OP_PIXELS}; 1 when it already fits. */
+    private opRasterScale;
+    /** A copy of `p` with every coordinate (and hole coordinate) multiplied by `s`. */
+    private scalePolygon;
+    /**
+     * Replace `regions` with their inverse inside the image rectangle: the image
+     * minus the selection's union (the former regions become holes). Returns null
+     * for a degenerate image or an empty selection.
+     *
+     * Done *vectorially* so it scales to gigapixel images: the selection is
+     * unioned first (raster, bounded by the ROIs' extent — never the whole image),
+     * then the result is the image rectangle as the exterior with each union
+     * component's outline punched out as a hole. A component's own hole (a donut)
+     * becomes a solid island part. Only the image's corner coordinates are used —
+     * no full-image buffer is ever allocated.
+     */
+    inverse(regions: Region[], imageWidth: number, imageHeight: number): Region | null;
+    /** A closed straight-edged Polygon from parallel coord arrays. */
+    private ringPolygon;
+    /**
+     * Split a region into its disjoint parts — one region per {@link MultiPolygon}
+     * part. A single connected {@link Polygon}/{@link Rectangle} has nothing to
+     * split and is returned unchanged (as a one-element list).
+     */
+    ungroup(region: Region): Region[];
+    /** True when ungrouping `region` would actually split it (≥2 parts). */
+    canUngroup(region: Region): boolean;
+    /**
+     * Simplify a region's outline(s) with Douglas–Peucker — drop vertices within
+     * `altitudePx` pixels of the line between their kept neighbours. Applies to
+     * the exterior and every hole, of a polygon or each part of a MultiPolygon; a
+     * ring that would degenerate below a triangle is left at its previous detail
+     * (the part/hole is kept, not dropped). Rectangles and open polylines are
+     * returned unchanged. Result is always a straight-edged polygon (any Bézier
+     * smoothing is dropped, since the anchor set changes).
+     */
+    simplify(region: Region, altitudePx: number): Region;
+    /** Douglas–Peucker the exterior + each hole of one polygon. A ring that
+     *  collapses below 3 vertices keeps its original points (never degenerates). */
+    private simplifyPolygon;
+    /** Union of every region's filled mask (exterior minus holes), or null.
+     *  `scale` (≤ 1) downscales the raster for large selections; coordinates and
+     *  the clip bounds are scaled to match. */
+    private unionMask;
+    /** Rasterise any region (rect / closed polygon / multi-polygon, holes punched
+     *  out) into a bbox mask. Null for open polylines or degenerate geometry.
+     *  `scale` (≤ 1) shrinks the coordinates and clip bounds for a downscaled raster. */
+    private rasterizeRegion;
+    /** Wrap traced parts as one region (Polygon if single, else MultiPolygon),
+     *  inheriting colour/label from `proto`. Null when there are no parts. */
+    private regionFromParts;
+    private makeRegion;
+    private clonePolygon;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RegionOpsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RegionOpsService>;
+}

package/lib/render-orchestrator.d.ts

@@ -0,0 +1,59 @@
+import { IImageInfo } from './contracts/image.contract';
+/**
+ * Two-pass (small→large) render sequencing, extracted from
+ * VisualizerComponent (refactoring plan, Step 7 — a pure move of the
+ * orchestration; the component keeps the UI flags and supplies them through
+ * the host callbacks).
+ *
+ * When the file has small-tier URLs we render the small tier first for a fast
+ * blurry preview, release the loading overlay (keeping a translucent
+ * "sharpening" spinner), then sharpen by re-rendering the canonical large tier
+ * in place. Without a small tier it's the original single pass. The large pass
+ * retries once after a short delay — the preview endpoint can hit a transient
+ * 503 or a lock-contention window, and the second attempt usually lands on
+ * fresh pre-gen-cached PNGs.
+ */
+export interface TwoPassRenderHost {
+    /** Load + plot one phase (the component owns div/screen/plot-type/z and the
+     *  newer-click filename guard). `inPlace` updates the existing render so the
+     *  canvas doesn't blank during the small→large swap. */
+    renderPhase(info: IImageInfo, inPlace: boolean): Promise<unknown>;
+    /** The small tier is on screen — drop the full loading overlay so the user
+     *  sees the blurry preview, and show the sharpening spinner. */
+    smallShown(): void;
+    /** The large render settled (either way) — sharpening spinner off. */
+    sharpenSettled(): void;
+    /** Rendering finished. `viaSmall` = the overlay was already released by the
+     *  small tier (so only release the running guard + apply the ROI); otherwise
+     *  do the full finalize (overlay + running + ROI). */
+    finished(viaSmall: boolean, logTag: string): void;
+    /** Both large-tier attempts failed; the small tier stays on screen as the
+     *  fallback. Surface it to the user and release the running guard + ROI. */
+    sharpenFailed(err: unknown): void;
+}
+export declare class RenderOrchestrator {
+    private host;
+    private retryDelayMs;
+    constructor(host: TwoPassRenderHost, retryDelayMs?: number);
+    /** Run the render: single-pass when `smallInfo` is null, two-pass otherwise. */
+    render(info: IImageInfo, smallInfo: IImageInfo | null): Promise<void>;
+    /** One retry after a brief delay before giving up on the large tier. */
+    private renderLargeWithRetry;
+}
+/**
+ * Debounced z-slice scrubbing (extracted with the orchestrator): coalesce the
+ * rapid changes a slider drag fires so a slice swap doesn't run on every
+ * pixel; the final value lands immediately via {@link commit} (onSlideEnd).
+ */
+export declare class SliceScrubber {
+    private apply;
+    private delayMs;
+    private timer;
+    constructor(apply: (z: number) => void, delayMs?: number);
+    /** Debounced application of z while dragging. */
+    scrub(z: number): void;
+    /** Apply z immediately (slide end / keyboard step), dropping any pending scrub. */
+    commit(z: number): void;
+    /** Drop a pending scrub without applying (teardown). */
+    cancel(): void;
+}