@jax-data-science/sci-image-visualizer 0.2.8 → 0.2.10

package/index.d.ts

@@ -22,10 +22,13 @@ export * from './lib/contracts/display-types';
 export * from './lib/contracts/sam.contract';
 export * from './lib/contracts/cell-segmenter.contract';
 export { CellposeSegmenterService } from './lib/toolbar/segmentation/cellpose-segmenter.service';
+export * from './lib/contracts/instance-segmenter.contract';
+export { YoloSegmenterService } from './lib/toolbar/segmentation/yolo-segmenter.service';
 export { ProcessingImage } from './lib/processing/processing-image';
 export { cropImage, CropImageOptions } from './lib/processing/image-crop';
 export { ImageConverterService } from './lib/processing/image-converter.service';
 export { SAM_MODELS, DEFAULT_SAM_MODEL_ID, getSamModel, isSamModelReady, setSamModelUrls, setDefaultSamModel, getDefaultSamModelId, } from './lib/toolbar/segmentation/sam-model-registry';
+export { YOLO_MODELS, DEFAULT_YOLO_MODEL_ID, getYoloModel, isYoloModelReady, setYoloModelUrls, setDefaultYoloModel, getDefaultYoloModelId, YoloModelDef, } from './lib/toolbar/segmentation/yolo-model-registry';
 export { setOrtWasmBase, getOrtWasmBase } from './lib/toolbar/segmentation/ort-runtime-config';
 export * from './lib/models/region';
 export * from './lib/models/class-preset';

package/lib/contracts/instance-segmenter.contract.d.ts

