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

package/fesm2022/jax-data-science-sci-image-visualizer.mjs

@@ -395,6 +395,280 @@ const CELL_SEGMENTER = new InjectionToken('CELL_SEGMENTER', {
     factory: () => inject(CellposeSegmenterService),
 });
 
+/**
+ * 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.
+ */
+const HF = 'https://huggingface.co/Ballon999';
+const EYE_DEFAULTS = {
+    confidence: 0.6,
+    iouThreshold: 0.5,
+    mergeThreshold: 0.3,
+    overlapX: 0,
+    overlapY: 0,
+};
+// Embryos are large, touch each other, and are imaged at native scale — hence
+// the heavy overlap and the far looser merge thresholds.
+const EMBRYO_DEFAULTS = {
+    confidence: 0.6,
+    iouThreshold: 0.8,
+    mergeThreshold: 0.8,
+    overlapX: 60,
+    overlapY: 60,
+};
+const YOLO_MODELS = [
+    {
+        id: 'yolov8x-seg-opticnerve',
+        label: 'Optic nerve',
+        modelUrl: `${HF}/yolov8x-seg-opticnerve-onnx/resolve/main/model.fp16w.onnx`,
+        defaults: { ...EYE_DEFAULTS },
+    },
+    {
+        id: 'yolov8x-seg-retina',
+        label: 'Retina',
+        modelUrl: `${HF}/yolov8x-seg-retina-onnx/resolve/main/model.fp16w.onnx`,
+        defaults: { ...EYE_DEFAULTS },
+    },
+    {
+        id: 'yolov8x-seg-embryo-m2',
+        label: 'Embryo (M2)',
+        modelUrl: `${HF}/yolov8x-seg-embryo-m2-onnx/resolve/main/model.fp16w.onnx`,
+        defaults: { ...EMBRYO_DEFAULTS },
+    },
+    {
+        id: 'yolov8x-seg-embryo-m3',
+        label: 'Embryo (M3)',
+        modelUrl: `${HF}/yolov8x-seg-embryo-m3-onnx/resolve/main/model.fp16w.onnx`,
+        defaults: { ...EMBRYO_DEFAULTS },
+    },
+];
+const DEFAULT_YOLO_MODEL_ID = 'yolov8x-seg-opticnerve';
+let defaultModelId = DEFAULT_YOLO_MODEL_ID;
+/** Look up a model definition by id. Returns undefined for an unknown id. */
+function getYoloModel(id) {
+    return YOLO_MODELS.find((m) => m.id === id);
+}
+/** Whether a model has a usable weights URL configured. */
+function isYoloModelReady(id) {
+    const m = getYoloModel(id);
+    return !!m && m.modelUrl.trim().length > 0;
+}
+/**
+ * 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.
+ */
+function setYoloModelUrls(id, urls) {
+    const m = getYoloModel(id);
+    if (!m)
+        return;
+    if (urls.modelUrl !== undefined)
+        m.modelUrl = urls.modelUrl;
+    if (urls.metaUrl !== undefined)
+        m.metaUrl = urls.metaUrl;
+}
+/** Change which model runs when a caller does not name one. */
+function setDefaultYoloModel(id) {
+    if (getYoloModel(id))
+        defaultModelId = id;
+}
+function getDefaultYoloModelId() {
+    return defaultModelId;
+}
+
+/**
+ * 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.
+ */
+class YoloSegmenterService {
+    constructor() {
+        this.instances = new Map();
+        this.loading = new Map();
+    }
+    async segmentInstances(image, opts = {}, progress) {
+        const modelId = opts.modelId ?? getDefaultYoloModelId();
+        const def = this.requireModel(modelId);
+        let announcedDownload = false;
+        const seg = await this.getModel(modelId, (loaded, total) => {
+            if (total)
+                progress?.onProgress?.(loaded / total);
+            progress?.onBytes?.(loaded, total);
+            if (loaded > 0 && !announcedDownload) {
+                announcedDownload = true;
+                progress?.onStatus?.(`Downloading ${def.label} model…`);
+            }
+        }, (status) => progress?.onStatus?.(status));
+        progress?.onStatus?.('Running inference…');
+        const result = await seg.segment({ data: image.data, width: image.width, height: image.height }, {
+            confThreshold: opts.confidence ?? def.defaults.confidence,
+            iouThreshold: opts.iouThreshold ?? def.defaults.iouThreshold,
+            threshold: opts.mergeThreshold ?? def.defaults.mergeThreshold,
+            overlapX: opts.overlapX ?? def.defaults.overlapX,
+            overlapY: opts.overlapY ?? def.defaults.overlapY,
+            ...(opts.maskThreshold !== undefined ? { maskThreshold: opts.maskThreshold } : {}),
+            ...(opts.maxDetections !== undefined ? { maxDetections: opts.maxDetections } : {}),
+            ...(opts.classFilter ? { classFilter: opts.classFilter } : {}),
+            ...(opts.withMasks !== undefined ? { withMasks: opts.withMasks } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            // Only worth tracing when there are masks to trace.
+            tracePolygons: opts.withMasks !== false,
+            traceOptions: {
+                ...(opts.simplifyTolerance !== undefined ? { simplifyTolerance: opts.simplifyTolerance } : {}),
+                ...(opts.minArea !== undefined ? { minArea: opts.minArea } : {}),
+            },
+            onTileProgress: (done, total) => progress?.onStatus?.(done < total ? `Running inference (tile ${done}/${total})…` : 'Tracing outlines…'),
+        });
+        // Detections without geometry are dropped rather than surfaced as empty
+        // regions — a detection whose mask vanished under thresholding has nothing
+        // meaningful to draw or edit.
+        const detections = [];
+        for (const d of result.detections) {
+            if (!d.polygons || d.polygons.length === 0)
+                continue;
+            detections.push({
+                polygons: d.polygons.map((p) => ({
+                    exterior: p.exterior.map(([x, y]) => [x, y]),
+                    holes: p.holes.map((h) => h.map(([x, y]) => [x, y])),
+                })),
+                box: [d.box[0], d.box[1], d.box[2], d.box[3]],
+                score: d.score,
+                classId: d.classId,
+                className: d.className ?? `class${d.classId}`,
+            });
+        }
+        return {
+            detections,
+            width: result.width,
+            height: result.height,
+            classNames: result.classNames,
+        };
+    }
+    /**
+     * 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 = getDefaultYoloModelId(), onProgress, onStatus) {
+        const existing = this.instances.get(modelId);
+        if (existing)
+            return Promise.resolve(existing);
+        const inFlight = this.loading.get(modelId);
+        if (inFlight)
+            return inFlight;
+        const def = this.requireModel(modelId);
+        const load = (async () => {
+            // Lazy: keep yolo-segdetect-js + its ORT runtime out of the initial bundle.
+            const { YoloSegmenter, configureOrt } = await import('yolo-segdetect-js');
+            configureOrt({ wasmPaths: getOrtWasmBase() });
+            const seg = await YoloSegmenter.fromPretrained(def.modelUrl, {
+                preload: true,
+                ...(def.metaUrl ? { metaUrl: def.metaUrl } : {}),
+                onProgress: ({ loaded, total }) => onProgress?.(loaded, total),
+                onStatus: (s) => onStatus?.(s),
+            });
+            this.instances.set(modelId, seg);
+            return seg;
+        })();
+        this.loading.set(modelId, load);
+        // A failed load must not poison the cache — the next caller should retry
+        // rather than inherit the rejected promise forever.
+        load.catch(() => this.loading.delete(modelId));
+        return load;
+    }
+    /** Whether a model is already loaded (warm). */
+    isLoaded(modelId = getDefaultYoloModelId()) {
+        return this.instances.has(modelId);
+    }
+    /**
+     * 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.
+     */
+    async dispose(modelId) {
+        const ids = modelId ? [modelId] : [...new Set([...this.instances.keys(), ...this.loading.keys()])];
+        await Promise.all(ids.map((id) => this.disposeOne(id)));
+    }
+    async disposeOne(id) {
+        const pending = this.loading.get(id);
+        const loaded = this.instances.get(id);
+        this.instances.delete(id);
+        this.loading.delete(id);
+        if (loaded)
+            await loaded.dispose();
+        if (!pending)
+            return;
+        // A pending load assigns instances[id] before its promise resolves, so by
+        // the time this await returns the entry is back. Clear it only if it still
+        // points at what *this* load produced — a newer load started in the
+        // meantime owns its own entry and must not be evicted.
+        const seg = await pending.catch(() => null);
+        if (!seg || seg === loaded)
+            return;
+        if (this.instances.get(id) === seg)
+            this.instances.delete(id);
+        await seg.dispose();
+    }
+    requireModel(modelId) {
+        const def = getYoloModel(modelId);
+        if (!def)
+            throw new Error(`Unknown YOLO model id "${modelId}".`);
+        if (!def.modelUrl.trim()) {
+            throw new Error(`YOLO model "${modelId}" is not configured — its modelUrl is empty.`);
+        }
+        return def;
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.9", ngImport: i0, type: YoloSegmenterService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.3.9", ngImport: i0, type: YoloSegmenterService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.9", ngImport: i0, type: YoloSegmenterService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * 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.
+ */
+const INSTANCE_SEGMENTER = new InjectionToken('INSTANCE_SEGMENTER', {
+    providedIn: 'root',
+    factory: () => inject(YoloSegmenterService),
+});
+
 /**
  * Unified image container used throughout the processing pipeline.
  * Decouples pipeline logic from any specific library's image format.
@@ -21784,5 +22058,5 @@ function provideVisualization() {
  * Generated bundle index. Do not edit.
  */
 
-export { ALL_TOOLBAR_TOOLS, CELL_SEGMENTER, CHANNEL_HISTOGRAM_API, CellposeSegmenterService, ChannelHistogramComponent, DEFAULT_FALLBACK_PALETTE, DEFAULT_SAM_MODEL_ID, HexColorPickerComponent, IMAGE_STATE_PORT, ImageConverterService, LUT_COLORS, MultiPolygon, NAPARI_DECIMATE_OPTIONS, NAPARI_DEFAULT_DECIMATE, PLOT_TYPE_DESCRIPTORS, PREFERENCES_PORT, PlotType, Polygon, ProcessingImage, REGION_EDITOR_API, REGION_IO_PORT, Rectangle, Region, RegionEditorComponent, RoutingVisualizerService, SAM_MODELS, ShapeSelection, TILE_ACCESS_PORT, VISUALIZER, VIZ_CONFIG, ViewerFeature, VisualizationModule, VisualizerComponent, capabilitiesOf, cropImage, defaultPresetSet, getDefaultSamModelId, getOrtWasmBase, getPlotTypeDescriptor, getSamModel, isEmptyPresetSet, isNapari3d, isNapariIsosurface, isNapariScatter, isNapariScatter3d, isNapariSurface, isNapariVolume, isSamModelReady, isThreeDimensional, provideVisualization, setDefaultSamModel, setOrtWasmBase, setSamModelUrls };
+export { ALL_TOOLBAR_TOOLS, CELL_SEGMENTER, CHANNEL_HISTOGRAM_API, CellposeSegmenterService, ChannelHistogramComponent, DEFAULT_FALLBACK_PALETTE, DEFAULT_SAM_MODEL_ID, DEFAULT_YOLO_MODEL_ID, HexColorPickerComponent, IMAGE_STATE_PORT, INSTANCE_SEGMENTER, ImageConverterService, LUT_COLORS, MultiPolygon, NAPARI_DECIMATE_OPTIONS, NAPARI_DEFAULT_DECIMATE, PLOT_TYPE_DESCRIPTORS, PREFERENCES_PORT, PlotType, Polygon, ProcessingImage, REGION_EDITOR_API, REGION_IO_PORT, Rectangle, Region, RegionEditorComponent, RoutingVisualizerService, SAM_MODELS, ShapeSelection, TILE_ACCESS_PORT, VISUALIZER, VIZ_CONFIG, ViewerFeature, VisualizationModule, VisualizerComponent, YOLO_MODELS, YoloSegmenterService, capabilitiesOf, cropImage, defaultPresetSet, getDefaultSamModelId, getDefaultYoloModelId, getOrtWasmBase, getPlotTypeDescriptor, getSamModel, getYoloModel, isEmptyPresetSet, isNapari3d, isNapariIsosurface, isNapariScatter, isNapariScatter3d, isNapariSurface, isNapariVolume, isSamModelReady, isThreeDimensional, isYoloModelReady, provideVisualization, setDefaultSamModel, setDefaultYoloModel, setOrtWasmBase, setSamModelUrls, setYoloModelUrls };
 //# sourceMappingURL=jax-data-science-sci-image-visualizer.mjs.map