@jax-data-science/sci-image-visualizer 0.11.0 → 0.12.0

package/fesm2022/{jax-data-science-sci-image-visualizer-jax-data-science-sci-image-visualizer-BELcx0jv.mjs → jax-data-science-sci-image-visualizer-jax-data-science-sci-image-visualizer-a68Hw5rw.mjs}

@@ -7,6 +7,8 @@ import { BehaviorSubject, firstValueFrom, Subject, Subscription, of, Observable,
 import { timeout, debounceTime, takeUntil, switchMap, catchError, startWith, map } from 'rxjs/operators';
 import * as ort from 'onnxruntime-web';
 import { smoothMesh, surfaceNets, pointInRing as pointInRing$2, ringArea as ringArea$1, traceContours, rasterizePolygon as rasterizePolygon$1, floodFill } from 'napari-js/geometry';
+import { encode } from 'fast-png';
+import { decompress } from 'fzstd';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import * as i1$1 from '@angular/common';
 import { CommonModule } from '@angular/common';
@@ -5925,7 +5927,31 @@ async function readNrrd(bytes, gunzip) {
     // A 3D volume: sections along axis 0, each axis 2 wide and axis 1 high (jit-service's cut).
     const [n0, n1, n2] = sizes.length === 3 ? sizes : [sizes[0], sizes[1], 1];
     const axes = sizes.length === 3 ? { z: 0, x: 2, y: 1 } : { z: 2, x: 0, y: 1 };
-    return volume('nrrd', [n0, n1, n2], axes, data, SAMPLES[type], little);
+    return volume('nrrd', [n0, n1, n2], axes, data, SAMPLES[type], little, nrrdSpacing(field, sizes.length));
+}
+/** Per file axis, the voxel size in micrometres (see {@link LabelVolume.spacing}), or undefined. */
+function nrrdSpacing(field, dims) {
+    let sizes;
+    const directions = field['space directions'];
+    if (directions) {
+        const vectors = directions.match(/\(([^)]*)\)|none/g) ?? [];
+        sizes = vectors.filter((v) => v !== 'none').map((v) => Math.hypot(...v.slice(1, -1).split(',').map(Number)));
+    }
+    else if (field['spacings']) {
+        sizes = field['spacings'].split(/\s+/).map(Number);
+    }
+    if (!sizes || sizes.length !== dims || sizes.some((n) => !(n > 0)))
+        return undefined;
+    // One unit per axis (`space units: "mm" "um" "um"`), each axis scaled by its own.
+    const units = (field['space units'] ?? '').match(/"[^"]*"|\S+/g)?.map((u) => u.replace(/"/g, '').toLowerCase()) ?? [];
+    const factor = (unit) => unit === 'mm' || unit === 'millimeter' || unit === 'millimeters'
+        ? 1e3
+        : unit === 'm' || unit === 'meter' || unit === 'meters'
+            ? 1e6
+            : unit === 'nm' || unit === 'nanometer' || unit === 'nanometers'
+                ? 1e-3
+                : 1; // micrometres, or none said
+    return [...sizes.map((n, i) => n * factor(units[i])), ...(dims === 2 ? [1] : [])];
 }
 function readNifti(bytes) {
     if (bytes.length < 352)
@@ -5952,9 +5978,13 @@ function readNifti(bytes) {
     const offset = Math.max(352, Math.round(view.getFloat32(108, little)));
     const [n0, n1, n2] = [dims[0], dims[1], ndim >= 3 ? dims[2] : 1];
     // Slices along axis 2, each axis 0 wide and axis 1 high (Bio-Formats' planes).
-    return volume('nifti', [n0, n1, n2], { z: 2, x: 0, y: 1 }, bytes.subarray(offset), SAMPLES[type], little);
+    const pixdim = [1, 2, 3].map((i) => Math.abs(view.getFloat32(76 + 4 * i, little)));
+    const units = bytes[123] & 7;
+    const factor = units === 1 ? 1e6 : units === 3 ? 1 : 1e3; // metres, micrometres, else millimetres
+    const spacing = pixdim.every((n) => n > 0) ? pixdim.map((n) => n * factor) : undefined;
+    return volume('nifti', [n0, n1, n2], { z: 2, x: 0, y: 1 }, bytes.subarray(offset), SAMPLES[type], little, spacing);
 }
-function volume(format, n, axes, data, sample, little) {
+function volume(format, n, axes, data, sample, little, spacing) {
     const count = n[0] * n[1] * n[2];
     if (!(count > 0))
         throw new Error(`${format}: empty volume`);
@@ -5970,6 +6000,9 @@ function volume(format, n, axes, data, sample, little) {
         width,
         height,
         slices: n[axes.z],
+        ...(spacing
+            ? { spacing: [spacing[axes.x], spacing[axes.y], spacing[axes.z]] }
+            : {}),
         sliceLabels(z) {
             const out = new Uint32Array(width * height);
             const base = z * stride[axes.z];
@@ -6226,6 +6259,862 @@ async function folderSliceGeoJson(file, regionSet) {
     return JSON.stringify(doc);
 }
 
+/**
+ * The chunk codecs of the zarr stores label images come in (OME-Zarr `labels/`): Blosc framing
+ * with its lz4, zstd or zlib inner codecs (zarr v2's default, as ome-zarr-py writes), zstd (zarr
+ * v3's default), gzip and zlib. Anything else throws rather than be decoded wrongly. Pure: usable
+ * from workers.
+ *
+ * The Blosc framing follows jit-bioformats' `Blosc` (the decoder JIT validated on SpatialData
+ * stores): `u8 version, u8 versionlz, u8 flags, u8 typesize, u32 nbytes, u32 blocksize,
+ * u32 cbytes`, then `u32 bstarts[nblocks]`, then blocks of `nstreams` sub-streams, each
+ * `i32 csize` + bytes (a stream whose csize equals its decoded size stored raw, a negative one a
+ * run of one byte). Flags: 0x1 byte-shuffle, 0x2 memcpyed, 0x4 bit-shuffle, 0x10 no-split, bits
+ * 5-7 the inner codec.
+ */
+const BLOSC_CODECS = ['blosclz', 'lz4', 'snappy', 'zlib', 'zstd'];
+/** Decode a Blosc frame. */
+async function bloscDecompress(frame, inflate = platformInflate) {
+    const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+    if (frame.length < 16)
+        throw new Error('blosc: frame too short');
+    const flags = frame[2];
+    const typesize = frame[3];
+    const nbytes = view.getUint32(4, true);
+    const blocksize = view.getUint32(8, true);
+    const out = new Uint8Array(nbytes);
+    if (nbytes === 0)
+        return out;
+    if (flags & 0x2) {
+        out.set(frame.subarray(16, 16 + nbytes));
+        return out;
+    }
+    if (flags & 0x4)
+        throw new Error('blosc: bit-shuffle is not supported');
+    const code = flags >>> 5;
+    const codec = BLOSC_CODECS[code] ?? `code ${code}`;
+    if (codec !== 'lz4' && codec !== 'zstd' && codec !== 'zlib') {
+        throw new Error(`blosc: inner codec ${codec} is not supported (lz4, zstd or zlib)`);
+    }
+    const shuffle = (flags & 0x1) !== 0 && typesize > 1;
+    const noSplit = (flags & 0x10) !== 0;
+    const nblocks = Math.ceil(nbytes / blocksize);
+    const scratch = shuffle ? new Uint8Array(blocksize) : null;
+    for (let blk = 0; blk < nblocks; blk++) {
+        const bsize = Math.min(blocksize, nbytes - blk * blocksize);
+        const leftover = bsize !== blocksize;
+        const nstreams = !noSplit && !leftover ? typesize : 1;
+        const ssize = Math.floor(bsize / nstreams);
+        let p = view.getUint32(16 + blk * 4, true);
+        const block = scratch ?? out;
+        const base = scratch ? 0 : blk * blocksize;
+        for (let s = 0; s < nstreams; s++) {
+            const csize = view.getInt32(p, true);
+            p += 4;
+            const dst = base + s * ssize;
+            if (csize < 0) {
+                block.fill(-csize & 0xff, dst, dst + ssize);
+                continue;
+            }
+            const src = frame.subarray(p, p + csize);
+            if (csize === ssize) {
+                block.set(src, dst);
+            }
+            else {
+                const dec = codec === 'lz4'
+                    ? lz4BlockDecompress(src, ssize)
+                    : codec === 'zstd'
+                        ? decompress(src)
+                        : await inflate(src, 'deflate');
+                if (dec.length !== ssize)
+                    throw new Error(`blosc: ${codec} produced ${dec.length} of ${ssize} bytes`);
+                block.set(dec, dst);
+            }
+            p += csize;
+        }
+        if (scratch)
+            unshuffle(scratch, bsize, typesize, out, blk * blocksize);
+    }
+    return out;
+}
+/** Decode one LZ4 block (no frame) of `size` bytes. */
+function lz4BlockDecompress(src, size) {
+    const out = new Uint8Array(size);
+    let i = 0;
+    let o = 0;
+    while (i < src.length) {
+        const token = src[i++];
+        let literals = token >>> 4;
+        if (literals === 15) {
+            let b;
+            do {
+                b = src[i++];
+                literals += b;
+            } while (b === 255);
+        }
+        if (o + literals > size || i + literals > src.length)
+            throw new Error('lz4: literals overrun');
+        out.set(src.subarray(i, i + literals), o);
+        i += literals;
+        o += literals;
+        if (i >= src.length)
+            break; // the last sequence has no match
+        const offset = src[i] | (src[i + 1] << 8);
+        i += 2;
+        if (offset === 0 || offset > o)
+            throw new Error('lz4: bad match offset');
+        let length = (token & 15) + 4;
+        if ((token & 15) === 15) {
+            let b;
+            do {
+                b = src[i++];
+                length += b;
+            } while (b === 255);
+        }
+        if (o + length > size)
+            throw new Error('lz4: match overrun');
+        // Byte by byte: a match may overlap what it copies (a run).
+        for (let k = 0; k < length; k++, o++)
+            out[o] = out[o - offset];
+    }
+    if (o !== size)
+        throw new Error(`lz4: produced ${o} of ${size} bytes`);
+    return out;
+}
+/**
+ * Decode a zarr chunk through `codecs`, outermost last as zarr lists them (v2: the one
+ * `compressor`; v3: the bytes-to-bytes codecs after `bytes`).
+ */
+async function decodeChunk(bytes, codecs, inflate = platformInflate) {
+    let data = bytes;
+    for (const codec of [...codecs].reverse()) {
+        switch (codec.id) {
+            case 'blosc':
+                data = await bloscDecompress(data, inflate);
+                break;
+            case 'zstd':
+                data = decompress(data);
+                break;
+            case 'gzip':
+                data = await inflate(data, 'gzip');
+                break;
+            case 'zlib':
+                data = await inflate(data, 'deflate');
+                break;
+            default:
+                throw new Error(`zarr: codec ${codec.id} is not supported (blosc, zstd, gzip, zlib)`);
+        }
+    }
+    return data;
+}
+function unshuffle(src, len, typesize, dst, off) {
+    const n = Math.floor(len / typesize);
+    for (let j = 0; j < typesize; j++) {
+        const base = j * n;
+        for (let i = 0; i < n; i++)
+            dst[off + i * typesize + j] = src[base + i];
+    }
+    // Bytes past the last whole element are not shuffled.
+    for (let k = n * typesize; k < len; k++)
+        dst[off + k] = src[k];
+}
+async function platformInflate(bytes, format) {
+    if (typeof DecompressionStream === 'undefined')
+        throw new Error(`zarr: ${format} chunks need DecompressionStream`);
+    const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream(format));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/**
+ * A label image of an OME-Zarr store (`labels/<name>/`, NGFF 0.4 on zarr v2 or 0.5 on zarr v3),
+ * read in the browser from the store's files (a folder chosen, or a zip's members): its full
+ * resolution level, sliced along z, with the classes its `image-label` metadata names and colours.
+ *
+ * Chunks are decoded when a slice that needs them is read, so a store is never decoded whole.
+ * Only what label images use: C-order chunks of integer (or integer-valued float) samples, through
+ * the codecs {@link decodeChunk} reads, a missing chunk being the fill value. Sharded or transposed
+ * arrays, F-order and filters throw rather than be read wrongly. Pure: usable from workers.
+ */
+/** Whether `files` hold a zarr store (any zarr metadata among them). */
+function hasZarrMetadata(files) {
+    return files.some((f) => /(^|\/)(\.zattrs|\.zarray|\.zgroup|zarr\.json)$/.test(norm(f.name)));
+}
+/**
+ * The first label image of the zarr store among `files` (the order `labels/`'s listing gives,
+ * else the first found), or null when the store has none.
+ */
+async function readOmeZarrLabels(files, inflate) {
+    const byPath = new Map(files.map((f) => [norm(f.name), f]));
+    const groups = new Map();
+    for (const [path, file] of byPath) {
+        const m = /^(.*?)\/?(\.zattrs|zarr\.json)$/.exec(path);
+        if (!m)
+            continue;
+        const doc = JSON.parse(await file.text());
+        const attrs = (m[2] === 'zarr.json' ? doc['attributes'] : doc) ?? {};
+        groups.set(m[1], (attrs['ome'] ?? attrs));
+    }
+    const listed = [];
+    for (const [dir, ome] of groups) {
+        for (const name of ome['labels'] ?? [])
+            listed.push(join(dir, name));
+    }
+    const isLabel = (dir) => {
+        const ome = groups.get(dir);
+        return !!ome?.['multiscales'] && (!!ome['image-label'] || /(^|\/)labels\/[^/]+$/.test(dir));
+    };
+    const dir = [...listed, ...groups.keys()].find(isLabel);
+    if (dir === undefined)
+        return null;
+    const ome = groups.get(dir);
+    const ms = ome['multiscales'][0];
+    const dataset = ms.datasets[0];
+    const array = await readArrayMeta(byPath, join(dir, dataset.path));
+    const axes = (ms.axes ?? ['z', 'y', 'x'].slice(3 - array.shape.length)).map((a) => typeof a === 'string' ? { name: a } : a);
+    if (axes.length !== array.shape.length)
+        throw new Error(`OME-Zarr ${dir}: ${axes.length} axes for a ${array.shape.length}-D array`);
+    const at = (n) => axes.findIndex((a) => a.name.toLowerCase() === n);
+    const ix = at('x');
+    const iy = at('y');
+    const iz = at('z');
+    if (ix < 0 || iy < 0)
+        throw new Error(`OME-Zarr ${dir}: no x and y axes`);
+    const scale = dataset.coordinateTransformations?.find((t) => t.type === 'scale')?.scale;
+    const um = (i) => (i < 0 ? 1 : (scale?.[i] ?? 1) * unitToMicrons(axes[i].unit));
+    const stack = labelStack(byPath, join(dir, dataset.path), array, { ix, iy, iz }, inflate);
+    stack.spacing = [um(ix), um(iy), iz < 0 ? 1 : um(iz)];
+    const name = ms.name ?? dir.split('/').pop() ?? 'labels';
+    return { name, stack, classes: imageLabelClasses(ome['image-label']) };
+}
+async function readArrayMeta(byPath, path) {
+    const v2 = byPath.get(join(path, '.zarray'));
+    if (v2) {
+        const m = JSON.parse(await v2.text());
+        if (m.order && m.order !== 'C')
+            throw new Error(`zarr ${path}: ${m.order}-order chunks are not supported`);
+        if (m.filters?.length)
+            throw new Error(`zarr ${path}: filters are not supported`);
+        const sep = m.dimension_separator ?? '.';
+        return {
+            shape: m.shape,
+            chunks: m.chunks,
+            dtype: v2Dtype(m.dtype, path),
+            codecs: m.compressor ? [m.compressor] : [],
+            fill: Number(m.fill_value ?? 0) || 0,
+            key: (index) => index.join(sep),
+        };
+    }
+    const v3 = byPath.get(join(path, 'zarr.json'));
+    if (!v3)
+        throw new Error(`zarr ${path}: no array metadata`);
+    const m = JSON.parse(await v3.text());
+    if (m.chunk_grid?.name !== 'regular')
+        throw new Error(`zarr ${path}: chunk grid ${m.chunk_grid?.name} is not supported`);
+    const codecs = (m.codecs ?? []);
+    const bytes = codecs[0];
+    if (bytes?.name !== 'bytes') {
+        throw new Error(`zarr ${path}: codec ${bytes?.name ?? 'none'} before bytes is not supported (sharding, transpose)`);
+    }
+    const little = (bytes.configuration?.['endian'] ?? 'little') === 'little';
+    const enc = m.chunk_key_encoding ?? { name: 'default' };
+    const sep = enc.configuration?.separator ?? (enc.name === 'v2' ? '.' : '/');
+    return {
+        shape: m.shape,
+        chunks: m.chunk_grid.configuration.chunk_shape,
+        dtype: v3Dtype(m.data_type, little, path),
+        codecs: codecs.slice(1).map((c) => ({ id: c.name, ...(c.configuration ?? {}) })),
+        fill: Number(m.fill_value ?? 0) || 0,
+        key: (index) => (enc.name === 'v2' ? index.join(sep) : ['c', ...index].join(sep)),
+    };
+}
+/** The slices of the array at `path`, decoding (and keeping) the chunk layers a slice spans. */
+function labelStack(byPath, path, a, axes, inflate) {
+    const { ix, iy, iz } = axes;
+    const width = a.shape[ix];
+    const height = a.shape[iy];
+    const slices = iz < 0 ? 1 : a.shape[iz];
+    const cx = a.chunks[ix];
+    const cy = a.chunks[iy];
+    // The chunks (their decodes, pending or done) of the last chunk layer along z read: a slice's
+    // neighbours share it. A read keeps the layer it started with, so a read of another layer
+    // replacing this cache while it awaits a chunk cannot change what it reads.
+    let layer = null;
+    const chunk = async (index) => {
+        const file = byPath.get(join(path, a.key(index)));
+        if (!file)
+            return null;
+        return decodeChunk(await file.bytes(), a.codecs, inflate);
+    };
+    return {
+        width,
+        height,
+        slices,
+        async labels(z) {
+            if (z < 0 || z >= slices)
+                throw new Error(`slice ${z} of ${slices}`);
+            const kz = iz < 0 ? 0 : Math.floor(z / a.chunks[iz]);
+            if (layer?.kz !== kz)
+                layer = { kz, chunks: new Map() };
+            const mine = layer;
+            const out = new Uint32Array(width * height);
+            const strides = a.chunks.map((_, d) => a.chunks.slice(d + 1).reduce((p, n) => p * n, 1));
+            for (let gy = 0; gy * cy < height; gy++) {
+                for (let gx = 0; gx * cx < width; gx++) {
+                    // Every other axis (time, channel) at its first index.
+                    const index = a.shape.map((_, d) => (d === ix ? gx : d === iy ? gy : d === iz ? kz : 0));
+                    const key = index.join(',');
+                    let pending = mine.chunks.get(key);
+                    if (!pending) {
+                        pending = chunk(index);
+                        mine.chunks.set(key, pending);
+                        // A chunk that failed to decode is not kept: the next read tries it again.
+                        pending.catch(() => mine.chunks.delete(key));
+                    }
+                    const data = await pending;
+                    const view = data ? new DataView(data.buffer, data.byteOffset, data.byteLength) : null;
+                    const inZ = iz < 0 ? 0 : z - kz * a.chunks[iz];
+                    for (let y = gy * cy; y < Math.min(height, (gy + 1) * cy); y++) {
+                        for (let x = gx * cx; x < Math.min(width, (gx + 1) * cx); x++) {
+                            let v = a.fill;
+                            if (view) {
+                                const local = a.shape.map((_, d) => d === ix ? x - gx * cx : d === iy ? y - gy * cy : d === iz ? inZ : 0);
+                                const i = local.reduce((p, n, d) => p + n * strides[d], 0);
+                                v = a.dtype.read(view, i * a.dtype.bytes);
+                            }
+                            if (v > 0xffffffff) {
+                                // A label id past 32 bits would be another label once narrowed: refuse it.
+                                throw new Error(`zarr ${path}: label ${v} does not fit 32 bits`);
+                            }
+                            out[y * width + x] = v > 0 ? v : 0;
+                        }
+                    }
+                }
+            }
+            return out;
+        },
+    };
+}
+const SAMPLE = {
+    u1: { bytes: 1, read: (v, at) => v.getUint8(at) },
+    i1: { bytes: 1, read: (v, at) => v.getInt8(at) },
+    u2: { bytes: 2, read: (v, at, le) => v.getUint16(at, le) },
+    i2: { bytes: 2, read: (v, at, le) => v.getInt16(at, le) },
+    u4: { bytes: 4, read: (v, at, le) => v.getUint32(at, le) },
+    i4: { bytes: 4, read: (v, at, le) => v.getInt32(at, le) },
+    u8: { bytes: 8, read: (v, at, le) => Number(v.getBigUint64(at, le)) },
+    i8: { bytes: 8, read: (v, at, le) => Number(v.getBigInt64(at, le)) },
+    f4: { bytes: 4, read: (v, at, le) => Math.round(v.getFloat32(at, le)) },
+    f8: { bytes: 8, read: (v, at, le) => Math.round(v.getFloat64(at, le)) },
+};
+function v2Dtype(dtype, path) {
+    const m = /^([<>|])([uif])(\d)$/.exec(dtype);
+    const s = m ? SAMPLE[m[2] + m[3]] : undefined;
+    if (!m || !s)
+        throw new Error(`zarr ${path}: dtype ${dtype} is not a label type`);
+    const le = m[1] !== '>';
+    return { bytes: s.bytes, read: (v, at) => s.read(v, at, le) };
+}
+function v3Dtype(type, little, path) {
+    const m = /^(u?int|float)(8|16|32|64)$/.exec(type);
+    const code = m ? (m[1] === 'uint' ? 'u' : m[1] === 'int' ? 'i' : 'f') + Number(m[2]) / 8 : '';
+    const s = SAMPLE[code];
+    if (!s)
+        throw new Error(`zarr ${path}: data type ${type} is not a label type`);
+    return { bytes: s.bytes, read: (v, at) => s.read(v, at, little) };
+}
+/** The classes `image-label` names (a property naming each value) and colours; others unnamed. */
+function imageLabelClasses(meta) {
+    const named = new Map();
+    for (const p of meta?.properties ?? []) {
+        const name = ['name', 'class', 'label', 'acronym', 'structure', 'type']
+            .map((k) => p[k])
+            .find((v) => typeof v === 'string');
+        named.set(p['label-value'], { ...named.get(p['label-value']), name: name });
+    }
+    for (const c of meta?.colors ?? []) {
+        if (!c.rgba)
+            continue;
+        const hex = `#${c.rgba
+            .slice(0, 3)
+            .map((n) => Math.round(n).toString(16).padStart(2, '0'))
+            .join('')}`.toUpperCase();
+        named.set(c['label-value'], { ...named.get(c['label-value']), color: hex });
+    }
+    if (!named.size)
+        return labelClasses(undefined);
+    const classHierarchy = [];
+    const seen = new Set();
+    for (const [value, { name, color }] of named) {
+        const cls = name ?? `label ${value}`;
+        // One class per name: an instance segmentation names many values alike.
+        if (!seen.has(cls))
+            classHierarchy.push({ name: cls, ...(color ? { color } : {}), value });
+        seen.add(cls);
+    }
+    const labels = Object.fromEntries([...named].map(([v, { name }]) => [v, name ?? `label ${v}`]));
+    return labelClasses({ classHierarchy, labels });
+}
+function unitToMicrons(unit) {
+    switch (unit?.toLowerCase()) {
+        case 'nanometer':
+            return 1e-3;
+        case 'millimeter':
+            return 1e3;
+        case 'centimeter':
+            return 1e4;
+        case 'meter':
+            return 1e6;
+        default:
+            return 1; // micrometer, or none said
+    }
+}
+/** A path relative to the store, '/'-separated, without a leading './'. */
+function norm(name) {
+    return name.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function join(dir, name) {
+    return dir ? `${dir}/${name}` : name;
+}
+
+const EOCD = 0x06054b50;
+const ZIP64_LOCATOR = 0x07064b50;
+const ZIP64_EOCD = 0x06064b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+const U32 = 0xffffffff;
+/** Whether a file name is a zip archive. */
+function isZipName(name) {
+    return /\.zip$/i.test(name);
+}
+/** The members of the archive in `bytes` (directories and macOS metadata left out). */
+function readZip(bytes, inflateRaw = platformInflateRaw) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const eocd = findEocd(view);
+    let count = view.getUint16(eocd + 10, true);
+    let dirOffset = view.getUint32(eocd + 16, true);
+    if (count === 0xffff || dirOffset === U32) {
+        const locator = eocd - 20;
+        if (locator < 0 || view.getUint32(locator, true) !== ZIP64_LOCATOR)
+            throw new Error('zip: ZIP64 locator missing');
+        const z64 = num(view, locator + 8);
+        if (view.getUint32(z64, true) !== ZIP64_EOCD)
+            throw new Error('zip: ZIP64 directory end missing');
+        count = num(view, z64 + 32);
+        dirOffset = num(view, z64 + 48);
+    }
+    const entries = [];
+    let at = dirOffset;
+    for (let i = 0; i < count; i++) {
+        if (view.getUint32(at, true) !== CENTRAL)
+            throw new Error('zip: bad central directory');
+        const flags = view.getUint16(at + 8, true);
+        const method = view.getUint16(at + 10, true);
+        const crc = view.getUint32(at + 16, true);
+        let compressed = view.getUint32(at + 20, true);
+        let size = view.getUint32(at + 24, true);
+        const nameLen = view.getUint16(at + 28, true);
+        const extraLen = view.getUint16(at + 30, true);
+        const commentLen = view.getUint16(at + 32, true);
+        let local = view.getUint32(at + 42, true);
+        const nameBytes = bytes.subarray(at + 46, at + 46 + nameLen);
+        const name = (flags & 0x800 ? new TextDecoder() : new TextDecoder('latin1'))
+            .decode(nameBytes)
+            .replace(/\\/g, '/');
+        // ZIP64: the 32-bit fields that overflowed are in the extra field, in this order.
+        let x = at + 46 + nameLen;
+        const extraEnd = x + extraLen;
+        while (x + 4 <= extraEnd) {
+            const id = view.getUint16(x, true);
+            const len = view.getUint16(x + 2, true);
+            if (id === 0x0001) {
+                let p = x + 4;
+                if (size === U32)
+                    ((size = num(view, p)), (p += 8));
+                if (compressed === U32)
+                    ((compressed = num(view, p)), (p += 8));
+                if (local === U32)
+                    local = num(view, p);
+            }
+            x += 4 + len;
+        }
+        at = extraEnd + commentLen;
+        if (name.endsWith('/') || /(^|\/)__MACOSX\//.test(name) || /(^|\/)\.DS_Store$/.test(name))
+            continue;
+        const entry = { flags, method, crc, compressed, size, local };
+        entries.push({ name, size, bytes: () => readMember(bytes, view, name, entry, inflateRaw) });
+    }
+    return entries;
+}
+/**
+ * `files` with every `.zip` among them replaced by its members, named by their paths in it (a
+ * single top folder the archive wraps everything in is kept, as a folder pick would keep it).
+ */
+async function expandZips(files, inflateRaw) {
+    const out = [];
+    for (const file of files) {
+        if (!isZipName(file.name)) {
+            out.push(file);
+            continue;
+        }
+        for (const entry of readZip(await file.bytes(), inflateRaw)) {
+            out.push({
+                name: entry.name,
+                bytes: () => entry.bytes(),
+                text: async () => new TextDecoder().decode(await entry.bytes()),
+            });
+        }
+    }
+    return out;
+}
+async function readMember(bytes, view, name, m, inflateRaw) {
+    if (m.flags & 0x1)
+        throw new Error(`zip: ${name} is encrypted`);
+    if (view.getUint32(m.local, true) !== LOCAL)
+        throw new Error(`zip: ${name}: bad local header`);
+    const start = m.local + 30 + view.getUint16(m.local + 26, true) + view.getUint16(m.local + 28, true);
+    const raw = bytes.subarray(start, start + m.compressed);
+    if (raw.length !== m.compressed)
+        throw new Error(`zip: ${name} is truncated`);
+    let out;
+    if (m.method === 0)
+        out = raw;
+    else if (m.method === 8)
+        out = await inflateRaw(raw);
+    else
+        throw new Error(`zip: ${name} uses compression method ${m.method}, not stored or deflate`);
+    if (out.length !== m.size)
+        throw new Error(`zip: ${name} is ${out.length} bytes, expected ${m.size}`);
+    if (crc32(out) !== m.crc)
+        throw new Error(`zip: ${name} fails its CRC check`);
+    return out;
+}
+/** The end-of-central-directory record: the last one, within the 64 KiB a comment may take. */
+function findEocd(view) {
+    const stop = Math.max(0, view.byteLength - 22 - 0xffff);
+    for (let at = view.byteLength - 22; at >= stop; at--) {
+        if (view.getUint32(at, true) === EOCD)
+            return at;
+    }
+    throw new Error('zip: not a zip archive (no central directory)');
+}
+/** A little-endian u64 that fits a double (archives under 8 PB). */
+function num(view, at) {
+    return view.getUint32(at, true) + view.getUint32(at + 4, true) * 0x100000000;
+}
+let crcTable = null;
+/** CRC-32 (IEEE), as zip records it. */
+function crc32(data) {
+    if (!crcTable) {
+        crcTable = new Uint32Array(256);
+        for (let n = 0; n < 256; n++) {
+            let c = n;
+            for (let k = 0; k < 8; k++)
+                c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            crcTable[n] = c >>> 0;
+        }
+    }
+    let c = 0xffffffff;
+    for (let i = 0; i < data.length; i++)
+        c = crcTable[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+async function platformInflateRaw(bytes) {
+    if (typeof DecompressionStream === 'undefined')
+        throw new Error('zip: deflated members need DecompressionStream');
+    let inflater;
+    try {
+        // Compression Streams' raw DEFLATE (Chrome 103, Firefox 113, Safari 16.4 on).
+        inflater = new DecompressionStream('deflate-raw');
+    }
+    catch {
+        throw new Error('zip: this browser cannot inflate zip members (no DecompressionStream "deflate-raw")');
+    }
+    const stream = new Blob([bytes]).stream().pipeThrough(inflater);
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/**
+ * Annotations opened by themselves, with no image under them: a label volume (`.nii`, `.nii.gz`,
+ * `.nrrd`, with the ontology JSON chosen with it), an OME-Zarr store's label image, a folder of
+ * per-slice GeoJSON (with its `regionset.json`), one GeoJSON (z-indexed by `geometry.plane.z` or
+ * not), or a `.zip` of any of these.
+ *
+ * {@link openAnnotations} builds the image they are shown on, which every view takes as it takes
+ * any other (OpenSeadragon, napari, Plotly; a stack when there are several slices; the Volume and
+ * Isosurface views and their 3D region surfaces): a label volume's slices in gray levels, its
+ * regions filled over them in their classes' colours, else a blank stack the size of the regions.
+ * The image carries the annotations as its own region sources, one per slice
+ * ({@link IImageInfo.regionSlices}), traced or parsed the first time a slice is shown.
+ * The host publishes it as it publishes any image, and disposes it when another replaces it.
+ *
+ * {@link readAnnotationSlices} is the part the Region Editor's import shares: the sources, by slice.
+ */
+/** The longest side an image built for annotations may have: OpenSeadragon's non-tiled limit. */
+const ANNOTATION_IMAGE_MAX_DIM = 8192;
+/**
+ * The annotations among `files` (zips expanded), as one region source per slice; null when there
+ * are none to read. A label image's slices are traced, and a GeoJSON parsed, when the slice is
+ * first shown.
+ */
+async function readAnnotationSlices(chosen, decoders = {}) {
+    const files = await expandZips(chosen, decoders.inflateRaw);
+    const openGeoJson = decoders.openGeoJson ?? ((text) => openGeoJsonRegionSource(text));
+    if (hasZarrMetadata(files)) {
+        const zarr = await readOmeZarrLabels(files, decoders.inflate);
+        if (!zarr)
+            throw new Error('The zarr store has no label image (an OME-Zarr labels/ group).');
+        return labelSlices('labels', zarr.name, zarr.stack, styled(zarr.classes, decoders), openGeoJson);
+    }
+    const plan = planRegionImport(files);
+    if (!plan)
+        return null;
+    if (plan.kind === 'volume') {
+        const volume = await readLabelVolume(plan.volume.name, await plan.volume.bytes(), decoders.gunzip);
+        const classes = labelClasses(plan.ontology ? JSON.parse(await plan.ontology.text()) : undefined);
+        return labelSlices('labels', stem(plan.volume.name), stackOf(volume), styled(classes, decoders), openGeoJson);
+    }
+    if (plan.kind === 'folder') {
+        const regionSet = plan.regionSet ? JSON.parse(await plan.regionSet.text()) : null;
+        const openers = new Map();
+        plan.slices.forEach((file, z) => openers.set(z, async () => openGeoJson(await folderSliceGeoJson(file, regionSet))));
+        const folder = plan.slices[0].name.split('/').slice(-2, -1)[0] || 'regions';
+        return {
+            kind: 'folder',
+            name: folder,
+            slices: plan.slices.length,
+            openers,
+            summary: `${plan.slices.length} slice files`,
+        };
+    }
+    const slices = splitByPlane(await plan.file.text());
+    const openers = new Map();
+    slices.forEach((text, z) => openers.set(z, () => openGeoJson(text)));
+    return {
+        kind: 'single',
+        name: stem(plan.file.name),
+        slices: slices.length,
+        openers,
+        summary: slices.length > 1 ? `${slices.length} slices` : 'one plane',
+    };
+}
+let opened = 0;
+/**
+ * The image `files`' annotations are shown on by themselves (see the module comment). Throws when
+ * there are none, or when their regions span more than {@link ANNOTATION_IMAGE_MAX_DIM} pixels
+ * (they are then imported onto the image they were drawn on).
+ */
+async function openAnnotations(files, decoders = {}) {
+    const set = await readAnnotationSlices(files, { outlineLabels: true, ...decoders });
+    if (!set) {
+        throw new Error('Choose a label volume (.nii, .nii.gz, .nrrd, with its ontology JSON), an OME-Zarr store, ' +
+            'GeoJSON files or a folder of them, or a .zip of any of these.');
+    }
+    let urls = [];
+    let width;
+    let height;
+    let openers = set.openers;
+    // Releases the sources measuring opened that the store has not taken (none for a label image).
+    let release = () => undefined;
+    try {
+        if (set.labels && set.size) {
+            [width, height] = set.size;
+            checkSize(width, height);
+            urls = await labelSliceUrls(set.labels.stack, set.labels.classes);
+        }
+        else {
+            // Regions alone: a blank stack as large as they reach, measured on the sources (kept open
+            // for their slices, so each is parsed once).
+            const measured = await measure(set.openers);
+            openers = measured.openers;
+            release = measured.release;
+            [width, height] = measured.size;
+            checkSize(width, height);
+            const png = encode({ width, height, data: new Uint8Array(width * height), channels: 1, depth: 8 });
+            const blank = new Blob([png], { type: 'image/png' });
+            urls = Array.from({ length: set.slices }, () => URL.createObjectURL(blank));
+        }
+    }
+    catch (err) {
+        urls.forEach((u) => URL.revokeObjectURL(u));
+        release();
+        throw err;
+    }
+    const [mx, my, mz] = set.spacing ?? [];
+    const isStack = set.slices > 1;
+    const info = {
+        isGrayscale: true,
+        trueImageSize: [width, height],
+        urls,
+        isStack,
+        showStack: false,
+        scaleRatio: true,
+        // Unique: the slice cache keys on the name, and two opened sets must not share slices.
+        fileName: `${set.name} · annotations [${++opened}]`,
+        imageMeta: [
+            {
+                channelCount: 1,
+                rgbChannels: 1,
+                x: width,
+                y: height,
+                z: set.slices,
+                mppX: mx ?? null,
+                mppY: my ?? null,
+                ...(mz != null ? { mppZ: mz } : {}),
+            },
+        ],
+        tiled: false,
+        // Open mid-stack: an atlas's first and last sections are mostly empty.
+        initialZIndex: isStack ? set.slices >> 1 : undefined,
+        regionSlices: openers,
+    };
+    return {
+        info,
+        summary: `${set.summary}, ${width} × ${height}`,
+        dispose: () => {
+            urls.forEach((u) => URL.revokeObjectURL(u));
+            release();
+        },
+    };
+}
+function labelSlices(kind, name, stack, classes, openGeoJson) {
+    const openers = new Map();
+    for (let z = 0; z < stack.slices; z++) {
+        openers.set(z, async () => openGeoJson(labelSliceGeoJson(oneSlice(stack, await stack.labels(z)), 0, classes)));
+    }
+    return {
+        kind,
+        name,
+        slices: stack.slices,
+        openers,
+        labels: { stack, classes },
+        size: [stack.width, stack.height],
+        ...(stack.spacing ? { spacing: stack.spacing } : {}),
+        summary: `${stack.slices} slice${stack.slices === 1 ? '' : 's'} of ${stack.width} × ${stack.height}`,
+    };
+}
+/** `classes`, with the atlas look when asked for and they name no style of their own. */
+function styled(classes, decoders) {
+    return decoders.outlineLabels && !classes.style ? { ...classes, style: ATLAS_STYLE } : classes;
+}
+/** A label volume as a stack read on demand. */
+function stackOf(volume) {
+    return {
+        width: volume.width,
+        height: volume.height,
+        slices: volume.slices,
+        ...(volume.spacing ? { spacing: volume.spacing } : {}),
+        labels: async (z) => volume.sliceLabels(z),
+    };
+}
+/** One slice's labels as the one-slice volume the tracer reads. */
+function oneSlice(stack, labels) {
+    return { format: 'nrrd', width: stack.width, height: stack.height, slices: 1, sliceLabels: () => labels };
+}
+/**
+ * Every slice as a grayscale PNG blob URL, each label at its class colour's luminance (never 0),
+ * background black. Grayscale, not colour: the Volume and Isosurface views take a grayscale stack,
+ * and the colour is the regions' own, filled over it in their classes' colours (the atlas look).
+ */
+async function labelSliceUrls(stack, classes) {
+    const levels = new Map();
+    const levelOf = (v) => {
+        let l = levels.get(v);
+        if (l === undefined) {
+            const hex = classes.classOf(v).color;
+            const [r, g, b] = [1, 3, 5].map((o) => parseInt(hex.slice(o, o + 2), 16));
+            l = Math.max(1, Math.round(0.299 * r + 0.587 * g + 0.114 * b));
+            levels.set(v, l);
+        }
+        return l;
+    };
+    const urls = [];
+    const gray = new Uint8Array(stack.width * stack.height);
+    for (let z = 0; z < stack.slices; z++) {
+        const labels = await stack.labels(z);
+        for (let i = 0; i < labels.length; i++)
+            gray[i] = labels[i] ? levelOf(labels[i]) : 0;
+        const png = encode({ width: stack.width, height: stack.height, data: gray, channels: 1, depth: 8 });
+        urls.push(URL.createObjectURL(new Blob([png], { type: 'image/png' })));
+    }
+    return urls;
+}
+/**
+ * Open every slice's source to learn how far the regions reach (the image is as large, from the
+ * origin, as region coordinates are image pixels). Each opener then hands its already-open source
+ * over the first time (the region store owns it from then on) and opens anew after. `release`
+ * disposes the sources not handed over yet; they are released here when measuring fails.
+ */
+async function measure(openers) {
+    // Sources opened here and not yet handed to the store: theirs to release until then.
+    const held = new Map();
+    const release = () => {
+        for (const source of held.values())
+            source.dispose();
+        held.clear();
+    };
+    let x1 = 0;
+    let y1 = 0;
+    try {
+        for (const [z, open] of openers) {
+            const source = await open();
+            held.set(z, source);
+            const bounds = source.info.bounds;
+            if (bounds) {
+                x1 = Math.max(x1, bounds[2]);
+                y1 = Math.max(y1, bounds[3]);
+            }
+        }
+        if (!(x1 > 0 && y1 > 0))
+            throw new Error('The regions have no extent to show.');
+    }
+    catch (err) {
+        release();
+        throw err;
+    }
+    const reused = new Map();
+    for (const [z, open] of openers) {
+        reused.set(z, () => {
+            const first = held.get(z);
+            if (!first)
+                return open();
+            held.delete(z);
+            return Promise.resolve(first);
+        });
+    }
+    return { openers: reused, size: [Math.ceil(x1), Math.ceil(y1)], release };
+}
+function checkSize(width, height) {
+    if (Math.max(width, height) > ANNOTATION_IMAGE_MAX_DIM) {
+        throw new Error(`The annotations span ${width} × ${height} pixels, more than ${ANNOTATION_IMAGE_MAX_DIM} on a side: ` +
+            'open the image they were drawn on, and import them onto it from the Region Editor.');
+    }
+}
+/**
+ * One GeoJSON's slices: a collection whose features name planes (`geometry.plane.z`) split into
+ * one collection per plane, each keeping the set's class tree and style, its features moved to
+ * plane 0 (a slice's source shows plane 0); any other GeoJSON is one slice as it is.
+ */
+function splitByPlane(text) {
+    const doc = JSON.parse(text);
+    const features = doc.type === 'FeatureCollection' ? (doc.features ?? []) : [];
+    const zOf = (f) => Math.max(0, Math.floor(f.geometry?.plane?.z ?? 0));
+    const last = features.reduce((m, f) => Math.max(m, zOf(f)), 0);
+    if (last === 0)
+        return [text];
+    const slices = Array.from({ length: last + 1 }, () => []);
+    for (const f of features) {
+        const z = zOf(f);
+        const geometry = f.geometry ? { ...f.geometry } : f.geometry;
+        if (geometry)
+            delete geometry.plane;
+        slices[z].push({ ...f, geometry });
+    }
+    return slices.map((list) => JSON.stringify({ ...doc, features: list }));
+}
+function stem(name) {
+    return (name.split('/').pop() ?? name).replace(/\.(nii\.gz|nii|nrrd|geojson|json|zip)$/i, '');
+}
+
 /**
  * The largest bbox (in pixels) {@link rasterizePolygon} allocates before it
  * falls back to clipping at the window. Also the cap the wand/brush use to
@@ -9510,7 +10399,7 @@ function frameToRgba(cached, frameIndex) {
 /** Lazy-import so onnxruntime-web is never pulled into unit tests or the
  *  initial bundle — only when segmentation actually runs. */
 const onnxSessionFactory = async () => {
-    const { OnnxSamSession } = await import('./jax-data-science-sci-image-visualizer-onnx-sam-session-DEDSm_NL.mjs');
+    const { OnnxSamSession } = await import('./jax-data-science-sci-image-visualizer-onnx-sam-session-CvadfzjS.mjs');
     return new OnnxSamSession();
 };
 /** Thrown inside a load that a model switch superseded. */
@@ -10449,6 +11338,21 @@ function applyImageRois(info, target, z, minSourceChars = REGION_SOURCE_MIN_CHAR
     const load = (loads.get(target) ?? 0) + 1;
     loads.set(target, load);
     const asSource = (json) => !!attach && !!json && json.length >= minSourceChars;
+    if (info.regionSlices && attach) {
+        // An image built from annotations: its regions are its own sources, one per slice.
+        if (info.isStack) {
+            target.enterStackMode(new Map(), z, 'per-slice-file');
+            for (const [s, open] of info.regionSlices)
+                attach(open, { slice: s });
+            return;
+        }
+        target.setRegions([]);
+        target.resetUndoHistory();
+        const first = info.regionSlices.get(0) ?? info.regionSlices.values().next().value;
+        if (first)
+            attach(first, { slice: 0 });
+        return;
+    }
     if (info.isStack && info.tiled === false) {
         const perSlice = info.roiJsonStrs;
         const sliceCount = info.urls?.length ?? perSlice?.length ?? 0;
@@ -15908,53 +16812,47 @@ class RegionEditorComponent {
         });
     }
     /**
-     * Import `files` (see planRegionImport): one GeoJSON file as before; a label volume as one
-     * region source per slice, traced from it the first time the slice is shown, its classes named
-     * (and treed) by the ontology chosen with it; a folder as one source per slice file. Either
-     * replaces the regions and sources of every slice.
+     * Import `files`: one GeoJSON file as before (its regions, editable); anything else (see
+     * readAnnotationSlices) as one region source per slice, replacing the regions and sources of
+     * every slice: a label volume or an OME-Zarr label image traced the first time a slice is shown,
+     * its classes named (and treed) by its ontology; a folder as one source per slice file; a
+     * z-indexed GeoJSON one per plane; a zip of any of these.
      */
     async importRegionFiles(files) {
-        const plan = planRegionImport(files);
-        if (!plan) {
-            this.importFailed(new Error('Choose a GeoJSON file, a folder of GeoJSON files, or a .nii, .nii.gz or .nrrd label volume.'));
-            return;
-        }
-        if (plan.kind === 'single') {
-            await this.applyImportedRois(await plan.file.text());
-            return;
-        }
-        const attach = this.regionApi.importSliceRegionSources?.bind(this.regionApi);
-        if (!attach) {
-            this.importFailed(new Error('This viewer cannot hold region sources.'));
-            return;
-        }
-        // Taken before the files are read: decoding a volume takes a while, and the import must land
-        // on the image it was started for, not on one shown meanwhile.
-        const ticket = this.regionApi.regionImportTicket?.();
+        // Every step, reading the files included, reports its failure here rather than rejecting:
+        // the inputs call this without waiting on it.
         try {
-            const openers = new Map();
-            let summary;
-            if (plan.kind === 'volume') {
-                const volume = await readLabelVolume(plan.volume.name, await plan.volume.bytes());
-                const classes = labelClasses(plan.ontology ? JSON.parse(await plan.ontology.text()) : undefined);
-                for (let z = 0; z < volume.slices; z++) {
-                    openers.set(z, () => openGeoJsonRegionSource(labelSliceGeoJson(volume, z, classes)));
+            const plan = files.some((f) => isZipName(f.name)) ? null : planRegionImport(files);
+            if (plan?.kind === 'single') {
+                const text = await plan.file.text();
+                if (onePlane(text)) {
+                    await this.applyImportedRois(text);
+                    return;
                 }
-                summary = `${volume.slices} slices of ${volume.width} × ${volume.height}`;
-                this.warnIfSizeDiffers(volume.width, volume.height);
             }
-            else {
-                const regionSet = plan.regionSet ? JSON.parse(await plan.regionSet.text()) : null;
-                plan.slices.forEach((file, z) => openers.set(z, async () => openGeoJsonRegionSource(await folderSliceGeoJson(file, regionSet))));
-                summary = `${plan.slices.length} slice files`;
+            const attach = this.regionApi.importSliceRegionSources?.bind(this.regionApi);
+            if (!attach) {
+                this.importFailed(new Error('This viewer cannot hold region sources.'));
+                return;
+            }
+            // Taken before the files are read: decoding a volume takes a while, and the import must land
+            // on the image it was started for, not on one shown meanwhile.
+            const ticket = this.regionApi.regionImportTicket?.();
+            const set = await readAnnotationSlices(files);
+            if (!set) {
+                this.importFailed(new Error('Choose a GeoJSON file, a folder of GeoJSON files, a .nii, .nii.gz or .nrrd label volume, ' +
+                    'an OME-Zarr store, or a .zip of any of these.'));
+                return;
             }
-            const attached = attach(openers, ticket);
+            if (set.size)
+                this.warnIfSizeDiffers(set.size[0], set.size[1]);
+            const attached = attach(set.openers, ticket);
             if (attached === null) {
                 this.importStale();
                 return;
             }
             this.afterSourceImport();
-            this.toast('success', 'Regions imported', `${summary}; ${attached} slice${attached === 1 ? '' : 's'} annotated.`);
+            this.toast('success', 'Regions imported', `${set.summary}; ${attached} slice${attached === 1 ? '' : 's'} annotated.`);
         }
         catch (err) {
             this.importFailed(err);
@@ -16289,6 +17187,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.9", ngImpor
             }], active: [{
                 type: Input
             }] } });
+/**
+ * Whether one GeoJSON file holds a single plane (its regions imported as they always were). One
+ * that does not parse is taken as one too, so the regions import reports it as it always has.
+ */
+function onePlane(text) {
+    try {
+        return splitByPlane(text).length === 1;
+    }
+    catch {
+        return true;
+    }
+}
 
 /**
  * Shared intensity helpers (refactoring plan, Step 5). The two backends use
@@ -40407,6 +41317,16 @@ class VolumeRegionMeshes {
             this.remove(key, e.layer);
         this.wanted = [];
     }
+    /**
+     * The volume the surfaces sat in is gone (or no longer theirs): take every surface down, keeping
+     * the meshes wanted, so they come back when a frame is set again.
+     */
+    clearFrame() {
+        this.frame = null;
+        for (const [key, e] of [...this.layers])
+            this.remove(key, e.layer);
+        this.viewer.requestRender();
+    }
     sync() {
         const keep = new Map(this.wanted.map((m) => [m.key, m]));
         for (const [key, e] of [...this.layers]) {
@@ -44725,8 +45645,13 @@ function slabAt(dataset, slice) {
  * shape while keeping the selection. The first 3D layer added frames the camera (`fit3d: 'once'`).
  */
 class Spatial3dScene extends SpatialSceneBase {
-    constructor(ctx, session) {
+    /**
+     * @param info the image plotted with the cloud: the reference volume's stack (the 2D view's
+     *        image, see showVolumeAsImage) when the dataset has a volume, which the regions are on
+     */
+    constructor(ctx, session, info) {
         super(ctx, session, true);
+        this.info = info;
         /** The 3D point cloud. One layer: selection is a per-point alpha on it, not a second. */
         this.points = null;
         this.layerKey = null;
@@ -44768,9 +45693,64 @@ class Spatial3dScene extends SpatialSceneBase {
          *  one; a rebuild that leaves the key alone lets it finish. */
         this.densityLoads = new Supersede();
         this.geneMapLoads = new Supersede();
+        /** Whether the reference volume lets every region surface through (see setRegionsThroughVolume). */
+        this.regionsThrough = false;
         /** The store's invert setting, which the density volumes follow (no other subscription of
          *  this scene carries it). */
         this.invertSub = null;
+        this.regionMeshes = new VolumeRegionMeshes(ctx.viewer);
+    }
+    /** Show these region reconstructions with the cloud (replacing the ones shown). */
+    setRegionMeshes(meshes) {
+        this.regionMeshes.set(meshes);
+    }
+    setRegionHighlight(keys) {
+        this.regionMeshes.setHighlight(keys);
+    }
+    setRegionHidden(keys) {
+        this.regionMeshes.setHidden(keys);
+    }
+    /** As the Volume view: the reference volume hides the surfaces behind what it shows, or none. */
+    setRegionsThroughVolume(through) {
+        this.regionsThrough = through;
+        if (this.volume)
+            this.volume.blending = through ? 'translucent_no_depth' : 'translucent';
+        this.ctx.viewer.requestRender();
+    }
+    /**
+     * Place the region surfaces in the reference volume's box, as the Volume view places them in its
+     * own: image pixel (x, y) is voxel (x, y), slice k is voxel plane k, and the box is the volume's
+     * voxels times its voxel size, centred on the origin as napari centres the volume (and the cloud
+     * is offset to sit in it). Only when the plotted image IS that volume's stack: regions drawn on
+     * another image (a tissue image) have no place in it, and are not shown - nor are surfaces
+     * placed in a volume this one replaced.
+     */
+    placeRegionMeshes(dataset) {
+        const meta = dataset.volume;
+        if (!meta || !this.isVolumeStack(meta)) {
+            this.regionMeshes.clearFrame();
+            return;
+        }
+        const [vx, vy, vz] = meta.voxelSize;
+        this.regionMeshes.setFrame({
+            size: [meta.width, meta.height, meta.depth],
+            world: [meta.width * vx, meta.height * vy, meta.depth * vz],
+        });
+    }
+    /**
+     * Image px per voxel of the volume the surfaces sit in: 1, the reference volume being the stack's
+     * own voxels, as the Volume view's is at full resolution, so both reconstruct a class alike (and
+     * share its cached surface). Null while there is no volume stack to place them in.
+     */
+    voxelStep() {
+        const meta = this.session.latest?.[0]?.volume;
+        return this.volume && meta && this.isVolumeStack(meta) ? 1 : null;
+    }
+    /** Whether the plotted image is the reference volume's stack: its size and slice count. */
+    isVolumeStack(meta) {
+        const info = this.info;
+        const [w, h] = info?.trueImageSize ?? [0, 0];
+        return !!info?.isStack && w === meta.width && h === meta.height && (info.urls?.length ?? 0) === meta.depth;
     }
     async mount() {
         // Before the spatial subscription, so the first build already reads the current value.
@@ -44821,6 +45801,7 @@ class Spatial3dScene extends SpatialSceneBase {
         return out;
     }
     dispose() {
+        this.regionMeshes.clear();
         this.disposeSpatial();
         this.invertSub?.unsubscribe();
         this.invertSub = null;
@@ -45356,6 +46337,8 @@ class Spatial3dScene extends SpatialSceneBase {
             this.volume = null;
             this.volumeKey = null;
         }
+        // The surfaces sat in the volume just removed (or there was none): down until one is placed.
+        this.regionMeshes.clearFrame();
         this.origin = [0, 0, 0];
         if (!meta || !port?.getVolume)
             return;
@@ -45382,14 +46365,18 @@ class Spatial3dScene extends SpatialSceneBase {
             opacity: view.volumeOpacity,
             voxelSize: [vx, vy, vz],
         });
+        if (this.regionsThrough)
+            this.volume.blending = 'translucent_no_depth';
         // Half the box, negated: the observations' origin is the box's near corner,
         // and the box is centred on the world origin.
         this.origin = [-(meta.width * vx) / 2, -(meta.height * vy) / 2, -(meta.depth * vz) / 2];
+        this.placeRegionMeshes(dataset);
         // Force a geometry rebuild: the offset changed, so cached positions are stale.
         this.layerKey = null;
     }
     /** Drop every layer of the cloud (the dataset went away, or has no z). */
     removeLayers(viewer) {
+        this.regionMeshes.clearFrame();
         for (const layer of [this.points, this.volume, this.geneMapLayer, ...this.densityLayers]) {
             if (layer)
                 viewer.layers.remove(layer);
@@ -45733,7 +46720,7 @@ class NapariVisualizerService extends BaseStoreVisualizer {
     /** The scene a plot type mounts. */
     createScene(plotType, ctx, info, noImage) {
         if (isSpatialOmics3d(plotType))
-            return new Spatial3dScene(ctx, this.spatial);
+            return new Spatial3dScene(ctx, this.spatial, info);
         if (isSpatialOmics(plotType))
             return new Spatial2dScene(ctx, this.spatial, noImage);
         if (isNapariScatter(plotType))
@@ -46654,8 +47641,14 @@ class RoutingVisualizerService {
         this.napariFellBack = false;
         /** The div the backends render into (every backend shares it); '' before the first plot. */
         this.plotDiv = '';
-        /** Whether a napari volume view is the current plot type. */
+        /**
+         * Whether regions can be shown in 3D on screen: a napari volume (or isosurface) view, or the 3D
+         * spatial cloud over a stack image (its reference volume's, see showVolumeAsImage). Both draw the
+         * region reconstructions the same way (VolumeRegionMeshes), in the volume's box.
+         */
         this.volumeView$ = new BehaviorSubject(false);
+        /** Whether a napari volume (or isosurface) view is the current plot type: the slice pane's. */
+        this.imageVolumeView = false;
         /** Whether the volume view's slice pane is wanted (see {@link setSliceEditor}). */
         this.sliceEditor$ = new BehaviorSubject(false);
         /** Whether the volume view draws the region reconstructions through the volume. */
@@ -46881,13 +47874,13 @@ class RoutingVisualizerService {
     }
     plot(plotDiv, imageLoaded, imageInfo, screenHeight, plotType, inPlace) {
         this.currentPlotType = plotType;
-        this.volumeView$.next(isNapariVolume(plotType) || isNapariIsosurface(plotType));
         this.plottedFileName = imageInfo?.fileName;
         this.plottedInfo = imageInfo ?? null;
         this.plottedHeight = screenHeight;
+        this.updateVolumeView(plotType);
         // The slice pane belongs to the volume view: another plot type takes it down (OSD may be
         // about to draw the main view, which must not find the pane's viewer still mounted).
-        if (!this.volumeView$.value)
+        if (!this.imageVolumeView)
             this.unmountSlice();
         // Region surfaces belong to the image they were built from: another image drops them.
         if (this.classes3d$.value.length && this.plottedFileName !== this.classes3dImage)
@@ -46910,7 +47903,7 @@ class RoutingVisualizerService {
         }
         this.lastRendered = next;
         const plotted = next.plot(plotDiv, imageLoaded, imageInfo, screenHeight, plotType, inPlace);
-        if (!this.sliceDiv || !this.volumeView$.value)
+        if (!this.sliceDiv || !this.imageVolumeView)
             return plotted;
         // The split volume view: the slice pane follows the image (a new one, or its sharper pass).
         return plotted.then((ok) => {
@@ -46942,7 +47935,7 @@ class RoutingVisualizerService {
     async mountSlice(inPlace) {
         const div = this.sliceDiv;
         const info = this.plottedInfo;
-        if (!div || !info?.urls?.length || !this.volumeView$.value)
+        if (!div || !info?.urls?.length || !this.imageVolumeView)
             return false;
         const request = ++this.sliceRequest;
         try {
@@ -47064,7 +48057,7 @@ class RoutingVisualizerService {
     }
     setPlotType(plotType) {
         this.currentPlotType = plotType;
-        this.volumeView$.next(isNapariVolume(plotType) || isNapariIsosurface(plotType));
+        this.updateVolumeView(plotType);
         this.plotly.setPlotType(plotType);
     }
     /** @deprecated Use `getSurface3dControls()`. */
@@ -47367,6 +48360,13 @@ class RoutingVisualizerService {
         this.regionStore.setRegionStyle(patch);
     }
     // ── Regions in 3D: their reconstructions shown in the volume view ─────
+    /** Recompute which 3D view is on screen for `plotType` (see {@link volumeView$}). */
+    updateVolumeView(plotType) {
+        this.imageVolumeView = isNapariVolume(plotType) || isNapariIsosurface(plotType);
+        const regions3d = this.imageVolumeView || (isSpatialOmics3d(plotType) && !!this.plottedInfo?.isStack);
+        // Every plot, as before: the Region Editor drops its per-class volumes on each (a new image).
+        this.volumeView$.next(regions3d);
+    }
     /** Whether a napari volume (or isosurface) view is on screen: regions can be shown in 3D. */
     getVolumeView$() {
         return this.volumeView$.asObservable();
@@ -48026,5 +49026,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.9", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { TOOLBAR_TOOLS as $, ALL_GENES as A, REGION_IO_PORT as B, CANVAS_TOOL_IDS as C, DEFAULT_CATEGORICAL_PALETTE as D, REGION_SOURCE_MIN_CHARS as E, Rectangle as F, Region as G, HexColorPickerComponent as H, IMAGE_STATE_PORT as I, RegionEditorComponent as J, RoutingVisualizerService as K, LUT_COLORS as L, MISSING_COLOR as M, NAPARI_DECIMATE_OPTIONS as N, SEMANTIC_SEGMENTER as O, PLOT_MODE_CONTEXT as P, SPATIAL_DATA_PORT as Q, REGION_EDITOR_API as R, SAM_MODELS as S, SPATIAL_WIRE_VERSION as T, ShapeSelection as U, SpatialChartsComponent as V, SpatialControlsComponent as W, SpatialDataHttpService as X, SpatialSelectionStore as Y, SupersededError as Z, TILE_ACCESS_PORT as _, runDecoder as a, provideVisualization as a$, VISUALIZER as a0, VIZ_ALERT_TOAST_KEY as a1, VIZ_CONFIG as a2, VIZ_TOAST_KEY as a3, ViewerFeature as a4, VisualizationModule as a5, VisualizerComponent as a6, assertManifestVersion as a7, benefitsFromGrouping as a8, buildOmicsTraces as a9, isContinuousColumn as aA, isDialogToolContribution as aB, isEmptyPresetSet as aC, isLabelVolumeName as aD, isLittleEndian as aE, isNapari3d as aF, isNapariIsosurface as aG, isNapariScatter as aH, isNapariScatter3d as aI, isNapariSurface as aJ, isNapariVolume as aK, isSamModelReady as aL, isSpatialOmics as aM, isSpatialOmics3d as aN, isThreeDimensional as aO, labelClasses as aP, labelSliceGeoJson as aQ, lutFor as aR, markerDiameters as aS, maskToIndices as aT, mutedFromSelection as aU, omicsLayout as aV, openGeoJsonRegionSource as aW, openHttpRegionSource as aX, parsePresetSet as aY, planRegionImport as aZ, pointInRing as a_, capabilitiesOf as aa, clearSamModelCache as ab, contrastWindow as ac, contributedPlotTypeOption as ad, countMask as ae, cropImage as af, datasetFromManifest as ag, decodeColumn as ah, decodeCoords as ai, decodeFeatureVector as aj, decodePolygons as ak, decodeRadius as al, defaultPresetSet as am, dialogToolContributions as an, emptySelection as ao, encodeCategorical as ap, encodeContinuous as aq, findColumnMeta as ar, getDefaultSamModelId as as, getPlotTypeDescriptor as at, getSamModel as au, hydrateBounds as av, importFile as aw, isBuiltinPlotType as ax, isCanvasToolId as ay, isCategoricalColumn as az, ALL_TOOLBAR_TOOLS as b, readLabelVolume as b0, rendererOwnsWheel as b1, resolveCategoryColors as b2, selectByCategory as b3, selectInRegions as b4, setDefaultSamModel as b5, setOrtWasmBase as b6, setSamModelUrls as b7, sortToolContributions as b8, visibleToolContributions as b9, CELL_SEGMENTER as c, CHANNEL_HISTOGRAM_API as d, CellposeSegmenterService as e, fetchModel as f, getOrtWasmBase as g, ChannelHistogramComponent as h, DEFAULT_FALLBACK_PALETTE as i, DEFAULT_MUTED_OPACITY as j, DEFAULT_SAM_MODEL_ID as k, DEFAULT_SPATIAL_VIEW as l, INSTANCE_SEGMENTER as m, ImageConverterService as n, MultiPolygon as o, NAPARI_DEFAULT_DECIMATE as p, NO_CATEGORY as q, runEncoder as r, NO_OBSERVATION as s, PLOT_MODE_SESSION as t, PLOT_TYPE_CONTRIBUTIONS as u, PLOT_TYPE_DESCRIPTORS as v, PREFERENCES_PORT as w, PlotType as x, Polygon as y, ProcessingImage as z };
-//# sourceMappingURL=jax-data-science-sci-image-visualizer-jax-data-science-sci-image-visualizer-BELcx0jv.mjs.map
+export { TILE_ACCESS_PORT as $, ALL_GENES as A, ProcessingImage as B, CANVAS_TOOL_IDS as C, DEFAULT_CATEGORICAL_PALETTE as D, REGION_IO_PORT as E, REGION_SOURCE_MIN_CHARS as F, Rectangle as G, HexColorPickerComponent as H, IMAGE_STATE_PORT as I, Region as J, RegionEditorComponent as K, LUT_COLORS as L, MISSING_COLOR as M, NAPARI_DECIMATE_OPTIONS as N, RoutingVisualizerService as O, PLOT_MODE_CONTEXT as P, SEMANTIC_SEGMENTER as Q, REGION_EDITOR_API as R, SAM_MODELS as S, SPATIAL_DATA_PORT as T, SPATIAL_WIRE_VERSION as U, ShapeSelection as V, SpatialChartsComponent as W, SpatialControlsComponent as X, SpatialDataHttpService as Y, SpatialSelectionStore as Z, SupersededError as _, runDecoder as a, openGeoJsonRegionSource as a$, TOOLBAR_TOOLS as a0, VISUALIZER as a1, VIZ_ALERT_TOAST_KEY as a2, VIZ_CONFIG as a3, VIZ_TOAST_KEY as a4, ViewerFeature as a5, VisualizationModule as a6, VisualizerComponent as a7, assertManifestVersion as a8, benefitsFromGrouping as a9, isBuiltinPlotType as aA, isCanvasToolId as aB, isCategoricalColumn as aC, isContinuousColumn as aD, isDialogToolContribution as aE, isEmptyPresetSet as aF, isLabelVolumeName as aG, isLittleEndian as aH, isNapari3d as aI, isNapariIsosurface as aJ, isNapariScatter as aK, isNapariScatter3d as aL, isNapariSurface as aM, isNapariVolume as aN, isSamModelReady as aO, isSpatialOmics as aP, isSpatialOmics3d as aQ, isThreeDimensional as aR, isZipName as aS, labelClasses as aT, labelSliceGeoJson as aU, lutFor as aV, markerDiameters as aW, maskToIndices as aX, mutedFromSelection as aY, omicsLayout as aZ, openAnnotations as a_, buildOmicsTraces as aa, capabilitiesOf as ab, clearSamModelCache as ac, contrastWindow as ad, contributedPlotTypeOption as ae, countMask as af, cropImage as ag, datasetFromManifest as ah, decodeColumn as ai, decodeCoords as aj, decodeFeatureVector as ak, decodePolygons as al, decodeRadius as am, defaultPresetSet as an, dialogToolContributions as ao, emptySelection as ap, encodeCategorical as aq, encodeContinuous as ar, expandZips as as, findColumnMeta as at, getDefaultSamModelId as au, getPlotTypeDescriptor as av, getSamModel as aw, hasZarrMetadata as ax, hydrateBounds as ay, importFile as az, ALL_TOOLBAR_TOOLS as b, openHttpRegionSource as b0, parsePresetSet as b1, planRegionImport as b2, pointInRing as b3, provideVisualization as b4, readAnnotationSlices as b5, readLabelVolume as b6, readOmeZarrLabels as b7, readZip as b8, rendererOwnsWheel as b9, resolveCategoryColors as ba, selectByCategory as bb, selectInRegions as bc, setDefaultSamModel as bd, setOrtWasmBase as be, setSamModelUrls as bf, sortToolContributions as bg, visibleToolContributions as bh, ANNOTATION_IMAGE_MAX_DIM as c, CELL_SEGMENTER as d, CHANNEL_HISTOGRAM_API as e, fetchModel as f, getOrtWasmBase as g, CellposeSegmenterService as h, ChannelHistogramComponent as i, DEFAULT_FALLBACK_PALETTE as j, DEFAULT_MUTED_OPACITY as k, DEFAULT_SAM_MODEL_ID as l, DEFAULT_SPATIAL_VIEW as m, INSTANCE_SEGMENTER as n, ImageConverterService as o, MultiPolygon as p, NAPARI_DEFAULT_DECIMATE as q, runEncoder as r, NO_CATEGORY as s, NO_OBSERVATION as t, PLOT_MODE_SESSION as u, PLOT_TYPE_CONTRIBUTIONS as v, PLOT_TYPE_DESCRIPTORS as w, PREFERENCES_PORT as x, PlotType as y, Polygon as z };
+//# sourceMappingURL=jax-data-science-sci-image-visualizer-jax-data-science-sci-image-visualizer-a68Hw5rw.mjs.map