@@ -0,0 +1,124 @@
+import { InjectionToken } from '@angular/core';
+/**
+ * Port for an automatic **instance** segmenter — one that returns discrete,
+ * classified objects rather than a per-pixel label map.
+ *
+ * This is a sibling of {@link ICellSegmenter}, not a replacement. Cellpose-style
+ * segmenters produce one exclusive label per pixel, which is exactly right for
+ * densely packed cells; a detector like YOLO produces overlapping instances,
+ * each with its own class and confidence, and flattening those into a label map
+ * would silently discard both the overlap and the classification. The two
+ * outputs are genuinely different shapes, so they get different ports.
+ *
+ * Geometry is returned as polygon rings in **image pixels**, ready to become
+ * {@link Region}s without a second conversion step.
+ */
+/** A closed ring; the last point is NOT a repeat of the first. */
+export type InstanceRing = Array<[number, number]>;
+/** One polygon with optional interior rings (donut holes). */
+export interface InstancePolygon {
+    exterior: InstanceRing;
+    holes: InstanceRing[];
+}
+/** One detected object. */
+export interface InstanceDetection {
+    /**
+     * Outline(s) of this instance. Usually one, but a mask that splits under
+     * thresholding yields several — they all belong to the same detection.
+     */
+    polygons: InstancePolygon[];
+    /** `[x1, y1, x2, y2]` in image pixels. */
+    box: [number, number, number, number];
+    /** Model confidence, 0..1. */
+    score: number;
+    classId: number;
+    className: string;
+}
+export interface InstanceSegmentation {
+    detections: InstanceDetection[];
+    width: number;
+    height: number;
+    /** Class names indexed by class id, from the model's own metadata. */
+    classNames: string[];
+}
+/**
+ * Tunables for one run.
+ *
+ * Three separate thresholds are in play and they are easy to conflate:
+ * `confidence` and `iouThreshold` act per tile, while `mergeThreshold` governs
+ * the cross-tile reconciliation. They come from different stages of the
+ * pipeline and are not interchangeable.
+ */
+export interface InstanceSegmentOptions {
+    /** Which registered model to run. Defaults to the registry's default. */
+    modelId?: string;
+    /** Minimum detection confidence, per tile. */
+    confidence?: number;
+    /** NMS IoU within a single tile. */
+    iouThreshold?: number;
+    /** Intersection-over-smaller threshold for merging across tile seams. */
+    mergeThreshold?: number;
+    /** Tile overlap, percent. */
+    overlapX?: number;
+    overlapY?: number;
+    /** Probability at which a mask pixel counts as inside. */
+    maskThreshold?: number;
+    /** Cap on detections per tile. */
+    maxDetections?: number;
+    /** Keep only these class ids; omit for all classes the model declares. */
+    classFilter?: number[];
+    /** Douglas-Peucker tolerance in pixels for outline simplification; 0 disables. */
+    simplifyTolerance?: number;
+    /** Drop instances whose outline area is below this, in square pixels. */
+    minArea?: number;
+    /**
+     * Set false to detect boxes without assembling masks — substantially faster,
+     * since mask assembly dominates the cost of a run. Detections then carry a
+     * box and class but no outline, so nothing can be committed as a region.
+     */
+    withMasks?: boolean;
+    /**
+     * Abort an in-progress run.
+     *
+     * Cancellation is cooperative and checked at tile boundaries, so it takes
+     * effect within roughly one tile rather than instantly — a `session.run()`
+     * already in flight cannot be interrupted.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Progress/status callbacks (all optional).
+ *
+ * Deliberately mirrors {@link CellSegmentProgress} in shape rather than importing
+ * it — the two contracts stay independently versionable.
+ */
+export interface InstanceSegmentProgress {
+    /** Model-download progress, 0..1 (first run only). */
+    onProgress?: (fraction: number) => void;
+    /**
+     * Raw download byte counts, for hosts that render a size ("142 / 287 MB")
+     * rather than a bare percentage. `total` is null when the response carried no
+     * Content-Length.
+     *
+     * A fraction alone cannot be turned back into bytes, so a host given only
+     * {@link onProgress} has to invent the numbers — which reads as "0 MB / 0 MB"
+     * the moment it does.
+     */
+    onBytes?: (loaded: number, total: number | null) => void;
+    /** Human-readable phase, e.g. 'Running inference (tile 3/8)…'. */
+    onStatus?: (status: string) => void;
+}
+export interface IInstanceSegmenter {
+    /** Detect and outline all instances in an RGBA image. */
+    segmentInstances(image: {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    }, opts?: InstanceSegmentOptions, progress?: InstanceSegmentProgress): Promise<InstanceSegmentation>;
+}
+/**
+ * DI token for the automatic instance segmenter. Defaults to the in-library
+ * {@link YoloSegmenterService} (yolo-segdetect-js, lazy-loaded); override it in
+ * the host to swap implementations — for example to delegate to the server.
+ */
+export declare const INSTANCE_SEGMENTER: InjectionToken<IInstanceSegmenter>;

package/lib/toolbar/segmentation/yolo-model-registry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Registry of YOLOv8-seg instance-segmentation models.
+ *
+ * Mirrors {@link SAM_MODELS}: public HF-hosted ONNX by default so the tool works
+ * out of the box in any host, repointable at private hosting via
+ * {@link setYoloModelUrls}.
+ *
+ * Each entry carries the per-model *defaults* the server-side worker uses for
+ * that checkpoint. These are properties of how the model was trained (object
+ * scale, expected crowding), not UI preferences — the embryo models want heavy
+ * 60% tile overlap and loose merge thresholds because their objects are large
+ * and touch, while the eye models were trained on sparse, downsampled fields.
+ * Keeping them here means a host that just picks a model gets sane behaviour
+ * without having to know any of that.
+ *
+ * Weights point at the `model.fp16w.onnx` variant deliberately. The `.fp16`
+ * variant accumulates in half precision on WebGPU and, at the x-scale these
+ * models use, produces materially wrong boxes; `fp16w` stores weights in fp16
+ * and computes in fp32, so it is half the download at identical accuracy.
+ *
+ * Export tooling: the sibling `browser-onnx-tools` project.
+ */
+export interface YoloModelDef {
+    id: string;
+    label: string;
+    /** URL of the `.onnx` weights. Empty disables the model. */
+    modelUrl: string;
+    /**
+     * URL of the `model.json` sidecar. Omit to use `model.json` alongside the
+     * weights, which is how every published repo is laid out.
+     */
+    metaUrl?: string;
+    /** Per-model defaults, from the server worker's model table. */
+    defaults: {
+        confidence: number;
+        iouThreshold: number;
+        mergeThreshold: number;
+        overlapX: number;
+        overlapY: number;
+    };
+}
+export declare const YOLO_MODELS: YoloModelDef[];
+export declare const DEFAULT_YOLO_MODEL_ID = "yolov8x-seg-opticnerve";
+/** Look up a model definition by id. Returns undefined for an unknown id. */
+export declare function getYoloModel(id: string): YoloModelDef | undefined;
+/** Whether a model has a usable weights URL configured. */
+export declare function isYoloModelReady(id: string): boolean;
+/**
+ * Repoint a model at different hosting (e.g. a GCS bucket or a same-origin
+ * proxy). Call once at app init, before the first run. An empty `modelUrl`
+ * disables the model.
+ */
+export declare function setYoloModelUrls(id: string, urls: {
+    modelUrl?: string;
+    metaUrl?: string;
+}): void;
+/** Change which model runs when a caller does not name one. */
+export declare function setDefaultYoloModel(id: string): void;
+export declare function getDefaultYoloModelId(): string;

package/lib/toolbar/segmentation/yolo-segmenter.service.d.ts

@@ -0,0 +1,50 @@
+import type { IInstanceSegmenter, InstanceSegmentation, InstanceSegmentOptions, InstanceSegmentProgress } from '../../contracts/instance-segmenter.contract';
+import type { YoloSegmenter } from 'yolo-segdetect-js';
+import * as i0 from "@angular/core";
+/**
+ * Default in-library {@link IInstanceSegmenter}, backed by yolo-segdetect-js
+ * (YOLOv8-seg on WebGPU, falling back to WASM).
+ *
+ * `yolo-segdetect-js` is a regular dependency but is **lazy-imported** on first
+ * use, so apps that never run YOLO pay nothing for it — or for onnxruntime-web —
+ * in their initial bundle. This mirrors {@link CellposeSegmenterService}.
+ *
+ * The one structural difference from the Cellpose service: there are four YOLO
+ * checkpoints, not one, so instances are cached **per model id** rather than as
+ * a single singleton. Each entry owns its own worker and ORT session, so a host
+ * that switches models pays a second load but keeps the first one warm. Nothing
+ * evicts automatically — these are ~144 MB each, so a host that cycles through
+ * all four should call {@link dispose} for the ones it is done with.
+ */
+export declare class YoloSegmenterService implements IInstanceSegmenter {
+    private readonly instances;
+    private readonly loading;
+    segmentInstances(image: {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    }, opts?: InstanceSegmentOptions, progress?: InstanceSegmentProgress): Promise<InstanceSegmentation>;
+    /**
+     * The shared segmenter for a model id, created on first use and reused
+     * thereafter (deduped across concurrent callers). Exposed so a host's
+     * processing pipeline can drive richer `segment()` options on the same loaded
+     * session instead of loading the model twice.
+     */
+    getModel(modelId?: string, onProgress?: (loaded: number, total: number | null) => void, onStatus?: (status: string) => void): Promise<YoloSegmenter>;
+    /** Whether a model is already loaded (warm). */
+    isLoaded(modelId?: string): boolean;
+    /**
+     * Release one model, or all of them. Safe to call on a model never loaded.
+     *
+     * In-flight loads are torn down too, not just warm ones. Simply dropping the
+     * pending promise and returning would let the load finish afterwards,
+     * re-populate {@link instances}, and strand a live worker and ORT session that
+     * nothing owns — disposal would have reported success while leaking. So a load
+     * that is still running is awaited and then released.
+     */
+    dispose(modelId?: string): Promise<void>;
+    private disposeOne;
+    private requireModel;
+    static ɵfac: i0.ɵɵFactoryDeclaration<YoloSegmenterService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<YoloSegmenterService>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jax-data-science/sci-image-visualizer",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Browser-based scientific image visualization for Angular — gigapixel whole-slide (OpenSeadragon), 2D/3D (Plotly) and WebGPU (napari-js) rendering, with region/annotation editing and in-browser SAM segmentation.",
   "keywords": [
     "angular",
@@ -39,7 +39,8 @@
     "napari-js": "^0.11.0",
     "openseadragon": "^6.0.2",
     "plotly.js-dist-min": "^3.0.1",
-    "tslib": "^2.3.0"
+    "tslib": "^2.3.0",
+    "yolo-segdetect-js": "^0.1.1"
   },
   "peerDependencies": {
     "@angular/animations": "^17.3.0",