@fideus-labs/fidnii 0.1.0

package/dist/OMEZarrNVImage.js

@@ -0,0 +1,1799 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+import { NIFTI1 } from "nifti-reader-js";
+import { NVImage, SLICE_TYPE } from "@niivue/niivue";
+import { computeOmeroFromNgffImage } from "@fideus-labs/ngff-zarr/browser";
+import { LRUCache } from "lru-cache";
+import { getBytesPerPixel, getNiftiDataType, parseZarritaDtype, } from "./types.js";
+import { BufferManager } from "./BufferManager.js";
+import { RegionCoalescer } from "./RegionCoalescer.js";
+import { getChunkShape, getVolumeShape, select2DResolution, selectResolution, } from "./ResolutionSelector.js";
+import { alignToChunks, clipPlanesToNiivue, clipPlanesToPixelRegion, createDefaultClipPlanes, MAX_CLIP_PLANES, normalizeVector, validateClipPlanes, } from "./ClipPlanes.js";
+import { affineToNiftiSrows, calculateWorldBounds, createAffineFromNgffImage, } from "./utils/affine.js";
+import { worldToPixel } from "./utils/coordinates.js";
+import { boundsApproxEqual, computeViewportBounds2D, computeViewportBounds3D, } from "./ViewportBounds.js";
+import { OMEZarrNVImageEvent, } from "./events.js";
+const DEFAULT_MAX_PIXELS = 50_000_000;
+const DEFAULT_MAX_CACHE_ENTRIES = 200;
+/**
+ * OMEZarrNVImage extends NVImage to support rendering OME-Zarr images in NiiVue.
+ *
+ * Features:
+ * - Progressive loading: quick preview from lowest resolution, then target resolution
+ * - Arbitrary clip planes defined by point + normal (up to 6)
+ * - Dynamic buffer sizing to match fetched data exactly (no upsampling)
+ * - Request coalescing for efficient chunk fetching
+ * - Automatic metadata updates to reflect OME-Zarr coordinate transforms
+ */
+export class OMEZarrNVImage extends NVImage {
+    /** The OME-Zarr multiscales data */
+    multiscales;
+    /** Maximum number of pixels to use */
+    maxPixels;
+    /** Reference to NiiVue instance */
+    niivue;
+    /** Buffer manager for dynamically-sized pixel data */
+    bufferManager;
+    /** Region coalescer for efficient chunk fetching */
+    coalescer;
+    /** Decoded-chunk cache shared across 3D and 2D slab loads. */
+    _chunkCache;
+    /** Current clip planes in world space */
+    _clipPlanes;
+    /** Target resolution level index (based on maxPixels) */
+    targetLevelIndex;
+    /** Current resolution level index during progressive loading */
+    currentLevelIndex;
+    /** True if currently loading data */
+    isLoading = false;
+    /** Data type of the volume */
+    dtype;
+    /** Full volume bounds in world space */
+    _volumeBounds;
+    /** Current buffer bounds in world space (may differ from full volume when clipped) */
+    _currentBufferBounds;
+    /** Previous clip plane change handler (to restore later) */
+    previousOnClipPlaneChange;
+    /** Debounce delay for clip plane updates (ms) */
+    clipPlaneDebounceMs;
+    /** Timeout handle for debounced clip plane refetch */
+    clipPlaneRefetchTimeout = null;
+    /** Previous clip planes state for direction comparison */
+    _previousClipPlanes = [];
+    /** Previous pixel count at current resolution (for direction comparison) */
+    _previousPixelCount = 0;
+    /** Cached/computed OMERO metadata for visualization (cal_min/cal_max) */
+    _omero;
+    /** Active channel index for OMERO window selection (default: 0) */
+    _activeChannel = 0;
+    /** Resolution level at which OMERO was last computed (to track recomputation) */
+    _omeroComputedForLevel = -1;
+    /** Internal EventTarget for event dispatching (composition pattern) */
+    _eventTarget = new EventTarget();
+    /** Pending populate request (latest wins - replaces any previous pending) */
+    _pendingPopulateRequest = null;
+    /** Current populate trigger (set at start of populateVolume, used by events) */
+    _currentPopulateTrigger = "initial";
+    // ============================================================
+    // Multi-NV / Slab Buffer State
+    // ============================================================
+    /** Attached Niivue instances and their state */
+    _attachedNiivues = new Map();
+    /** Per-slice-type slab buffers (lazily created) */
+    _slabBuffers = new Map();
+    /** Debounce timeout for slab reload per slice type */
+    _slabReloadTimeouts = new Map();
+    // ============================================================
+    // Viewport-Aware Resolution State
+    // ============================================================
+    /** Whether viewport-aware resolution selection is enabled */
+    _viewportAwareEnabled = false;
+    /**
+     * Viewport bounds for the 3D render volume (union of all RENDER/MULTIPLANAR NVs).
+     * Null = full volume, no viewport constraint.
+     */
+    _viewportBounds3D = null;
+    /**
+     * Per-slab viewport bounds (from the NV instance that displays each slab).
+     * Null entry = full volume, no viewport constraint for that slab.
+     */
+    _viewportBoundsPerSlab = new Map();
+    /** Timeout handle for debounced viewport update */
+    _viewportUpdateTimeout = null;
+    /** Per-slab AbortController to cancel in-flight progressive loads */
+    _slabAbortControllers = new Map();
+    // ============================================================
+    // 3D Zoom Override
+    // ============================================================
+    /** Maximum 3D render zoom level for scroll-wheel zoom */
+    _max3DZoom;
+    /** Minimum 3D render zoom level for scroll-wheel zoom */
+    _min3DZoom;
+    /**
+     * Debounce delay for viewport-aware reloads (ms).
+     * Higher than clip plane debounce to avoid excessive reloads during
+     * continuous zoom/pan interactions.
+     */
+    static VIEWPORT_DEBOUNCE_MS = 500;
+    /**
+     * Private constructor. Use OMEZarrNVImage.create() for instantiation.
+     */
+    constructor(options) {
+        // Call NVImage constructor with no data buffer
+        super();
+        this.multiscales = options.multiscales;
+        this.maxPixels = options.maxPixels ?? DEFAULT_MAX_PIXELS;
+        this.niivue = options.niivue;
+        this.clipPlaneDebounceMs = options.clipPlaneDebounceMs ?? 300;
+        // Initialize chunk cache: user-provided > LRU(maxCacheEntries) > disabled
+        const maxEntries = options.maxCacheEntries ?? DEFAULT_MAX_CACHE_ENTRIES;
+        if (options.cache) {
+            this._chunkCache = options.cache;
+        }
+        else if (maxEntries > 0) {
+            this._chunkCache = new LRUCache({ max: maxEntries });
+        }
+        this.coalescer = new RegionCoalescer(this._chunkCache);
+        this._max3DZoom = options.max3DZoom ?? 10.0;
+        this._min3DZoom = options.min3DZoom ?? 0.3;
+        this._viewportAwareEnabled = options.viewportAware ?? true;
+        // Initialize clip planes to empty (full volume visible)
+        this._clipPlanes = createDefaultClipPlanes(this.multiscales);
+        // Get data type from highest resolution image
+        const highResImage = this.multiscales.images[0];
+        this.dtype = parseZarritaDtype(highResImage.data.dtype);
+        // Calculate volume bounds from highest resolution for most accurate bounds
+        const highResAffine = createAffineFromNgffImage(highResImage);
+        const highResShape = getVolumeShape(highResImage);
+        this._volumeBounds = calculateWorldBounds(highResAffine, highResShape);
+        // Initially, buffer bounds = full volume bounds (no clipping yet)
+        this._currentBufferBounds = { ...this._volumeBounds };
+        // Calculate target resolution based on pixel budget
+        const selection = selectResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds);
+        this.targetLevelIndex = selection.levelIndex;
+        this.currentLevelIndex = this.multiscales.images.length - 1;
+        // Create buffer manager (dynamic sizing, no pre-allocation)
+        this.bufferManager = new BufferManager(this.maxPixels, this.dtype);
+        // Initialize NVImage properties with placeholder values
+        // Actual values will be set when data is first loaded
+        this.initializeNVImageProperties();
+    }
+    /**
+     * Create a new OMEZarrNVImage instance.
+     *
+     * By default, the image is automatically added to NiiVue and progressive
+     * loading starts immediately (fire-and-forget). This enables progressive
+     * rendering where each resolution level is displayed as it loads.
+     *
+     * Set `autoLoad: false` for manual control over when loading starts.
+     * Listen to 'populateComplete' event to know when loading finishes.
+     *
+     * @param options - Options including multiscales, niivue reference, and optional maxPixels
+     * @returns Promise resolving to the OMEZarrNVImage instance
+     */
+    static async create(options) {
+        const image = new OMEZarrNVImage(options);
+        // Store and replace the clip plane change handler
+        image.previousOnClipPlaneChange = image.niivue.onClipPlaneChange;
+        image.niivue.onClipPlaneChange = (clipPlane) => {
+            // Call original handler if it exists
+            if (image.previousOnClipPlaneChange) {
+                image.previousOnClipPlaneChange(clipPlane);
+            }
+            // Handle clip plane change
+            image.onNiivueClipPlaneChange(clipPlane);
+        };
+        // Auto-attach the primary NV instance for slice type / location tracking
+        image.attachNiivue(image.niivue);
+        // Auto-load by default (add to NiiVue + start progressive loading)
+        const autoLoad = options.autoLoad ?? true;
+        if (autoLoad) {
+            image.niivue.addVolume(image);
+            void image.populateVolume(); // Fire-and-forget, returns immediately
+        }
+        return image;
+    }
+    /**
+     * Initialize NVImage properties with placeholder values.
+     * Actual values will be set by loadResolutionLevel() after first data fetch.
+     */
+    initializeNVImageProperties() {
+        // Create NIfTI header with placeholder values
+        const hdr = new NIFTI1();
+        this.hdr = hdr;
+        // Placeholder dimensions (will be updated when data loads)
+        hdr.dims = [3, 1, 1, 1, 1, 1, 1, 1];
+        // Set data type
+        hdr.datatypeCode = getNiftiDataType(this.dtype);
+        hdr.numBitsPerVoxel = getBytesPerPixel(this.dtype) * 8;
+        // Placeholder pixel dimensions
+        hdr.pixDims = [1, 1, 1, 1, 0, 0, 0, 0];
+        // Placeholder affine (identity)
+        hdr.affine = [
+            [1, 0, 0, 0],
+            [0, 1, 0, 0],
+            [0, 0, 1, 0],
+            [0, 0, 0, 1],
+        ];
+        hdr.sform_code = 1; // Scanner coordinates
+        // Set name
+        this.name = this.multiscales.metadata?.name ?? "OME-Zarr";
+        // Initialize with empty typed array (will be replaced when data loads)
+        // We need at least 1 element to avoid issues
+        this.img = this.bufferManager.resize([1, 1, 1]);
+        // Set default colormap
+        this._colormap = "gray";
+        this._opacity = 1.0;
+    }
+    /**
+     * Populate the volume with data.
+     *
+     * Loading strategy:
+     * 1. Load lowest resolution first for quick preview (unless skipPreview is true)
+     * 2. Jump directly to target resolution (skip intermediate levels)
+     *
+     * If called while already loading, the request is queued. Only the latest
+     * queued request is kept (latest wins). When a queued request is replaced,
+     * a `loadingSkipped` event is emitted.
+     *
+     * @param skipPreview - If true, skip the preview load (used for clip plane updates)
+     * @param trigger - What triggered this population (default: 'initial')
+     */
+    async populateVolume(skipPreview = false, trigger = "initial") {
+        // If already loading, queue this request (latest wins)
+        if (this.isLoading) {
+            if (this._pendingPopulateRequest !== null) {
+                // Replacing an existing queued request - emit loadingSkipped
+                this._emitEvent("loadingSkipped", {
+                    reason: "queued-replaced",
+                    trigger: this._pendingPopulateRequest.trigger,
+                });
+            }
+            // Queue this request (no event - just queuing)
+            this._pendingPopulateRequest = { skipPreview, trigger };
+            return;
+        }
+        this.isLoading = true;
+        this._currentPopulateTrigger = trigger;
+        this._pendingPopulateRequest = null; // Clear any stale pending request
+        try {
+            const numLevels = this.multiscales.images.length;
+            const lowestLevel = numLevels - 1;
+            // Quick preview from lowest resolution (if different from target and not skipped)
+            if (!skipPreview && lowestLevel !== this.targetLevelIndex) {
+                await this.loadResolutionLevel(lowestLevel, "preview");
+                const prevLevel = this.currentLevelIndex;
+                this.currentLevelIndex = lowestLevel;
+                // Emit resolutionChange for preview load
+                if (prevLevel !== lowestLevel) {
+                    this._emitEvent("resolutionChange", {
+                        currentLevel: this.currentLevelIndex,
+                        targetLevel: this.targetLevelIndex,
+                        previousLevel: prevLevel,
+                        trigger: this._currentPopulateTrigger,
+                    });
+                }
+            }
+            // Final quality at target resolution
+            await this.loadResolutionLevel(this.targetLevelIndex, "target");
+            const prevLevelBeforeTarget = this.currentLevelIndex;
+            this.currentLevelIndex = this.targetLevelIndex;
+            // Emit resolutionChange for target load
+            if (prevLevelBeforeTarget !== this.targetLevelIndex) {
+                this._emitEvent("resolutionChange", {
+                    currentLevel: this.currentLevelIndex,
+                    targetLevel: this.targetLevelIndex,
+                    previousLevel: prevLevelBeforeTarget,
+                    trigger: this._currentPopulateTrigger,
+                });
+            }
+            // Update previous state for direction-aware resolution selection
+            // Always calculate at level 0 for consistent comparison across resolution changes
+            this._previousClipPlanes = this.copyClipPlanes(this._clipPlanes);
+            const referenceImage = this.multiscales.images[0];
+            const region = clipPlanesToPixelRegion(this._clipPlanes, this._volumeBounds, referenceImage);
+            const aligned = alignToChunks(region, referenceImage);
+            this._previousPixelCount = this.calculateAlignedPixelCount(aligned);
+        }
+        finally {
+            this.isLoading = false;
+            this.handlePendingPopulateRequest();
+        }
+    }
+    /**
+     * Process any pending populate request after current load completes.
+     * If no pending request, emits populateComplete.
+     */
+    handlePendingPopulateRequest() {
+        const pending = this._pendingPopulateRequest;
+        if (pending !== null) {
+            this._pendingPopulateRequest = null;
+            // Use void to indicate we're intentionally not awaiting
+            void this.populateVolume(pending.skipPreview, pending.trigger);
+            return;
+        }
+        // No more pending requests - emit populateComplete
+        this._emitEvent("populateComplete", {
+            currentLevel: this.currentLevelIndex,
+            targetLevel: this.targetLevelIndex,
+            trigger: this._currentPopulateTrigger,
+        });
+    }
+    /**
+     * Load data at a specific resolution level.
+     *
+     * With dynamic buffer sizing:
+     * 1. Fetch data for the aligned region
+     * 2. Resize buffer to match fetched data exactly (no upsampling)
+     * 3. Update header with correct dimensions and voxel sizes
+     * 4. Refresh NiiVue
+     *
+     * @param levelIndex - Resolution level index
+     * @param requesterId - ID for request coalescing
+     */
+    async loadResolutionLevel(levelIndex, requesterId) {
+        // Emit loadingStart event
+        this._emitEvent("loadingStart", {
+            levelIndex,
+            trigger: this._currentPopulateTrigger,
+        });
+        const ngffImage = this.multiscales.images[levelIndex];
+        // Get the pixel region for current clip planes (+ 3D viewport bounds if active)
+        const pixelRegion = clipPlanesToPixelRegion(this._clipPlanes, this._volumeBounds, ngffImage, this._viewportBounds3D ?? undefined);
+        const alignedRegion = alignToChunks(pixelRegion, ngffImage);
+        // Calculate the shape of data to fetch
+        const fetchedShape = [
+            alignedRegion.chunkAlignedEnd[0] - alignedRegion.chunkAlignedStart[0],
+            alignedRegion.chunkAlignedEnd[1] - alignedRegion.chunkAlignedStart[1],
+            alignedRegion.chunkAlignedEnd[2] - alignedRegion.chunkAlignedStart[2],
+        ];
+        // Fetch the data
+        const fetchRegion = {
+            start: alignedRegion.chunkAlignedStart,
+            end: alignedRegion.chunkAlignedEnd,
+        };
+        const result = await this.coalescer.fetchRegion(ngffImage, levelIndex, fetchRegion, requesterId);
+        // Resize buffer to match fetched data exactly (no upsampling!)
+        const targetData = this.bufferManager.resize(fetchedShape);
+        // Direct copy of fetched data
+        targetData.set(result.data);
+        // Update this.img to point to the (possibly new) buffer
+        this.img = this.bufferManager.getTypedArray();
+        // Update NVImage header with correct dimensions and transforms
+        this.updateHeaderForRegion(ngffImage, alignedRegion, fetchedShape);
+        // Compute or apply OMERO metadata for cal_min/cal_max
+        await this.ensureOmeroMetadata(ngffImage, levelIndex);
+        // Reset global_min so NiiVue's refreshLayers() re-runs calMinMax() on real data.
+        // Without this, if calMinMax() was previously called on placeholder/empty data
+        // (e.g., when setting colormap before loading), global_min would already be set
+        // and NiiVue would skip recalculating intensity ranges, leaving cal_min/cal_max
+        // at stale values (typically 0/0), causing an all-white render.
+        this.global_min = undefined;
+        // Update NiiVue clip planes
+        this.updateNiivueClipPlanes();
+        // Refresh NiiVue
+        this.niivue.updateGLVolume();
+        // Widen the display window if actual data exceeds the OMERO range.
+        // At higher resolutions, individual bright/dark voxels that were averaged
+        // out at lower resolutions can exceed the OMERO-specified window, causing
+        // clipping artifacts. This preserves the OMERO lower bound but widens the
+        // ceiling to encompass the full data range when needed.
+        this._widenCalRangeIfNeeded(this);
+        // Emit loadingComplete event
+        this._emitEvent("loadingComplete", {
+            levelIndex,
+            trigger: this._currentPopulateTrigger,
+        });
+    }
+    /**
+     * Update NVImage header for a loaded region.
+     *
+     * With dynamic buffer sizing, the buffer dimensions equal the fetched dimensions.
+     * We set pixDims directly from the resolution level's voxel size (no upsampling correction).
+     * The affine translation is adjusted to account for the region offset.
+     *
+     * @param ngffImage - The NgffImage at the current resolution level
+     * @param region - The chunk-aligned region that was loaded
+     * @param fetchedShape - The shape of the fetched data [z, y, x]
+     */
+    updateHeaderForRegion(ngffImage, region, fetchedShape) {
+        if (!this.hdr)
+            return;
+        // Get voxel size from this resolution level (no upsampling adjustment needed!)
+        const scale = ngffImage.scale;
+        const sx = scale.x ?? scale.X ?? 1;
+        const sy = scale.y ?? scale.Y ?? 1;
+        const sz = scale.z ?? scale.Z ?? 1;
+        // Set pixDims directly from resolution's voxel size
+        this.hdr.pixDims = [1, sx, sy, sz, 0, 0, 0, 0];
+        // Set dims to match fetched data (buffer now equals fetched size)
+        // NIfTI dims: [ndim, x, y, z, t, ...]
+        this.hdr.dims = [
+            3,
+            fetchedShape[2],
+            fetchedShape[1],
+            fetchedShape[0],
+            1,
+            1,
+            1,
+            1,
+        ];
+        // Build affine with offset for region start
+        const affine = createAffineFromNgffImage(ngffImage);
+        // Adjust translation for region offset
+        // Buffer pixel [0,0,0] corresponds to source pixel region.chunkAlignedStart
+        const regionStart = region.chunkAlignedStart;
+        // regionStart is [z, y, x], affine translation is [x, y, z] (indices 12, 13, 14)
+        affine[12] += regionStart[2] * sx; // x offset
+        affine[13] += regionStart[1] * sy; // y offset
+        affine[14] += regionStart[0] * sz; // z offset
+        // Update affine in header
+        const srows = affineToNiftiSrows(affine);
+        this.hdr.affine = [
+            srows.srow_x,
+            srows.srow_y,
+            srows.srow_z,
+            [0, 0, 0, 1],
+        ];
+        // Update current buffer bounds
+        // Buffer starts at region.chunkAlignedStart and has extent fetchedShape
+        this._currentBufferBounds = {
+            min: [
+                affine[12], // x offset (world coord of buffer origin)
+                affine[13], // y offset
+                affine[14], // z offset
+            ],
+            max: [
+                affine[12] + fetchedShape[2] * sx,
+                affine[13] + fetchedShape[1] * sy,
+                affine[14] + fetchedShape[0] * sz,
+            ],
+        };
+        // Recalculate RAS orientation
+        this.calculateRAS();
+    }
+    /**
+     * Update NiiVue clip planes from current _clipPlanes.
+     *
+     * Clip planes are converted relative to the CURRENT BUFFER bounds,
+     * not the full volume bounds. This is because NiiVue's shader works
+     * in texture coordinates of the currently loaded data.
+     */
+    updateNiivueClipPlanes() {
+        // Use current buffer bounds for clip plane conversion
+        // This ensures clip planes are relative to the currently loaded data
+        const niivueClipPlanes = clipPlanesToNiivue(this._clipPlanes, this._currentBufferBounds);
+        if (niivueClipPlanes.length > 0) {
+            this.niivue.scene.clipPlaneDepthAziElevs = niivueClipPlanes;
+        }
+        else {
+            // Clear clip planes - set to "disabled" state (depth > 1.8)
+            this.niivue.scene.clipPlaneDepthAziElevs = [[2, 0, 0]];
+        }
+    }
+    /**
+     * Apply OMERO window settings to NIfTI header cal_min/cal_max.
+     *
+     * Uses the active channel's window (start/end preferred over min/max).
+     * This sets the display intensity range for NiiVue rendering.
+     */
+    applyOmeroToHeader() {
+        if (!this.hdr || !this._omero?.channels?.length)
+            return;
+        // Clamp active channel to valid range
+        const channelIndex = Math.min(this._activeChannel, this._omero.channels.length - 1);
+        const channel = this._omero.channels[channelIndex];
+        const window = channel?.window;
+        if (window) {
+            // Prefer start/end (display window based on quantiles) over min/max (data range)
+            const calMin = window.start ?? window.min;
+            const calMax = window.end ?? window.max;
+            if (calMin !== undefined)
+                this.hdr.cal_min = calMin;
+            if (calMax !== undefined)
+                this.hdr.cal_max = calMax;
+        }
+    }
+    /**
+     * Ensure OMERO metadata is available and applied.
+     *
+     * Strategy:
+     * - If OMERO exists in file metadata, use it (first time only)
+     * - If NOT present, compute dynamically:
+     *   - Compute at preview (lowest) resolution for quick initial display
+     *   - Recompute at target resolution for more accurate values
+     *   - Keep target values for consistency on subsequent clip plane changes
+     *
+     * @param ngffImage - The NgffImage at the current resolution level
+     * @param levelIndex - The resolution level index
+     */
+    async ensureOmeroMetadata(ngffImage, levelIndex) {
+        const existingOmero = this.multiscales.metadata?.omero;
+        if (existingOmero && !this._omero) {
+            // Use existing OMERO metadata from the file (first time)
+            this._omero = existingOmero;
+            this.applyOmeroToHeader();
+            return;
+        }
+        if (!existingOmero) {
+            // No OMERO in file - compute dynamically
+            // Compute at preview (lowest) and target levels, then keep for consistency
+            const lowestLevel = this.multiscales.images.length - 1;
+            const isPreviewLevel = levelIndex === lowestLevel;
+            const isTargetLevel = levelIndex === this.targetLevelIndex;
+            const needsCompute = isPreviewLevel ||
+                (isTargetLevel &&
+                    this._omeroComputedForLevel !== this.targetLevelIndex);
+            if (needsCompute) {
+                const computedOmero = await computeOmeroFromNgffImage(ngffImage);
+                this._omero = computedOmero;
+                this._omeroComputedForLevel = levelIndex;
+                this.applyOmeroToHeader();
+            }
+        }
+    }
+    /**
+     * Handle clip plane change from NiiVue.
+     * This is called when the user interacts with clip planes in NiiVue.
+     */
+    onNiivueClipPlaneChange(_clipPlane) {
+        // For now, we don't update our clip planes from NiiVue interactions
+        // This could be extended in the future to support bidirectional sync
+    }
+    /**
+     * Set clip planes.
+     *
+     * Visual clipping is updated immediately for responsive feedback.
+     * Data refetch is debounced to avoid excessive reloading during slider interaction.
+     * Resolution changes are direction-aware: reducing volume may increase resolution,
+     * increasing volume may decrease resolution.
+     *
+     * @param planes - Array of clip planes (max 6). Empty array = full volume visible.
+     * @throws Error if more than 6 planes provided or if planes are invalid
+     */
+    setClipPlanes(planes) {
+        // Validate the planes
+        validateClipPlanes(planes);
+        // Check if this is a "reset" operation (clearing all planes)
+        const isReset = planes.length === 0 && this._previousClipPlanes.length > 0;
+        // Store new clip planes
+        this._clipPlanes = planes.map((p) => ({
+            point: [...p.point],
+            normal: normalizeVector([...p.normal]),
+        }));
+        // Always update NiiVue clip planes immediately (visual feedback)
+        this.updateNiivueClipPlanes();
+        this.niivue.drawScene();
+        // Clear any pending debounced refetch
+        if (this.clipPlaneRefetchTimeout) {
+            clearTimeout(this.clipPlaneRefetchTimeout);
+            this.clipPlaneRefetchTimeout = null;
+        }
+        // Debounce the data refetch decision
+        this.clipPlaneRefetchTimeout = setTimeout(() => {
+            this.handleDebouncedClipPlaneUpdate(isReset);
+        }, this.clipPlaneDebounceMs);
+    }
+    /**
+     * Handle clip plane update after debounce delay.
+     * Implements direction-aware resolution selection.
+     *
+     * Only triggers a refetch when the resolution level needs to change.
+     * Visual clipping is handled by NiiVue clip planes (updated immediately in setClipPlanes).
+     */
+    handleDebouncedClipPlaneUpdate(isReset) {
+        this.clipPlaneRefetchTimeout = null;
+        // Always use level 0 for consistent pixel count comparison across resolution changes
+        const referenceImage = this.multiscales.images[0];
+        // Calculate current region at reference resolution
+        const currentRegion = clipPlanesToPixelRegion(this._clipPlanes, this._volumeBounds, referenceImage);
+        const currentAligned = alignToChunks(currentRegion, referenceImage);
+        const currentPixelCount = this.calculateAlignedPixelCount(currentAligned);
+        // Determine volume change direction (comparing at consistent reference level)
+        const volumeReduced = currentPixelCount < this._previousPixelCount;
+        const volumeIncreased = currentPixelCount > this._previousPixelCount;
+        // Get optimal resolution for new region (3D viewport bounds)
+        const selection = selectResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds, this._viewportBounds3D ?? undefined);
+        // Direction-aware resolution change
+        let newTargetLevel = this.targetLevelIndex;
+        if (isReset) {
+            // Reset/clear: always recalculate optimal resolution
+            newTargetLevel = selection.levelIndex;
+        }
+        else if (volumeReduced && selection.levelIndex < this.targetLevelIndex) {
+            // Volume reduced → allow higher resolution (lower level index)
+            newTargetLevel = selection.levelIndex;
+        }
+        else if (volumeIncreased && selection.levelIndex > this.targetLevelIndex) {
+            // Volume increased → allow lower resolution (higher level index) if needed to fit
+            newTargetLevel = selection.levelIndex;
+        }
+        // Otherwise: keep current level (no unnecessary resolution changes)
+        // Only refetch when resolution level changes
+        // Visual clipping is handled by NiiVue clip planes (already updated in setClipPlanes)
+        if (newTargetLevel !== this.targetLevelIndex) {
+            this.targetLevelIndex = newTargetLevel;
+            this.populateVolume(true, "clipPlanesChanged"); // Skip preview for clip plane updates
+        }
+        // Emit clipPlanesChange event (after debounce)
+        this._emitEvent("clipPlanesChange", {
+            clipPlanes: this.copyClipPlanes(this._clipPlanes),
+        });
+    }
+    /**
+     * Calculate pixel count for a chunk-aligned region.
+     */
+    calculateAlignedPixelCount(aligned) {
+        return ((aligned.chunkAlignedEnd[0] - aligned.chunkAlignedStart[0]) *
+            (aligned.chunkAlignedEnd[1] - aligned.chunkAlignedStart[1]) *
+            (aligned.chunkAlignedEnd[2] - aligned.chunkAlignedStart[2]));
+    }
+    /**
+     * Create a deep copy of clip planes array.
+     */
+    copyClipPlanes(planes) {
+        return planes.map((p) => ({
+            point: [...p.point],
+            normal: [...p.normal],
+        }));
+    }
+    /**
+     * Get current clip planes.
+     *
+     * @returns Copy of current clip planes array
+     */
+    getClipPlanes() {
+        return this._clipPlanes.map((p) => ({
+            point: [...p.point],
+            normal: [...p.normal],
+        }));
+    }
+    /**
+     * Add a single clip plane.
+     *
+     * @param plane - Clip plane to add
+     * @throws Error if already at maximum (6) clip planes
+     */
+    addClipPlane(plane) {
+        if (this._clipPlanes.length >= MAX_CLIP_PLANES) {
+            throw new Error(`Cannot add clip plane: already at maximum of ${MAX_CLIP_PLANES} planes`);
+        }
+        const newPlanes = [
+            ...this._clipPlanes,
+            {
+                point: [...plane.point],
+                normal: [...plane.normal],
+            },
+        ];
+        this.setClipPlanes(newPlanes);
+    }
+    /**
+     * Remove a clip plane by index.
+     *
+     * @param index - Index of plane to remove
+     * @throws Error if index is out of bounds
+     */
+    removeClipPlane(index) {
+        if (index < 0 || index >= this._clipPlanes.length) {
+            throw new Error(`Invalid clip plane index: ${index} (have ${this._clipPlanes.length} planes)`);
+        }
+        const newPlanes = this._clipPlanes.filter((_, i) => i !== index);
+        this.setClipPlanes(newPlanes);
+    }
+    /**
+     * Clear all clip planes (show full volume).
+     */
+    clearClipPlanes() {
+        this.setClipPlanes([]);
+    }
+    /**
+     * Get the current resolution level index.
+     */
+    getCurrentLevelIndex() {
+        return this.currentLevelIndex;
+    }
+    /**
+     * Get the target resolution level index.
+     */
+    getTargetLevelIndex() {
+        return this.targetLevelIndex;
+    }
+    /**
+     * Get the number of resolution levels.
+     */
+    getNumLevels() {
+        return this.multiscales.images.length;
+    }
+    /**
+     * Get the volume bounds in world space.
+     */
+    getVolumeBounds() {
+        return {
+            min: [...this._volumeBounds.min],
+            max: [...this._volumeBounds.max],
+        };
+    }
+    // ============================================================
+    // Viewport-Aware Resolution
+    // ============================================================
+    /**
+     * Enable or disable viewport-aware resolution selection.
+     *
+     * When enabled, pan/zoom/rotation interactions are monitored and the fetch
+     * region is constrained to the visible viewport area. This allows higher
+     * resolution within the same `maxPixels` budget when zoomed in.
+     *
+     * @param enabled - Whether to enable viewport-aware resolution
+     */
+    setViewportAware(enabled) {
+        if (enabled === this._viewportAwareEnabled)
+            return;
+        this._viewportAwareEnabled = enabled;
+        if (enabled) {
+            // Hook viewport events on all attached NVs
+            for (const [nv, state] of this._attachedNiivues) {
+                this._hookViewportEvents(nv, state);
+            }
+            // Compute initial viewport bounds and trigger refetch
+            this._recomputeViewportBounds();
+        }
+        else {
+            // Unhook viewport events on all attached NVs
+            for (const [nv, state] of this._attachedNiivues) {
+                this._unhookViewportEvents(nv, state);
+            }
+            // Clear viewport bounds and refetch at full volume
+            this._viewportBounds3D = null;
+            this._viewportBoundsPerSlab.clear();
+            if (this._viewportUpdateTimeout) {
+                clearTimeout(this._viewportUpdateTimeout);
+                this._viewportUpdateTimeout = null;
+            }
+            // Recompute resolution without viewport constraint
+            const selection = selectResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds);
+            if (selection.levelIndex !== this.targetLevelIndex) {
+                this.targetLevelIndex = selection.levelIndex;
+                this.populateVolume(true, "viewportChanged");
+            }
+            // Also reload slabs without viewport constraint
+            this._reloadAllSlabs("viewportChanged");
+        }
+    }
+    /**
+     * Get whether viewport-aware resolution selection is enabled.
+     */
+    get viewportAware() {
+        return this._viewportAwareEnabled;
+    }
+    /**
+     * Get the current 3D viewport bounds (null if viewport-aware is disabled
+     * or no viewport constraint is active).
+     */
+    getViewportBounds() {
+        if (!this._viewportBounds3D)
+            return null;
+        return {
+            min: [...this._viewportBounds3D.min],
+            max: [...this._viewportBounds3D.max],
+        };
+    }
+    /**
+     * Hook viewport events (onMouseUp, onZoom3DChange, wheel) on a NV instance.
+     */
+    _hookViewportEvents(nv, state) {
+        // Save and chain onMouseUp (fires at end of any mouse/touch interaction)
+        state.previousOnMouseUp = nv.onMouseUp;
+        nv.onMouseUp = (data) => {
+            if (state.previousOnMouseUp) {
+                state.previousOnMouseUp(data);
+            }
+            this._handleViewportInteractionEnd(nv);
+        };
+        // Save and chain onZoom3DChange (fires when volScaleMultiplier changes)
+        state.previousOnZoom3DChange = nv.onZoom3DChange;
+        nv.onZoom3DChange = (zoom) => {
+            if (state.previousOnZoom3DChange) {
+                state.previousOnZoom3DChange(zoom);
+            }
+            this._handleViewportInteractionEnd(nv);
+        };
+        // Add wheel event listener on the canvas for scroll-wheel zoom detection
+        const controller = new AbortController();
+        state.viewportAbortController = controller;
+        if (nv.canvas) {
+            nv.canvas.addEventListener("wheel", () => {
+                this._handleViewportInteractionEnd(nv);
+            }, { signal: controller.signal, passive: true });
+        }
+    }
+    /**
+     * Unhook viewport events from a NV instance.
+     */
+    _unhookViewportEvents(nv, state) {
+        // Restore onMouseUp
+        if (state.previousOnMouseUp !== undefined) {
+            nv.onMouseUp = state.previousOnMouseUp;
+            state.previousOnMouseUp = undefined;
+        }
+        // Restore onZoom3DChange
+        if (state.previousOnZoom3DChange !== undefined) {
+            nv.onZoom3DChange = state.previousOnZoom3DChange;
+            state.previousOnZoom3DChange = undefined;
+        }
+        // Remove wheel event listener
+        if (state.viewportAbortController) {
+            state.viewportAbortController.abort();
+            state.viewportAbortController = undefined;
+        }
+    }
+    // ============================================================
+    // 3D Zoom Override
+    // ============================================================
+    /**
+     * Install a capturing-phase wheel listener on the NV canvas that overrides
+     * NiiVue's hardcoded 3D render zoom clamp ([0.5, 2.0]).
+     *
+     * The listener intercepts scroll events over 3D render tiles and applies
+     * zoom via `nv.setScale()` (which has no internal clamp), using the
+     * configurable `_min3DZoom` / `_max3DZoom` bounds instead.
+     *
+     * Clip-plane scrolling is preserved: when a clip plane is active
+     * (depth < 1.8), the event passes through to NiiVue's native handler.
+     */
+    _hookZoomOverride(nv, state) {
+        if (!nv.canvas)
+            return;
+        const controller = new AbortController();
+        state.zoomOverrideAbortController = controller;
+        nv.canvas.addEventListener("wheel", (e) => {
+            // Convert mouse position to DPR-scaled canvas coordinates
+            const rect = nv.canvas.getBoundingClientRect();
+            const dpr = nv.uiData.dpr ?? 1;
+            const x = (e.clientX - rect.left) * dpr;
+            const y = (e.clientY - rect.top) * dpr;
+            // Only intercept if mouse is over a 3D render tile
+            if (nv.inRenderTile(x, y) < 0)
+                return;
+            // Preserve clip-plane scrolling: when a clip plane is active
+            // (depth < 1.8), let NiiVue handle the event normally.
+            const clips = nv.scene.clipPlaneDepthAziElevs;
+            const activeIdx = nv.uiData.activeClipPlaneIndex;
+            if (nv.volumes.length > 0 &&
+                clips?.[activeIdx]?.[0] !== undefined &&
+                clips[activeIdx][0] < 1.8) {
+                return;
+            }
+            // Prevent NiiVue's clamped handler from running.
+            // NiiVue registers its listener in the bubbling phase, so our
+            // capturing-phase listener fires first. stopImmediatePropagation
+            // ensures no other same-element listeners fire either.
+            e.stopImmediatePropagation();
+            e.preventDefault();
+            // Compute new zoom (same ×1.1 / ×0.9 per step as NiiVue).
+            // Round to 2 decimal places (NiiVue rounds to 1, which causes the
+            // zoom to get stuck at small values like 0.5 where ×0.9 rounds back).
+            const zoomDir = e.deltaY < 0 ? 1 : -1;
+            const current = nv.scene.volScaleMultiplier;
+            let newZoom = current * (zoomDir > 0 ? 1.1 : 0.9);
+            newZoom = Math.round(newZoom * 100) / 100;
+            newZoom = Math.max(this._min3DZoom, Math.min(this._max3DZoom, newZoom));
+            nv.setScale(newZoom);
+            // Notify the viewport-aware system. Since we stopped propagation,
+            // the passive wheel listener from _hookViewportEvents won't fire,
+            // so we call this directly.
+            this._handleViewportInteractionEnd(nv);
+        }, { capture: true, signal: controller.signal });
+    }
+    /**
+     * Remove the 3D zoom override wheel listener from a NV instance.
+     */
+    _unhookZoomOverride(_nv, state) {
+        if (state.zoomOverrideAbortController) {
+            state.zoomOverrideAbortController.abort();
+            state.zoomOverrideAbortController = undefined;
+        }
+    }
+    /**
+     * Called at the end of any viewport interaction (mouse up, touch end,
+     * zoom change, scroll wheel). Debounces the viewport bounds recomputation.
+     */
+    _handleViewportInteractionEnd(_nv) {
+        if (!this._viewportAwareEnabled)
+            return;
+        // Debounce: clear any pending update and schedule a new one
+        if (this._viewportUpdateTimeout) {
+            clearTimeout(this._viewportUpdateTimeout);
+        }
+        this._viewportUpdateTimeout = setTimeout(() => {
+            this._viewportUpdateTimeout = null;
+            this._recomputeViewportBounds();
+        }, OMEZarrNVImage.VIEWPORT_DEBOUNCE_MS);
+    }
+    /**
+     * Recompute viewport bounds from all attached NV instances and trigger
+     * resolution reselection if bounds changed significantly.
+     */
+    _recomputeViewportBounds() {
+        if (!this._viewportAwareEnabled)
+            return;
+        // Compute separate viewport bounds for:
+        // - 3D volume: union of all RENDER/MULTIPLANAR NV viewport bounds
+        // - Per-slab: each slab type gets its own NV's viewport bounds
+        let new3DBounds = null;
+        const newSlabBounds = new Map();
+        for (const [nv, state] of this._attachedNiivues) {
+            if (state.currentSliceType === SLICE_TYPE.RENDER ||
+                state.currentSliceType === SLICE_TYPE.MULTIPLANAR) {
+                // 3D render mode: compute from orthographic frustum
+                const nvBounds = computeViewportBounds3D(nv, this._volumeBounds);
+                if (!new3DBounds) {
+                    new3DBounds = nvBounds;
+                }
+                else {
+                    // Union of multiple 3D views
+                    new3DBounds = {
+                        min: [
+                            Math.min(new3DBounds.min[0], nvBounds.min[0]),
+                            Math.min(new3DBounds.min[1], nvBounds.min[1]),
+                            Math.min(new3DBounds.min[2], nvBounds.min[2]),
+                        ],
+                        max: [
+                            Math.max(new3DBounds.max[0], nvBounds.max[0]),
+                            Math.max(new3DBounds.max[1], nvBounds.max[1]),
+                            Math.max(new3DBounds.max[2], nvBounds.max[2]),
+                        ],
+                    };
+                }
+            }
+            else if (this._isSlabSliceType(state.currentSliceType)) {
+                // 2D slice mode: compute from pan/zoom
+                const sliceType = state.currentSliceType;
+                const slabState = this._slabBuffers.get(sliceType);
+                const normScale = slabState?.normalizationScale ?? 1.0;
+                const nvBounds = computeViewportBounds2D(nv, state.currentSliceType, this._volumeBounds, normScale);
+                newSlabBounds.set(sliceType, nvBounds);
+            }
+        }
+        // Check if 3D bounds changed
+        const bounds3DChanged = !new3DBounds !== !this._viewportBounds3D ||
+            (new3DBounds &&
+                this._viewportBounds3D &&
+                !boundsApproxEqual(new3DBounds, this._viewportBounds3D));
+        // Check if any slab bounds changed
+        let slabBoundsChanged = false;
+        for (const [sliceType, newBounds] of newSlabBounds) {
+            const oldBounds = this._viewportBoundsPerSlab.get(sliceType) ?? null;
+            if (!newBounds !== !oldBounds ||
+                (newBounds && oldBounds && !boundsApproxEqual(newBounds, oldBounds))) {
+                slabBoundsChanged = true;
+                break;
+            }
+        }
+        if (!bounds3DChanged && !slabBoundsChanged)
+            return;
+        // Update stored bounds
+        this._viewportBounds3D = new3DBounds;
+        for (const [sliceType, bounds] of newSlabBounds) {
+            this._viewportBoundsPerSlab.set(sliceType, bounds);
+        }
+        // Recompute 3D resolution selection with new 3D viewport bounds
+        if (bounds3DChanged) {
+            const selection = selectResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds, this._viewportBounds3D ?? undefined);
+            if (selection.levelIndex !== this.targetLevelIndex) {
+                this.targetLevelIndex = selection.levelIndex;
+                this.populateVolume(true, "viewportChanged");
+            }
+        }
+        // Reload slabs with new per-slab viewport bounds
+        if (slabBoundsChanged) {
+            this._reloadAllSlabs("viewportChanged");
+        }
+    }
+    /**
+     * Reload all active slabs (for all slice types that have buffers).
+     */
+    _reloadAllSlabs(trigger) {
+        for (const [sliceType, slabState] of this._slabBuffers) {
+            // Find the world coordinate for this slab from any attached NV in this mode
+            for (const [nv, attachedState] of this._attachedNiivues) {
+                if (this._isSlabSliceType(attachedState.currentSliceType) &&
+                    attachedState.currentSliceType === sliceType) {
+                    const crosshairPos = nv.scene?.crosshairPos;
+                    if (!crosshairPos || nv.volumes.length === 0)
+                        continue;
+                    try {
+                        const mm = nv.frac2mm([
+                            crosshairPos[0],
+                            crosshairPos[1],
+                            crosshairPos[2],
+                        ]);
+                        // frac2mm returns values in the slab NVImage's mm space, which
+                        // is normalized (world * normalizationScale). Convert back to
+                        // physical world coordinates for worldToPixel and other callers.
+                        const ns = slabState.normalizationScale;
+                        const worldCoord = [
+                            mm[0] / ns,
+                            mm[1] / ns,
+                            mm[2] / ns,
+                        ];
+                        this._debouncedSlabReload(sliceType, worldCoord, trigger);
+                    }
+                    catch {
+                        // Can't convert coordinates yet
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    /**
+     * Get whether the image is currently loading.
+     */
+    getIsLoading() {
+        return this.isLoading;
+    }
+    /**
+     * Wait for all pending fetches to complete.
+     */
+    async waitForIdle() {
+        await this.coalescer.onIdle();
+    }
+    // ============================================================
+    // OMERO Metadata (Visualization Parameters)
+    // ============================================================
+    /**
+     * Get OMERO metadata (if available).
+     *
+     * Returns the existing OMERO metadata from the OME-Zarr file,
+     * or the computed OMERO metadata if none was present in the file.
+     *
+     * OMERO metadata includes per-channel visualization parameters:
+     * - window.min/max: The actual data range
+     * - window.start/end: The display window (based on quantiles)
+     * - color: Hex color for the channel
+     * - label: Channel name
+     *
+     * @returns OMERO metadata or undefined if not yet loaded/computed
+     */
+    getOmero() {
+        return this._omero;
+    }
+    /**
+     * Get the active channel index used for OMERO window selection.
+     *
+     * For multi-channel images, this determines which channel's
+     * cal_min/cal_max values are applied to the NiiVue display.
+     *
+     * @returns Current active channel index (0-based)
+     */
+    getActiveChannel() {
+        return this._activeChannel;
+    }
+    /**
+     * Set the active channel for OMERO window selection.
+     *
+     * For multi-channel images, this determines which channel's
+     * window (cal_min/cal_max) values are applied to the NiiVue display.
+     *
+     * Changing the active channel immediately updates the display intensity
+     * range and refreshes the NiiVue rendering.
+     *
+     * @param index - Channel index (0-based)
+     * @throws Error if no OMERO metadata is available
+     * @throws Error if index is out of range
+     *
+     * @example
+     * ```typescript
+     * // Get number of channels
+     * const omero = image.getOmero();
+     * if (omero) {
+     *   console.log(`${omero.channels.length} channels available`);
+     *   // Switch to channel 1
+     *   image.setActiveChannel(1);
+     * }
+     * ```
+     */
+    setActiveChannel(index) {
+        if (!this._omero?.channels?.length) {
+            throw new Error("No OMERO metadata available");
+        }
+        if (index < 0 || index >= this._omero.channels.length) {
+            throw new Error(`Invalid channel index: ${index} (have ${this._omero.channels.length} channels)`);
+        }
+        this._activeChannel = index;
+        this.applyOmeroToHeader();
+        this.niivue.updateGLVolume();
+        this._widenCalRangeIfNeeded(this);
+    }
+    // ============================================================
+    // Multi-NV / Slab Buffer Management
+    // ============================================================
+    /**
+     * Attach a Niivue instance for slice-type-aware rendering.
+     *
+     * The image auto-detects the NV's current slice type and hooks into
+     * `onOptsChange` to track mode changes and `onLocationChange` to track
+     * crosshair/slice position changes.
+     *
+     * When the NV is in a 2D slice mode (Axial, Coronal, Sagittal), the image
+     * loads a slab (one chunk thick in the orthogonal direction) at the current
+     * slice position, using a 2D pixel budget for resolution selection.
+     *
+     * @param nv - The Niivue instance to attach
+     */
+    attachNiivue(nv) {
+        if (this._attachedNiivues.has(nv))
+            return; // Already attached
+        const state = {
+            nv,
+            currentSliceType: this._detectSliceType(nv),
+            previousOnLocationChange: nv.onLocationChange,
+            previousOnOptsChange: nv
+                .onOptsChange,
+        };
+        // Hook onOptsChange to detect slice type changes
+        nv.onOptsChange = (propertyName, newValue, oldValue) => {
+            // Chain to previous handler
+            if (state.previousOnOptsChange) {
+                state.previousOnOptsChange(propertyName, newValue, oldValue);
+            }
+            if (propertyName === "sliceType") {
+                this._handleSliceTypeChange(nv, newValue);
+            }
+        };
+        // Hook onLocationChange to detect slice position changes
+        nv.onLocationChange = (location) => {
+            // Chain to previous handler
+            if (state.previousOnLocationChange) {
+                state.previousOnLocationChange(location);
+            }
+            this._handleLocationChange(nv, location);
+        };
+        this._attachedNiivues.set(nv, state);
+        // Hook viewport events if viewport-aware mode is already enabled
+        if (this._viewportAwareEnabled) {
+            this._hookViewportEvents(nv, state);
+        }
+        // Override NiiVue's hardcoded 3D zoom clamp (always-on)
+        this._hookZoomOverride(nv, state);
+        // If the NV is already in a 2D slice mode, set up the slab buffer
+        const sliceType = state.currentSliceType;
+        if (this._isSlabSliceType(sliceType)) {
+            this._ensureSlabForNiivue(nv, sliceType);
+        }
+    }
+    /**
+     * Detach a Niivue instance, restoring its original callbacks.
+     *
+     * @param nv - The Niivue instance to detach
+     */
+    detachNiivue(nv) {
+        const state = this._attachedNiivues.get(nv);
+        if (!state)
+            return;
+        // Unhook viewport events if active
+        this._unhookViewportEvents(nv, state);
+        // Unhook 3D zoom override
+        this._unhookZoomOverride(nv, state);
+        // Restore original callbacks
+        nv.onLocationChange = state.previousOnLocationChange ?? (() => { });
+        nv.onOptsChange =
+            (state.previousOnOptsChange ?? (() => { }));
+        this._attachedNiivues.delete(nv);
+    }
+    /**
+     * Get the slab buffer state for a given slice type, if it exists.
+     * Useful for testing and inspection.
+     *
+     * @param sliceType - The slice type to query
+     * @returns The slab buffer state, or undefined if not yet created
+     */
+    getSlabBufferState(sliceType) {
+        return this._slabBuffers.get(sliceType);
+    }
+    /**
+     * Get all attached Niivue instances.
+     */
+    getAttachedNiivues() {
+        return Array.from(this._attachedNiivues.keys());
+    }
+    // ---- Private slab helpers ----
+    /**
+     * Detect the current slice type of a Niivue instance.
+     */
+    _detectSliceType(nv) {
+        // Access the opts.sliceType via the scene data or fall back to checking
+        // the convenience properties. Niivue stores the current sliceType in opts.
+        // We can read it from the NV instance's internal opts.
+        const opts = nv.opts;
+        if (opts && typeof opts.sliceType === "number") {
+            return opts.sliceType;
+        }
+        // Default to Render
+        return SLICE_TYPE.RENDER;
+    }
+    /**
+     * Check if a slice type is one of the 2D slab types.
+     */
+    _isSlabSliceType(st) {
+        return (st === SLICE_TYPE.AXIAL ||
+            st === SLICE_TYPE.CORONAL ||
+            st === SLICE_TYPE.SAGITTAL);
+    }
+    /**
+     * Get the orthogonal axis index for a slab slice type.
+     * Returns index in [z, y, x] order:
+     * - Axial: slicing through Z → orthogonal axis = 0 (Z)
+     * - Coronal: slicing through Y → orthogonal axis = 1 (Y)
+     * - Sagittal: slicing through X → orthogonal axis = 2 (X)
+     */
+    _getOrthogonalAxis(sliceType) {
+        switch (sliceType) {
+            case SLICE_TYPE.AXIAL:
+                return 0; // Z
+            case SLICE_TYPE.CORONAL:
+                return 1; // Y
+            case SLICE_TYPE.SAGITTAL:
+                return 2; // X
+        }
+    }
+    /**
+     * Handle a slice type change on an attached Niivue instance.
+     */
+    _handleSliceTypeChange(nv, newSliceType) {
+        const state = this._attachedNiivues.get(nv);
+        if (!state)
+            return;
+        const oldSliceType = state.currentSliceType;
+        state.currentSliceType = newSliceType;
+        if (oldSliceType === newSliceType)
+            return;
+        if (this._isSlabSliceType(newSliceType)) {
+            // Switching TO a 2D slab mode: swap in the slab NVImage
+            this._ensureSlabForNiivue(nv, newSliceType);
+        }
+        else {
+            // Switching TO Render or Multiplanar mode: swap back to the main (3D) NVImage
+            this._swapVolumeInNiivue(nv, this);
+        }
+    }
+    /**
+     * Handle location (crosshair) change on an attached Niivue instance.
+     * Checks if the current slice position has moved outside the loaded slab.
+     */
+    _handleLocationChange(nv, _location) {
+        const state = this._attachedNiivues.get(nv);
+        if (!state || !this._isSlabSliceType(state.currentSliceType))
+            return;
+        const sliceType = state.currentSliceType;
+        const slabState = this._slabBuffers.get(sliceType);
+        if (!slabState || slabState.slabStart < 0)
+            return; // Slab not yet created or loaded
+        // Get the current crosshair position in fractional coordinates [0..1]
+        const crosshairPos = nv.scene?.crosshairPos;
+        if (!crosshairPos || nv.volumes.length === 0)
+            return;
+        let worldCoord;
+        try {
+            const mm = nv.frac2mm([
+                crosshairPos[0],
+                crosshairPos[1],
+                crosshairPos[2],
+            ]);
+            // frac2mm returns values in the slab NVImage's normalized mm space
+            // (world * normalizationScale). Convert back to physical world.
+            const ns = slabState.normalizationScale;
+            worldCoord = [mm[0] / ns, mm[1] / ns, mm[2] / ns];
+        }
+        catch {
+            return; // Can't convert coordinates yet
+        }
+        // Convert world to pixel at the slab's current resolution level
+        const ngffImage = this.multiscales.images[slabState.levelIndex];
+        const pixelCoord = worldToPixel(worldCoord, ngffImage);
+        // Check the orthogonal axis
+        const orthAxis = this._getOrthogonalAxis(sliceType);
+        const pixelPos = pixelCoord[orthAxis];
+        // Is the pixel position outside the currently loaded slab?
+        if (pixelPos < slabState.slabStart || pixelPos >= slabState.slabEnd) {
+            // Need to reload the slab for the new position
+            this._debouncedSlabReload(sliceType, worldCoord);
+        }
+    }
+    /**
+     * Debounced slab reload to avoid excessive reloading during scrolling.
+     */
+    _debouncedSlabReload(sliceType, worldCoord, trigger = "sliceChanged") {
+        // Clear any pending reload for this slice type
+        const existing = this._slabReloadTimeouts.get(sliceType);
+        if (existing)
+            clearTimeout(existing);
+        const timeout = setTimeout(() => {
+            this._slabReloadTimeouts.delete(sliceType);
+            void this._loadSlab(sliceType, worldCoord, trigger);
+        }, 100); // Short debounce for slice scrolling (faster than clip plane debounce)
+        this._slabReloadTimeouts.set(sliceType, timeout);
+    }
+    /**
+     * Ensure a slab buffer exists and is loaded for the given NV + slice type.
+     * If needed, creates the slab buffer and triggers an initial load.
+     */
+    _ensureSlabForNiivue(nv, sliceType) {
+        let slabState = this._slabBuffers.get(sliceType);
+        if (!slabState) {
+            // Lazily create the slab buffer
+            slabState = this._createSlabBuffer(sliceType);
+            this._slabBuffers.set(sliceType, slabState);
+        }
+        // Swap the slab's NVImage into this NV instance
+        this._swapVolumeInNiivue(nv, slabState.nvImage);
+        // Get the current crosshair position and load the slab.
+        // Use the volume bounds center as a fallback if crosshair isn't available yet.
+        let worldCoord;
+        try {
+            const crosshairPos = nv.scene?.crosshairPos;
+            if (crosshairPos && nv.volumes.length > 0) {
+                const mm = nv.frac2mm([
+                    crosshairPos[0],
+                    crosshairPos[1],
+                    crosshairPos[2],
+                ]);
+                worldCoord = [mm[0], mm[1], mm[2]];
+            }
+            else {
+                // Fall back to volume center
+                worldCoord = [
+                    (this._volumeBounds.min[0] + this._volumeBounds.max[0]) / 2,
+                    (this._volumeBounds.min[1] + this._volumeBounds.max[1]) / 2,
+                    (this._volumeBounds.min[2] + this._volumeBounds.max[2]) / 2,
+                ];
+            }
+        }
+        catch {
+            // Fall back to volume center if frac2mm fails
+            worldCoord = [
+                (this._volumeBounds.min[0] + this._volumeBounds.max[0]) / 2,
+                (this._volumeBounds.min[1] + this._volumeBounds.max[1]) / 2,
+                (this._volumeBounds.min[2] + this._volumeBounds.max[2]) / 2,
+            ];
+        }
+        void this._loadSlab(sliceType, worldCoord, "initial").catch((err) => {
+            console.error(`[fidnii] Error loading slab for ${SLICE_TYPE[sliceType]}:`, err);
+        });
+    }
+    /**
+     * Create a new slab buffer state for a slice type.
+     */
+    _createSlabBuffer(sliceType) {
+        const bufferManager = new BufferManager(this.maxPixels, this.dtype);
+        const nvImage = new NVImage();
+        // Initialize with placeholder NIfTI header (same as main image setup)
+        const hdr = new NIFTI1();
+        nvImage.hdr = hdr;
+        hdr.dims = [3, 1, 1, 1, 1, 1, 1, 1];
+        hdr.datatypeCode = getNiftiDataType(this.dtype);
+        hdr.numBitsPerVoxel = getBytesPerPixel(this.dtype) * 8;
+        hdr.pixDims = [1, 1, 1, 1, 0, 0, 0, 0];
+        hdr.affine = [
+            [1, 0, 0, 0],
+            [0, 1, 0, 0],
+            [0, 0, 1, 0],
+            [0, 0, 0, 1],
+        ];
+        hdr.sform_code = 1;
+        nvImage.name = `${this.name ?? "OME-Zarr"} [${SLICE_TYPE[sliceType]}]`;
+        nvImage.img = bufferManager.resize([1, 1, 1]);
+        nvImage._colormap = "gray";
+        nvImage._opacity = 1.0;
+        // Select initial resolution using 2D pixel budget
+        const orthAxis = this._getOrthogonalAxis(sliceType);
+        const selection = select2DResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds, orthAxis);
+        return {
+            nvImage,
+            bufferManager,
+            levelIndex: this.multiscales.images.length - 1, // Start at lowest
+            targetLevelIndex: selection.levelIndex,
+            slabStart: -1,
+            slabEnd: -1,
+            isLoading: false,
+            dtype: this.dtype,
+            normalizationScale: 1.0, // Updated on first slab load
+            pendingReload: null,
+        };
+    }
+    /**
+     * Swap the NVImage in a Niivue instance's volume list.
+     * Removes any existing volumes from this OMEZarrNVImage and adds the target.
+     */
+    _swapVolumeInNiivue(nv, targetVolume) {
+        // Find and remove any volumes we own (the main image or any slab NVImages)
+        const ourVolumes = new Set([this]);
+        for (const slab of this._slabBuffers.values()) {
+            ourVolumes.add(slab.nvImage);
+        }
+        // Remove our volumes from nv (in reverse to avoid index shifting issues)
+        const toRemove = nv.volumes.filter((v) => ourVolumes.has(v));
+        for (const vol of toRemove) {
+            try {
+                nv.removeVolume(vol);
+            }
+            catch {
+                // Ignore errors during removal (volume may not be fully initialized)
+            }
+        }
+        // Add the target volume if not already present
+        if (!nv.volumes.includes(targetVolume)) {
+            try {
+                nv.addVolume(targetVolume);
+            }
+            catch (err) {
+                console.warn("[fidnii] Failed to add volume to NV:", err);
+                return;
+            }
+        }
+        try {
+            nv.updateGLVolume();
+            this._widenCalRangeIfNeeded(targetVolume);
+        }
+        catch {
+            // May fail if GL context not ready
+        }
+    }
+    /**
+     * Load a slab for a 2D slice type at the given world position.
+     *
+     * The slab is one chunk thick in the orthogonal direction and uses
+     * the full in-plane extent (respecting clip planes).
+     *
+     * Loading follows a progressive strategy: preview (lowest res) then target.
+     * For viewport-triggered reloads, progressive rendering is skipped and
+     * only the target level is loaded (the user already sees the previous
+     * resolution, so a single jump is smoother).
+     *
+     * If a load is already in progress, the request is queued (latest-wins)
+     * and automatically drained when the current load finishes.
+     */
+    async _loadSlab(sliceType, worldCoord, trigger) {
+        const slabState = this._slabBuffers.get(sliceType);
+        if (!slabState)
+            return;
+        if (slabState.isLoading) {
+            // Queue this request (latest wins) — auto-drained when current load finishes
+            slabState.pendingReload = { worldCoord, trigger };
+            // Abort the in-flight progressive load so it finishes faster
+            const controller = this._slabAbortControllers.get(sliceType);
+            if (controller)
+                controller.abort();
+            return;
+        }
+        slabState.isLoading = true;
+        slabState.pendingReload = null;
+        // Create an AbortController for this load so it can be cancelled if a
+        // newer request arrives while we're still fetching intermediate levels.
+        const abortController = new AbortController();
+        this._slabAbortControllers.set(sliceType, abortController);
+        this._emitEvent("slabLoadingStart", {
+            sliceType,
+            levelIndex: slabState.targetLevelIndex,
+            trigger,
+        });
+        try {
+            const orthAxis = this._getOrthogonalAxis(sliceType);
+            // Recompute target resolution using 2D pixel budget with per-slab viewport bounds
+            const slabViewportBounds = this._viewportBoundsPerSlab.get(sliceType) ??
+                undefined;
+            const selection = select2DResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds, orthAxis, slabViewportBounds);
+            slabState.targetLevelIndex = selection.levelIndex;
+            const numLevels = this.multiscales.images.length;
+            const lowestLevel = numLevels - 1;
+            // For viewport-triggered reloads, skip progressive rendering — jump
+            // straight to the target level. The user already sees the previous
+            // resolution, so a single update is smoother than replaying the full
+            // progressive sequence which causes visual flicker during rapid
+            // zoom/pan interactions.
+            const skipProgressive = trigger === "viewportChanged";
+            const startLevel = skipProgressive
+                ? slabState.targetLevelIndex
+                : lowestLevel;
+            for (let level = startLevel; level >= slabState.targetLevelIndex; level--) {
+                // Check if this load has been superseded by a newer request
+                if (abortController.signal.aborted)
+                    break;
+                await this._loadSlabAtLevel(slabState, sliceType, worldCoord, level, orthAxis, trigger);
+                // Check again after the async fetch completes
+                if (abortController.signal.aborted)
+                    break;
+                slabState.levelIndex = level;
+                // Yield to the browser so the current level is actually painted before
+                // we start fetching the next (higher-resolution) level.
+                if (level > slabState.targetLevelIndex) {
+                    await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+                }
+            }
+        }
+        finally {
+            slabState.isLoading = false;
+            this._emitEvent("slabLoadingComplete", {
+                sliceType,
+                levelIndex: slabState.levelIndex,
+                slabStart: slabState.slabStart,
+                slabEnd: slabState.slabEnd,
+                trigger,
+            });
+            // Auto-drain: if a newer request was queued while we were loading,
+            // start it now (like populateVolume's handlePendingPopulateRequest).
+            this._handlePendingSlabReload(sliceType);
+        }
+    }
+    /**
+     * Process any pending slab reload request after the current load completes.
+     * Mirrors populateVolume's handlePendingPopulateRequest pattern.
+     */
+    _handlePendingSlabReload(sliceType) {
+        const slabState = this._slabBuffers.get(sliceType);
+        if (!slabState)
+            return;
+        const pending = slabState.pendingReload;
+        if (pending) {
+            slabState.pendingReload = null;
+            void this._loadSlab(sliceType, pending.worldCoord, pending.trigger);
+        }
+    }
+    /**
+     * Load slab data at a specific resolution level.
+     */
+    async _loadSlabAtLevel(slabState, sliceType, worldCoord, levelIndex, orthAxis, _trigger) {
+        const ngffImage = this.multiscales.images[levelIndex];
+        const chunkShape = getChunkShape(ngffImage);
+        const volumeShape = getVolumeShape(ngffImage);
+        // Convert world position to pixel position at this level
+        const pixelCoord = worldToPixel(worldCoord, ngffImage);
+        const orthPixel = pixelCoord[orthAxis];
+        // Find the chunk-aligned slab in the orthogonal axis
+        const chunkSize = chunkShape[orthAxis];
+        const slabStart = Math.max(0, Math.floor(orthPixel / chunkSize) * chunkSize);
+        const slabEnd = Math.min(slabStart + chunkSize, volumeShape[orthAxis]);
+        // Get the full in-plane region (respecting clip planes only).
+        // Viewport bounds are intentionally NOT passed here — they are used only
+        // for resolution selection (in _loadSlab → select2DResolution) so that a
+        // higher-res level is chosen when zoomed in.  The fetch region always
+        // covers the full in-plane extent so the slab fills the entire viewport.
+        const pixelRegion = clipPlanesToPixelRegion(this._clipPlanes, this._volumeBounds, ngffImage);
+        const alignedRegion = alignToChunks(pixelRegion, ngffImage);
+        // Override the orthogonal axis with our slab extent
+        const fetchStart = [
+            alignedRegion.chunkAlignedStart[0],
+            alignedRegion.chunkAlignedStart[1],
+            alignedRegion.chunkAlignedStart[2],
+        ];
+        const fetchEnd = [
+            alignedRegion.chunkAlignedEnd[0],
+            alignedRegion.chunkAlignedEnd[1],
+            alignedRegion.chunkAlignedEnd[2],
+        ];
+        fetchStart[orthAxis] = slabStart;
+        fetchEnd[orthAxis] = slabEnd;
+        const fetchedShape = [
+            fetchEnd[0] - fetchStart[0],
+            fetchEnd[1] - fetchStart[1],
+            fetchEnd[2] - fetchStart[2],
+        ];
+        // Fetch the data
+        const fetchRegion = { start: fetchStart, end: fetchEnd };
+        const result = await this.coalescer.fetchRegion(ngffImage, levelIndex, fetchRegion, `slab-${SLICE_TYPE[sliceType]}-${levelIndex}`);
+        // Resize buffer and copy data
+        const targetData = slabState.bufferManager.resize(fetchedShape);
+        targetData.set(result.data);
+        slabState.nvImage.img = slabState.bufferManager.getTypedArray();
+        // Update slab position tracking
+        slabState.slabStart = slabStart;
+        slabState.slabEnd = slabEnd;
+        // Update the NVImage header for this slab region
+        this._updateSlabHeader(slabState.nvImage, ngffImage, fetchStart, fetchEnd, fetchedShape);
+        // Apply OMERO metadata if available
+        if (this._omero) {
+            this._applyOmeroToSlabHeader(slabState.nvImage);
+        }
+        // Reset global_min so NiiVue recalculates intensity ranges
+        slabState.nvImage.global_min = undefined;
+        // Compute the normalization scale used by _updateSlabHeader so we can
+        // convert the world coordinate into the slab's normalized mm space.
+        const scale = ngffImage.scale;
+        const maxVoxelSize = Math.max(scale.x ?? scale.X ?? 1, scale.y ?? scale.Y ?? 1, scale.z ?? scale.Z ?? 1);
+        const normalizationScale = maxVoxelSize > 0 ? 1.0 / maxVoxelSize : 1.0;
+        slabState.normalizationScale = normalizationScale;
+        const normalizedMM = [
+            worldCoord[0] * normalizationScale,
+            worldCoord[1] * normalizationScale,
+            worldCoord[2] * normalizationScale,
+        ];
+        // Refresh all NV instances using this slice type
+        for (const [attachedNv, attachedState] of this._attachedNiivues) {
+            if (this._isSlabSliceType(attachedState.currentSliceType) &&
+                attachedState.currentSliceType === sliceType) {
+                // Ensure this NV has the slab volume
+                if (attachedNv.volumes.includes(slabState.nvImage)) {
+                    attachedNv.updateGLVolume();
+                    // Widen the display window if actual data exceeds the OMERO range.
+                    // Must run after updateGLVolume() which computes global_min/global_max.
+                    this._widenCalRangeIfNeeded(slabState.nvImage);
+                    // Position the crosshair at the correct slice within this slab.
+                    // Without this, NiiVue defaults to the center of the slab which
+                    // corresponds to different physical positions at each resolution level.
+                    const frac = attachedNv.mm2frac(normalizedMM);
+                    // Clamp to [0,1] — when viewport-aware mode constrains the slab to
+                    // a subregion, the crosshair world position may be outside the slab's
+                    // spatial extent, causing mm2frac to return out-of-range values.
+                    frac[0] = Math.max(0, Math.min(1, frac[0]));
+                    frac[1] = Math.max(0, Math.min(1, frac[1]));
+                    frac[2] = Math.max(0, Math.min(1, frac[2]));
+                    attachedNv.scene.crosshairPos = frac;
+                    attachedNv.drawScene();
+                }
+            }
+        }
+    }
+    /**
+     * Update NVImage header for a slab region.
+     */
+    _updateSlabHeader(nvImage, ngffImage, fetchStart, _fetchEnd, fetchedShape) {
+        if (!nvImage.hdr)
+            return;
+        const scale = ngffImage.scale;
+        const sx = scale.x ?? scale.X ?? 1;
+        const sy = scale.y ?? scale.Y ?? 1;
+        const sz = scale.z ?? scale.Z ?? 1;
+        // NiiVue's 2D slice renderer has precision issues when voxel sizes are
+        // very small (e.g. OME-Zarr datasets in meters where pixDims ~ 2e-5).
+        // Since the slab NVImage is rendered independently in its own Niivue
+        // instance, we can normalize coordinates to ~1mm voxels without affecting
+        // the 3D render. We scale uniformly to preserve aspect ratio.
+        const maxVoxelSize = Math.max(sx, sy, sz);
+        const normalizationScale = maxVoxelSize > 0 ? 1.0 / maxVoxelSize : 1.0;
+        const nsx = sx * normalizationScale;
+        const nsy = sy * normalizationScale;
+        const nsz = sz * normalizationScale;
+        nvImage.hdr.pixDims = [1, nsx, nsy, nsz, 0, 0, 0, 0];
+        // NIfTI dims: [ndim, x, y, z, t, ...]
+        nvImage.hdr.dims = [
+            3,
+            fetchedShape[2],
+            fetchedShape[1],
+            fetchedShape[0],
+            1,
+            1,
+            1,
+            1,
+        ];
+        // Build affine with offset for region start, then normalize
+        const affine = createAffineFromNgffImage(ngffImage);
+        // Adjust translation for region offset (fetchStart is [z, y, x])
+        affine[12] += fetchStart[2] * sx; // x offset
+        affine[13] += fetchStart[1] * sy; // y offset
+        affine[14] += fetchStart[0] * sz; // z offset
+        // Apply normalization to the entire affine (scale columns + translation)
+        for (let i = 0; i < 15; i++) {
+            affine[i] *= normalizationScale;
+        }
+        // affine[15] stays 1
+        const srows = affineToNiftiSrows(affine);
+        nvImage.hdr.affine = [
+            srows.srow_x,
+            srows.srow_y,
+            srows.srow_z,
+            [0, 0, 0, 1],
+        ];
+        nvImage.hdr.sform_code = 1;
+        nvImage.calculateRAS();
+    }
+    /**
+     * Apply OMERO metadata to a slab NVImage header.
+     */
+    _applyOmeroToSlabHeader(nvImage) {
+        if (!nvImage.hdr || !this._omero?.channels?.length)
+            return;
+        const channelIndex = Math.min(this._activeChannel, this._omero.channels.length - 1);
+        const channel = this._omero.channels[channelIndex];
+        const window = channel?.window;
+        if (window) {
+            const calMin = window.start ?? window.min;
+            const calMax = window.end ?? window.max;
+            if (calMin !== undefined)
+                nvImage.hdr.cal_min = calMin;
+            if (calMax !== undefined)
+                nvImage.hdr.cal_max = calMax;
+        }
+    }
+    /**
+     * Widen the display intensity range if the actual data exceeds the current
+     * cal_min/cal_max window (typically set from OMERO metadata).
+     *
+     * OMERO window settings may have been computed at a lower resolution where
+     * downsampling averaged out extreme voxels. At higher resolutions, individual
+     * bright/dark voxels can exceed the OMERO range, causing clipping artifacts
+     * (e.g., "banding" where bright structures clip to solid white).
+     *
+     * Widens cal_min/cal_max to global_min/global_max (actual data extremes at
+     * the current resolution level) so no data is clipped. The hdr.cal_min/
+     * cal_max values are NOT modified — they preserve the original OMERO values
+     * for reuse on subsequent slab reloads.
+     *
+     * Must be called AFTER updateGLVolume() so that calMinMax() has computed
+     * global_min/global_max from the actual slab data.
+     *
+     * @returns true if the display range was widened
+     */
+    _widenCalRangeIfNeeded(nvImage) {
+        if (nvImage.global_min === undefined || nvImage.global_max === undefined) {
+            return false;
+        }
+        let widened = false;
+        // Widen the runtime display range (cal_min/cal_max) to encompass the
+        // actual data extremes (global_min/global_max) at this resolution level.
+        // The hdr values are NOT modified so the original OMERO window is
+        // preserved for next reload.
+        if (nvImage.cal_max !== undefined &&
+            nvImage.global_max > nvImage.cal_max) {
+            nvImage.cal_max = nvImage.global_max;
+            widened = true;
+        }
+        if (nvImage.cal_min !== undefined &&
+            nvImage.global_min < nvImage.cal_min) {
+            nvImage.cal_min = nvImage.global_min;
+            widened = true;
+        }
+        return widened;
+    }
+    // ============================================================
+    // Event System (Browser-native EventTarget API)
+    // ============================================================
+    /**
+     * Add a type-safe event listener for OMEZarrNVImage events.
+     *
+     * @param type - Event type name
+     * @param listener - Event listener function
+     * @param options - Standard addEventListener options (once, signal, etc.)
+     *
+     * @example
+     * ```typescript
+     * image.addEventListener('resolutionChange', (event) => {
+     *   console.log('New level:', event.detail.currentLevel);
+     * });
+     *
+     * // One-time listener
+     * image.addEventListener('loadingComplete', handler, { once: true });
+     *
+     * // With AbortController
+     * const controller = new AbortController();
+     * image.addEventListener('loadingStart', handler, { signal: controller.signal });
+     * controller.abort(); // removes the listener
+     * ```
+     */
+    addEventListener(type, listener, options) {
+        this._eventTarget.addEventListener(type, listener, options);
+    }
+    /**
+     * Remove a type-safe event listener for OMEZarrNVImage events.
+     *
+     * @param type - Event type name
+     * @param listener - Event listener function to remove
+     * @param options - Standard removeEventListener options
+     */
+    removeEventListener(type, listener, options) {
+        this._eventTarget.removeEventListener(type, listener, options);
+    }
+    /**
+     * Internal helper to emit events.
+     * Catches and logs any errors from event listeners to prevent breaking execution.
+     */
+    _emitEvent(eventName, detail) {
+        try {
+            const event = new OMEZarrNVImageEvent(eventName, detail);
+            this._eventTarget.dispatchEvent(event);
+        }
+        catch (error) {
+            console.error(`Error in ${eventName} event listener:`, error);
+        }
+    }
+}
+//# sourceMappingURL=OMEZarrNVImage.js.map