@fideus-labs/fidnii 0.5.0 → 0.7.0

package/dist/OMEZarrNVImage.js

@@ -13,8 +13,8 @@ import { RegionCoalescer } from "./RegionCoalescer.js";
 import { getChunkShape, getVolumeShape, select2DResolution, selectResolution, } from "./ResolutionSelector.js";
 import { getBytesPerPixel, getChannelInfo, getNiftiDataType, getRGBNiftiDataType, isRGBImage, NiftiDataType, needsRGBNormalization, parseZarritaDtype, } from "./types.js";
 import { affineToNiftiSrows, calculateWorldBounds, createAffineFromNgffImage, createAffineFromOMEZarr, } from "./utils/affine.js";
-import { worldToPixel } from "./utils/coordinates.js";
-import { applyOrientationToAffine, getOrientationMapping, getOrientationSigns, } from "./utils/orientation.js";
+import { worldToPixelAffine } from "./utils/coordinates.js";
+import { getOrientationMapping } from "./utils/orientation.js";
 import { boundsApproxEqual, computeViewportBounds2D, computeViewportBounds3D, } from "./ViewportBounds.js";
 const DEFAULT_MAX_PIXELS = 50_000_000;
 const DEFAULT_MAX_CACHE_ENTRIES = 200;
@@ -41,6 +41,29 @@ export class OMEZarrNVImage extends NVImage {
      * OMERO intensity windowing is skipped.
      */
     isLabelImage;
+    // ============================================================
+    // Colormap Override
+    // ============================================================
+    /**
+     * The continuous colormap name used for rendering.
+     *
+     * Overrides the NVImage setter so that changing the colormap on this
+     * image automatically propagates to all slab (2D slice) NVImages.
+     * Label images are unaffected — they use `setColormapLabel()` instead.
+     */
+    get colormap() {
+        return this._colormap;
+    }
+    set colormap(cm) {
+        // Use NVImage's setter (calls calMinMax + onColormapChange)
+        super.colormap = cm;
+        // Propagate to all existing slab NVImages
+        if (!this.isLabelImage) {
+            for (const slab of this._slabBuffers.values()) {
+                slab.nvImage.colormap = cm;
+            }
+        }
+    }
     /** Reference to NiiVue instance */
     niivue;
     /** Buffer manager for dynamically-sized pixel data */
@@ -78,8 +101,8 @@ export class OMEZarrNVImage extends NVImage {
     _volumeBounds;
     /** Current buffer bounds in world space (may differ from full volume when clipped) */
     _currentBufferBounds;
-    /** Previous clip plane change handler (to restore later) */
-    previousOnClipPlaneChange;
+    /** AbortController for the clip plane event listener on the primary NV */
+    _clipPlaneAbortController;
     /** Debounce delay for clip plane updates (ms) */
     clipPlaneDebounceMs;
     /** Timeout handle for debounced clip plane refetch */
@@ -98,6 +121,12 @@ export class OMEZarrNVImage extends NVImage {
     _eventTarget = new EventTarget();
     /** Pending populate request (latest wins - replaces any previous pending) */
     _pendingPopulateRequest = null;
+    /**
+     * AbortController for the in-flight `populateVolume` fetch.
+     * Aborted when a new `populateVolume` call supersedes the current one,
+     * allowing in-flight HTTP requests to be cancelled promptly.
+     */
+    _populateAbortController = null;
     /** Current populate trigger (set at start of populateVolume, used by events) */
     _currentPopulateTrigger = "initial";
     // ============================================================
@@ -129,6 +158,34 @@ export class OMEZarrNVImage extends NVImage {
     /** Per-slab AbortController to cancel in-flight progressive loads */
     _slabAbortControllers = new Map();
     // ============================================================
+    // Time Dimension State
+    // ============================================================
+    /**
+     * Time axis metadata, or `null` if the dataset has no `"t"` dimension.
+     * Populated during construction by inspecting `NgffImage.dims`.
+     */
+    _timeAxisInfo = null;
+    /** Current time index (0-based). Always 0 for non-time datasets. */
+    _timeIndex = 0;
+    /** Number of adjacent time frames to pre-fetch in each direction. */
+    _timePrefetchCount;
+    /**
+     * LRU cache of pre-fetched 3D time frames, keyed by time index.
+     * Only used when `_timeAxisInfo` is non-null.
+     */
+    _timeFrameCache;
+    /** Set of time indices currently being pre-fetched (for dedup). */
+    _prefetchingTimeIndices = new Set();
+    /** AbortController for the most recent pre-fetch batch. */
+    _prefetchAbortController = null;
+    /**
+     * Snapshot of the chunk-aligned region and resolution level used for
+     * the last successful 3D volume load. Used to serve cached time frames
+     * at the same spatial region. Cleared on clip plane / viewport / resolution
+     * changes.
+     */
+    _lastLoadedRegion = null;
+    // ============================================================
     // 3D Zoom Override
     // ============================================================
     /** Maximum 3D render zoom level for scroll-wheel zoom */
@@ -141,6 +198,8 @@ export class OMEZarrNVImage extends NVImage {
      * continuous zoom/pan interactions.
      */
     static VIEWPORT_DEBOUNCE_MS = 500;
+    /** Default number of adjacent time frames to pre-fetch. */
+    static DEFAULT_TIME_PREFETCH_COUNT = 2;
     /**
      * Private constructor. Use OMEZarrNVImage.create() for instantiation.
      */
@@ -181,6 +240,34 @@ export class OMEZarrNVImage extends NVImage {
         // Detect 2D images (no z axis) and store y-flip preference
         this._is2D = highResImage.dims.indexOf("z") === -1;
         this._flipY2D = options.flipY2D ?? true;
+        // Detect time dimension from the zarr axes
+        const tDimIndex = highResImage.dims.indexOf("t");
+        if (tDimIndex !== -1) {
+            const timeCount = highResImage.data.shape[tDimIndex];
+            if (timeCount > 0) {
+                // Look up time unit from axes metadata
+                const timeAxis = this.multiscales.metadata?.axes?.find((a) => a.name === "t");
+                this._timeAxisInfo = {
+                    count: timeCount,
+                    dimIndex: tDimIndex,
+                    step: highResImage.scale.t ?? 1,
+                    origin: highResImage.translation.t ?? 0,
+                    unit: timeAxis?.unit,
+                };
+            }
+        }
+        // Initialize time state
+        this._timePrefetchCount =
+            options.timePrefetchCount ?? OMEZarrNVImage.DEFAULT_TIME_PREFETCH_COUNT;
+        const defaultTimeIndex = options.timeIndex ?? 0;
+        this._timeIndex = this._timeAxisInfo
+            ? Math.max(0, Math.min(defaultTimeIndex, this._timeAxisInfo.count - 1))
+            : 0;
+        // Time frame cache: capacity = current frame + both directions + small buffer
+        const cacheCapacity = 2 * this._timePrefetchCount + 3;
+        this._timeFrameCache = new LRUCache({
+            max: cacheCapacity,
+        });
         // Calculate volume bounds from highest resolution for most accurate bounds.
         // Use the unadjusted affine (no orientation signs) because volume bounds
         // live in OME-Zarr world space and drive internal clip-plane / viewport math.
@@ -218,16 +305,12 @@ export class OMEZarrNVImage extends NVImage {
      */
     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);
-        };
+        // Listen for clip plane changes via the browser-native event API
+        const clipPlaneController = new AbortController();
+        image._clipPlaneAbortController = clipPlaneController;
+        image.niivue.addEventListener("clipPlaneChange", (e) => {
+            image.onNiivueClipPlaneChange(e.detail.clipPlane);
+        }, { signal: clipPlaneController.signal });
         // 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)
@@ -318,8 +401,14 @@ export class OMEZarrNVImage extends NVImage {
             }
             // Queue this request (no event - just queuing)
             this._pendingPopulateRequest = { skipPreview, trigger };
+            // Abort the in-flight fetch so the queued request runs sooner
+            this._populateAbortController?.abort();
             return;
         }
+        // Abort any lingering controller from a previous run (defensive)
+        this._populateAbortController?.abort();
+        const abortController = new AbortController();
+        this._populateAbortController = abortController;
         this.isLoading = true;
         this._currentPopulateTrigger = trigger;
         this._pendingPopulateRequest = null; // Clear any stale pending request
@@ -328,7 +417,9 @@ export class OMEZarrNVImage extends NVImage {
             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");
+                await this.loadResolutionLevel(lowestLevel, "preview", undefined, abortController.signal);
+                if (abortController.signal.aborted)
+                    return;
                 const prevLevel = this.currentLevelIndex;
                 this.currentLevelIndex = lowestLevel;
                 // Emit resolutionChange for preview load
@@ -342,7 +433,9 @@ export class OMEZarrNVImage extends NVImage {
                 }
             }
             // Final quality at target resolution
-            await this.loadResolutionLevel(this.targetLevelIndex, "target");
+            await this.loadResolutionLevel(this.targetLevelIndex, "target", undefined, abortController.signal);
+            if (abortController.signal.aborted)
+                return;
             const prevLevelBeforeTarget = this.currentLevelIndex;
             this.currentLevelIndex = this.targetLevelIndex;
             // Emit resolutionChange for target load
@@ -364,6 +457,7 @@ export class OMEZarrNVImage extends NVImage {
         }
         finally {
             this.isLoading = false;
+            this._populateAbortController = null;
             this.handlePendingPopulateRequest();
         }
     }
@@ -385,6 +479,11 @@ export class OMEZarrNVImage extends NVImage {
             targetLevel: this.targetLevelIndex,
             trigger: this._currentPopulateTrigger,
         });
+        // Kick off pre-fetching of adjacent time frames now that we have a
+        // stable spatial region + resolution level.
+        if (this._timeAxisInfo && this._timeAxisInfo.count > 1) {
+            this._prefetchAdjacentFrames(this._timeIndex);
+        }
     }
     /**
      * Load data at a specific resolution level.
@@ -397,8 +496,11 @@ export class OMEZarrNVImage extends NVImage {
      *
      * @param levelIndex - Resolution level index
      * @param requesterId - ID for request coalescing
+     * @param timeIndex - Time point index to fetch (defaults to `this._timeIndex`)
+     * @param signal - Optional AbortSignal to cancel the fetch
      */
-    async loadResolutionLevel(levelIndex, requesterId) {
+    async loadResolutionLevel(levelIndex, requesterId, timeIndex, signal) {
+        const effectiveTimeIndex = timeIndex ?? this._timeIndex;
         // Emit loadingStart event
         this._emitEvent("loadingStart", {
             levelIndex,
@@ -419,7 +521,7 @@ export class OMEZarrNVImage extends NVImage {
             start: alignedRegion.chunkAlignedStart,
             end: alignedRegion.chunkAlignedEnd,
         };
-        const result = await this.coalescer.fetchRegion(ngffImage, levelIndex, fetchRegion, requesterId);
+        const result = await this.coalescer.fetchRegion(ngffImage, levelIndex, fetchRegion, requesterId, effectiveTimeIndex, signal);
         // Resize buffer to match fetched data exactly (no upsampling!)
         const targetData = this.bufferManager.resize(fetchedShape);
         // For non-uint8 RGB/RGBA, we need OMERO metadata *before* copying
@@ -442,6 +544,9 @@ export class OMEZarrNVImage extends NVImage {
         this.img = this.bufferManager.getTypedArray();
         // Update NVImage header with correct dimensions and transforms
         this.updateHeaderForRegion(ngffImage, alignedRegion, fetchedShape);
+        // Snapshot the loaded region so time frame pre-fetch uses the same
+        // spatial region / resolution level.
+        this._lastLoadedRegion = { region: alignedRegion, levelIndex };
         if (this.isLabelImage) {
             // Label images: apply a discrete colormap instead of OMERO windowing
             this._applyLabelColormap(this, result.data);
@@ -508,27 +613,36 @@ export class OMEZarrNVImage extends NVImage {
             1,
             1,
         ];
-        // Build the unadjusted affine (no orientation signs) and offset it
-        // to the loaded region. Buffer bounds use this OME-Zarr-space affine
-        // for internal clip-plane / viewport math.
+        // Compute buffer bounds in un-oriented OME-Zarr world space.
+        // These drive clip-plane / viewport math and must stay un-oriented.
         const regionStart = region.chunkAlignedStart;
-        const affine = createAffineFromOMEZarr(ngffImage.scale, ngffImage.translation);
-        // 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 current buffer bounds in OME-Zarr world space
+        const translation = ngffImage.translation;
+        const tx = (translation.x ?? translation.X ?? 0) + regionStart[2] * sx;
+        const ty = (translation.y ?? translation.Y ?? 0) + regionStart[1] * sy;
+        const tz = (translation.z ?? translation.Z ?? 0) + regionStart[0] * sz;
         this._currentBufferBounds = {
-            min: [affine[12], affine[13], affine[14]],
+            min: [tx, ty, tz],
             max: [
-                affine[12] + fetchedShape[2] * sx,
-                affine[13] + fetchedShape[1] * sy,
-                affine[14] + fetchedShape[0] * sz,
+                tx + fetchedShape[2] * sx,
+                ty + fetchedShape[1] * sy,
+                tz + fetchedShape[0] * sz,
             ],
         };
-        // Apply orientation signs so the NIfTI affine encodes anatomical
-        // direction for NiiVue's calculateRAS()
-        applyOrientationToAffine(affine, ngffImage.axesOrientations);
+        // Build the fully oriented affine (including orientation permutation
+        // and sign flips), then apply the region offset in world space.
+        // The offset goes through the oriented 3x3 rotation matrix so it
+        // lands on the correct world axis even when NGFF axes are permuted.
+        const affine = createAffineFromNgffImage(ngffImage);
+        // regionStart is [z, y, x]; affine columns map NIfTI [i=x, j=y, k=z]
+        const offsetX = regionStart[2]; // NIfTI i = NGFF x
+        const offsetY = regionStart[1]; // NIfTI j = NGFF y
+        const offsetZ = regionStart[0]; // NIfTI k = NGFF z
+        affine[12] +=
+            affine[0] * offsetX + affine[4] * offsetY + affine[8] * offsetZ;
+        affine[13] +=
+            affine[1] * offsetX + affine[5] * offsetY + affine[9] * offsetZ;
+        affine[14] +=
+            affine[2] * offsetX + affine[6] * offsetY + affine[10] * offsetZ;
         // For 2D images, flip y so NiiVue's calculateRAS() accounts for
         // top-to-bottom pixel storage order. We shift the translation so
         // the last row maps to where the first row was, then negate the
@@ -786,6 +900,8 @@ export class OMEZarrNVImage extends NVImage {
         // Visual clipping is handled by NiiVue clip planes (already updated in setClipPlanes)
         if (newTargetLevel !== this.targetLevelIndex) {
             this.targetLevelIndex = newTargetLevel;
+            // Spatial region changed — cached time frames are stale
+            this._invalidateTimeFrameCache();
             this.populateVolume(true, "clipPlanesChanged"); // Skip preview for clip plane updates
         }
         // Emit clipPlanesChange event (after debounce)
@@ -905,6 +1021,202 @@ export class OMEZarrNVImage extends NVImage {
         };
     }
     // ============================================================
+    // Time Navigation
+    // ============================================================
+    /**
+     * Time axis metadata, or `null` if the dataset has no `"t"` dimension.
+     *
+     * @example
+     * ```ts
+     * const info = image.timeAxisInfo
+     * if (info) {
+     *   console.log(`${info.count} time points, step=${info.step} ${info.unit}`)
+     * }
+     * ```
+     */
+    get timeAxisInfo() {
+        return this._timeAxisInfo;
+    }
+    /**
+     * Total number of time points.
+     * Returns 1 for datasets without a `"t"` dimension.
+     */
+    get timeCount() {
+        return this._timeAxisInfo?.count ?? 1;
+    }
+    /**
+     * Current time index (0-based).
+     * Always 0 for datasets without a `"t"` dimension.
+     */
+    get timeIndex() {
+        return this._timeIndex;
+    }
+    /**
+     * Compute the physical time value at a given index.
+     *
+     * @param index - Time index (0-based)
+     * @returns Physical time value (`origin + index * step`)
+     */
+    getTimeValue(index) {
+        if (!this._timeAxisInfo)
+            return 0;
+        return this._timeAxisInfo.origin + index * this._timeAxisInfo.step;
+    }
+    /**
+     * Set the active time index and reload the volume.
+     *
+     * If the requested frame is in the pre-fetch cache, the buffer is
+     * swapped instantly without a network fetch. Otherwise, the frame is
+     * loaded from the zarr store at the current resolution level and
+     * spatial region.
+     *
+     * After the frame is loaded, adjacent frames are pre-fetched in the
+     * background so subsequent scrubbing can serve frames from cache.
+     *
+     * @param index - Time index (0-based)
+     * @throws If `index` is out of range `[0, timeCount)`
+     *
+     * @example
+     * ```ts
+     * await image.setTimeIndex(5)
+     * image.addEventListener('timeChange', (e) => {
+     *   console.log(`Frame ${e.detail.index}, cached=${e.detail.cached}`)
+     * })
+     * ```
+     */
+    async setTimeIndex(index) {
+        if (!this._timeAxisInfo) {
+            if (index !== 0) {
+                throw new Error(`Cannot set time index ${index}: dataset has no time dimension`);
+            }
+            return;
+        }
+        if (index < 0 || index >= this._timeAxisInfo.count) {
+            throw new Error(`Time index ${index} out of range [0, ${this._timeAxisInfo.count})`);
+        }
+        const previousIndex = this._timeIndex;
+        if (index === previousIndex)
+            return;
+        this._timeIndex = index;
+        // Try the pre-fetch cache first
+        const cached = this._timeFrameCache.get(index);
+        if (cached && cached.levelIndex === this.currentLevelIndex) {
+            // Cache hit: instant buffer swap
+            const targetData = this.bufferManager.resize(cached.shape);
+            targetData.set(cached.data);
+            this.img = this.bufferManager.getTypedArray();
+            this.updateHeaderForRegion(this.multiscales.images[cached.levelIndex], cached.region, cached.shape);
+            this.global_min = undefined;
+            this.niivue.updateGLVolume();
+            this._emitEvent("timeChange", {
+                index,
+                timeValue: this.getTimeValue(index),
+                previousIndex,
+                cached: true,
+            });
+        }
+        else {
+            // Cache miss: full load at current resolution + region
+            await this.populateVolume(true, "initial");
+            this._emitEvent("timeChange", {
+                index,
+                timeValue: this.getTimeValue(index),
+                previousIndex,
+                cached: false,
+            });
+        }
+        // Pre-fetch adjacent frames in the background
+        this._prefetchAdjacentFrames(index);
+    }
+    /**
+     * Clear the pre-fetched time frame cache.
+     *
+     * Called internally when the spatial region or resolution changes
+     * (clip planes, viewport, resolution level), since cached frames
+     * were fetched for the previous region and are no longer valid.
+     */
+    _invalidateTimeFrameCache() {
+        this._timeFrameCache.clear();
+        this._lastLoadedRegion = null;
+        // Cancel any in-flight pre-fetches
+        if (this._prefetchAbortController) {
+            this._prefetchAbortController.abort();
+            this._prefetchAbortController = null;
+        }
+        this._prefetchingTimeIndices.clear();
+    }
+    /**
+     * Pre-fetch adjacent time frames in the background.
+     *
+     * Fetches frames `[index - N, index + N]` (clamped to valid range)
+     * at the current resolution level and spatial region. Already-cached
+     * and currently-in-flight indices are skipped.
+     *
+     * @param centerIndex - The time index to pre-fetch around
+     */
+    _prefetchAdjacentFrames(centerIndex) {
+        if (!this._timeAxisInfo || this._timePrefetchCount <= 0)
+            return;
+        if (!this._lastLoadedRegion)
+            return;
+        // Cancel any previous pre-fetch batch
+        if (this._prefetchAbortController) {
+            this._prefetchAbortController.abort();
+        }
+        const abortController = new AbortController();
+        this._prefetchAbortController = abortController;
+        const { region, levelIndex } = this._lastLoadedRegion;
+        const ngffImage = this.multiscales.images[levelIndex];
+        // Collect indices to pre-fetch
+        const indices = [];
+        for (let delta = 1; delta <= this._timePrefetchCount; delta++) {
+            const before = centerIndex - delta;
+            const after = centerIndex + delta;
+            if (before >= 0)
+                indices.push(before);
+            if (after < this._timeAxisInfo.count)
+                indices.push(after);
+        }
+        // Filter out already cached and in-flight indices
+        const toFetch = indices.filter((i) => !this._timeFrameCache.has(i) && !this._prefetchingTimeIndices.has(i));
+        if (toFetch.length === 0)
+            return;
+        const fetchRegion = {
+            start: region.chunkAlignedStart,
+            end: region.chunkAlignedEnd,
+        };
+        // Fire-and-forget pre-fetches
+        for (const timeIdx of toFetch) {
+            if (abortController.signal.aborted)
+                break;
+            this._prefetchingTimeIndices.add(timeIdx);
+            void this.coalescer
+                .fetchRegion(ngffImage, levelIndex, fetchRegion, `prefetch-t${timeIdx}`, timeIdx)
+                .then((result) => {
+                if (abortController.signal.aborted)
+                    return;
+                const shape = [
+                    region.chunkAlignedEnd[0] - region.chunkAlignedStart[0],
+                    region.chunkAlignedEnd[1] - region.chunkAlignedStart[1],
+                    region.chunkAlignedEnd[2] - region.chunkAlignedStart[2],
+                ];
+                // Store a copy so the original fetch result can be GC'd
+                this._timeFrameCache.set(timeIdx, {
+                    data: result.data.slice(),
+                    shape,
+                    levelIndex,
+                    region,
+                });
+            })
+                .catch(() => {
+                // Silently ignore pre-fetch failures (non-critical)
+            })
+                .finally(() => {
+                this._prefetchingTimeIndices.delete(timeIdx);
+            });
+        }
+    }
+    // ============================================================
     // Viewport-Aware Resolution
     // ============================================================
     /**
@@ -944,6 +1256,8 @@ export class OMEZarrNVImage extends NVImage {
             const selection = selectResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds);
             if (selection.levelIndex !== this.targetLevelIndex) {
                 this.targetLevelIndex = selection.levelIndex;
+                // Spatial region changed — cached time frames are stale
+                this._invalidateTimeFrameCache();
                 this.populateVolume(true, "viewportChanged");
             }
             // Also reload slabs without viewport constraint
@@ -969,49 +1283,33 @@ export class OMEZarrNVImage extends NVImage {
         };
     }
     /**
-     * Hook viewport events (onMouseUp, onZoom3DChange, wheel) on a NV instance.
+     * Hook viewport events (mouseUp, zoom3DChange, wheel) on a NV instance.
+     * All listeners share a single AbortController so they can be torn down
+     * together via {@link _unhookViewportEvents}.
      */
     _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;
+        const signal = controller.signal;
+        // Detect end of mouse/touch interaction
+        nv.addEventListener("mouseUp", () => {
+            this._handleViewportInteractionEnd(nv);
+        }, { signal });
+        // Detect 3D zoom level changes
+        nv.addEventListener("zoom3DChange", () => {
+            this._handleViewportInteractionEnd(nv);
+        }, { signal });
+        // Detect scroll-wheel zoom on the canvas
         if (nv.canvas) {
             nv.canvas.addEventListener("wheel", () => {
                 this._handleViewportInteractionEnd(nv);
-            }, { signal: controller.signal, passive: true });
+            }, { 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
+    _unhookViewportEvents(_nv, state) {
         if (state.viewportAbortController) {
             state.viewportAbortController.abort();
             state.viewportAbortController = undefined;
@@ -1175,6 +1473,8 @@ export class OMEZarrNVImage extends NVImage {
             const selection = selectResolution(this.multiscales, this.maxPixels, this._clipPlanes, this._volumeBounds, this._viewportBounds3D ?? undefined);
             if (selection.levelIndex !== this.targetLevelIndex) {
                 this.targetLevelIndex = selection.levelIndex;
+                // Spatial region changed — cached time frames are stale
+                this._invalidateTimeFrameCache();
                 this.populateVolume(true, "viewportChanged");
             }
         }
@@ -1227,10 +1527,65 @@ export class OMEZarrNVImage extends NVImage {
         return this.isLoading;
     }
     /**
-     * Wait for all pending fetches to complete.
+     * Wait for all async work to settle: debounced timers (clip plane
+     * refetch, viewport update, slab reload), the main `populateVolume`
+     * pipeline, all slab loads, and in-flight coalescer fetches.
+     *
+     * The method polls in a loop because debounced timers may fire while
+     * we are waiting, triggering new loads. It only resolves once every
+     * source of async work is idle simultaneously.
      */
     async waitForIdle() {
-        await this.coalescer.onIdle();
+        // Polling interval for active-load checks (ms).
+        const POLL_MS = 50;
+        while (true) {
+            // ---- Debounced timers ----
+            // Wait for pending debounce timers to fire (and potentially
+            // trigger new loads) before checking load state.
+            if (this.clipPlaneRefetchTimeout !== null) {
+                await new Promise((r) => setTimeout(r, this.clipPlaneDebounceMs + POLL_MS));
+                continue;
+            }
+            if (this._viewportUpdateTimeout !== null) {
+                await new Promise((r) => setTimeout(r, OMEZarrNVImage.VIEWPORT_DEBOUNCE_MS + POLL_MS));
+                continue;
+            }
+            if (this._slabReloadTimeouts.size > 0) {
+                // Slab reload debounce is 100 ms (hardcoded in
+                // _debouncedSlabReload).
+                await new Promise((r) => setTimeout(r, 100 + POLL_MS));
+                continue;
+            }
+            // ---- Active loads ----
+            if (this.isLoading || this._pendingPopulateRequest !== null) {
+                await new Promise((r) => setTimeout(r, POLL_MS));
+                continue;
+            }
+            let slabBusy = false;
+            for (const slabState of this._slabBuffers.values()) {
+                if (slabState.isLoading || slabState.pendingReload !== null) {
+                    slabBusy = true;
+                    break;
+                }
+            }
+            if (slabBusy) {
+                await new Promise((r) => setTimeout(r, POLL_MS));
+                continue;
+            }
+            // ---- In-flight fetches ----
+            await this.coalescer.onIdle();
+            // ---- Convergence check ----
+            // A debounce timer or pending request may have appeared while we
+            // were awaiting the coalescer. If so, loop again.
+            const stillBusy = this.isLoading ||
+                this._pendingPopulateRequest !== null ||
+                this.clipPlaneRefetchTimeout !== null ||
+                this._viewportUpdateTimeout !== null ||
+                this._slabReloadTimeouts.size > 0 ||
+                Array.from(this._slabBuffers.values()).some((s) => s.isLoading || s.pendingReload !== null);
+            if (!stillBusy)
+                break;
+        }
     }
     // ============================================================
     // OMERO Metadata (Visualization Parameters)
@@ -1305,9 +1660,10 @@ export class OMEZarrNVImage extends NVImage {
     /**
      * 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.
+     * The image auto-detects the NV's current slice type and uses
+     * `addEventListener('sliceTypeChange', ...)` to track mode changes and
+     * `addEventListener('locationChange', ...)` to track crosshair/slice
+     * position changes via Niivue's browser-native EventTarget API.
      *
      * 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
@@ -1318,30 +1674,21 @@ export class OMEZarrNVImage extends NVImage {
     attachNiivue(nv) {
         if (this._attachedNiivues.has(nv))
             return; // Already attached
+        const eventAbortController = new AbortController();
         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);
+            eventAbortController,
         };
+        const signal = eventAbortController.signal;
+        // Listen for slice type changes via the browser-native event API
+        nv.addEventListener("sliceTypeChange", (e) => {
+            this._handleSliceTypeChange(nv, e.detail.sliceType);
+        }, { signal });
+        // Listen for crosshair/slice position changes
+        nv.addEventListener("locationChange", (e) => {
+            this._handleLocationChange(nv, e.detail);
+        }, { signal });
         this._attachedNiivues.set(nv, state);
         // Hook viewport events if viewport-aware mode is already enabled
         if (this._viewportAwareEnabled) {
@@ -1356,7 +1703,9 @@ export class OMEZarrNVImage extends NVImage {
         }
     }
     /**
-     * Detach a Niivue instance, restoring its original callbacks.
+     * Detach a Niivue instance, removing all event listeners registered by this
+     * image (viewport, zoom-override, slice-type, location, and clip-plane
+     * listeners are all torn down via their respective `AbortController`s).
      *
      * @param nv - The Niivue instance to detach
      */
@@ -1368,10 +1717,13 @@ export class OMEZarrNVImage extends NVImage {
         this._unhookViewportEvents(nv, state);
         // Unhook 3D zoom override
         this._unhookZoomOverride(nv, state);
-        // Restore original callbacks
-        nv.onLocationChange = state.previousOnLocationChange ?? (() => { });
-        nv.onOptsChange = (state.previousOnOptsChange ??
-            (() => { }));
+        // Remove niivue event listeners (sliceTypeChange, locationChange)
+        state.eventAbortController.abort();
+        // If detaching the primary NV, also remove the clip plane listener
+        if (nv === this.niivue && this._clipPlaneAbortController) {
+            this._clipPlaneAbortController.abort();
+            this._clipPlaneAbortController = undefined;
+        }
         this._attachedNiivues.delete(nv);
     }
     /**
@@ -1414,21 +1766,43 @@ export class OMEZarrNVImage extends NVImage {
             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)
+     * Get the NGFF array axis index that is orthogonal to a slice plane.
+     *
+     * NiiVue slice types refer to anatomical planes:
+     * - Axial: perpendicular to S/I (physicalRow 2)
+     * - Coronal: perpendicular to A/P (physicalRow 1)
+     * - Sagittal: perpendicular to R/L (physicalRow 0)
+     *
+     * When the dataset has permuted axes (e.g. NGFF y encodes S/I instead
+     * of A/P), the NGFF array axis that is orthogonal to a given anatomical
+     * plane differs from the default z/y/x mapping. This method uses the
+     * orientation metadata to find the correct NGFF axis.
+     *
+     * Returns index in [z, y, x] order (0=z, 1=y, 2=x).
      */
     _getOrthogonalAxis(sliceType) {
+        // Which physical (RAS) row is perpendicular to this slice plane?
+        let targetRow;
         switch (sliceType) {
             case SLICE_TYPE.AXIAL:
-                return 0; // Z
+                targetRow = 2; // S/I
+                break;
             case SLICE_TYPE.CORONAL:
-                return 1; // Y
+                targetRow = 1; // A/P
+                break;
             case SLICE_TYPE.SAGITTAL:
-                return 2; // X
+                targetRow = 0; // R/L
+                break;
         }
+        const orientations = this.multiscales.images[0]?.axesOrientations;
+        const mapping = getOrientationMapping(orientations);
+        // Find which NGFF axis maps to targetRow.
+        // mapping.x/y/z have physicalRow; NGFF indices: x=2, y=1, z=0
+        if (mapping.z.physicalRow === targetRow)
+            return 0;
+        if (mapping.y.physicalRow === targetRow)
+            return 1;
+        return 2;
     }
     /**
      * Handle a slice type change on an attached Niivue instance.
@@ -1477,9 +1851,12 @@ export class OMEZarrNVImage extends NVImage {
         catch {
             return; // Can't convert coordinates yet
         }
-        // Convert world to pixel at the slab's current resolution level
+        // Convert world to pixel at the slab's current resolution level.
+        // Must use the full oriented affine (not the naive scale+translation)
+        // because worldCoord is in oriented (NIfTI RAS) space.
         const ngffImage = this.multiscales.images[slabState.levelIndex];
-        const pixelCoord = worldToPixel(worldCoord, ngffImage);
+        const orientedAffine = createAffineFromNgffImage(ngffImage);
+        const pixelCoord = worldToPixelAffine(worldCoord, orientedAffine);
         // Check the orthogonal axis
         const orthAxis = this._getOrthogonalAxis(sliceType);
         const pixelPos = pixelCoord[orthAxis];
@@ -1514,10 +1891,11 @@ export class OMEZarrNVImage extends NVImage {
             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.
+        // Capture the crosshair world position BEFORE swapping volumes.
+        // frac2mm() uses the current volume's affine, so it must run while
+        // the 3D (or previous slab) NVImage is still attached. After the swap,
+        // the 1×1×1 placeholder's identity affine would produce incorrect
+        // coordinates.
         let worldCoord;
         try {
             const crosshairPos = nv.scene?.crosshairPos;
@@ -1546,6 +1924,8 @@ export class OMEZarrNVImage extends NVImage {
                 (this._volumeBounds.min[2] + this._volumeBounds.max[2]) / 2,
             ];
         }
+        // Swap the slab's NVImage into this NV instance (after capturing coords)
+        this._swapVolumeInNiivue(nv, slabState.nvImage);
         void this._loadSlab(sliceType, worldCoord, "initial").catch((err) => {
             console.error(`[fidnii] Error loading slab for ${SLICE_TYPE[sliceType]}:`, err);
         });
@@ -1581,7 +1961,7 @@ export class OMEZarrNVImage extends NVImage {
         nvImage.name = `${this.name ?? "OME-Zarr"} [${SLICE_TYPE[sliceType]}]`;
         nvImage.img = bufferManager.resize([1, 1, 1]);
         if (!this.isLabelImage) {
-            nvImage._colormap = "gray";
+            nvImage._colormap = this._colormap || "gray";
         }
         nvImage._opacity = 1.0;
         // Select initial resolution using 2D pixel budget
@@ -1744,8 +2124,11 @@ export class OMEZarrNVImage extends NVImage {
         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);
+        // Convert world position to pixel position at this level.
+        // Must use the full oriented affine because worldCoord is in oriented
+        // (NIfTI RAS) space, not raw NGFF scale+translation space.
+        const orientedAffine = createAffineFromNgffImage(ngffImage);
+        const pixelCoord = worldToPixelAffine(worldCoord, orientedAffine);
         const orthPixel = pixelCoord[orthAxis];
         // Find the chunk-aligned slab in the orthogonal axis
         const chunkSize = chunkShape[orthAxis];
@@ -1778,7 +2161,7 @@ export class OMEZarrNVImage extends NVImage {
         ];
         // Fetch the data
         const fetchRegion = { start: fetchStart, end: fetchEnd };
-        const result = await this.coalescer.fetchRegion(ngffImage, levelIndex, fetchRegion, `slab-${SLICE_TYPE[sliceType]}-${levelIndex}`);
+        const result = await this.coalescer.fetchRegion(ngffImage, levelIndex, fetchRegion, `slab-${SLICE_TYPE[sliceType]}-${levelIndex}`, this._timeIndex);
         // Resize buffer and copy data
         const targetData = slabState.bufferManager.resize(fetchedShape);
         const normalize = needsRGBNormalization(ngffImage, this.dtype);
@@ -1881,17 +2264,28 @@ export class OMEZarrNVImage extends NVImage {
             1,
             1,
         ];
-        // Build affine with orientation signs, then offset for region start.
-        // Use the original unoriented scale values with orientation signs for
-        // the translation offset calculation. This ensures correctness even when
-        // axes are permuted (where affine diagonal may be zero).
+        // Build the fully oriented affine (including orientation permutation
+        // and sign flips), then apply the region offset in world space.
+        //
+        // The offset must be applied AFTER orientation because the fetch region
+        // start is in NGFF voxel space [z, y, x], and the oriented 3x3 rotation
+        // matrix is needed to transform that voxel offset into world coordinates.
+        // Previously, the offset was applied before orientation which broke when
+        // NGFF axes were permuted (e.g. NGFF z → physical A/P axis).
         const affine = createAffineFromNgffImage(ngffImage);
-        // Get orientation signs to apply to the offset calculation
-        const signs = getOrientationSigns(ngffImage.axesOrientations);
-        // Adjust translation for region offset (fetchStart is [z, y, x])
-        affine[12] += fetchStart[2] * signs.x * sx; // x offset (orientation-aware)
-        affine[13] += fetchStart[1] * signs.y * sy; // y offset (orientation-aware)
-        affine[14] += fetchStart[0] * signs.z * sz; // z offset (orientation-aware)
+        // Transform the NGFF voxel offset through the oriented 3x3 rotation.
+        // fetchStart is [z, y, x]; affine columns map NIfTI [i=x, j=y, k=z]
+        // to world, so we need offset in NIfTI [x, y, z] order.
+        const offsetX = fetchStart[2]; // NIfTI i = NGFF x
+        const offsetY = fetchStart[1]; // NIfTI j = NGFF y
+        const offsetZ = fetchStart[0]; // NIfTI k = NGFF z
+        // Multiply the 3x3 rotation by the offset vector and add to translation
+        affine[12] +=
+            affine[0] * offsetX + affine[4] * offsetY + affine[8] * offsetZ;
+        affine[13] +=
+            affine[1] * offsetX + affine[5] * offsetY + affine[9] * offsetZ;
+        affine[14] +=
+            affine[2] * offsetX + affine[6] * offsetY + affine[10] * offsetZ;
         // For 2D images, flip y before normalization (composes with orientation)
         if (this._flipY2D && this._is2D) {
             // Get the y axis orientation mapping to find where the y scale is stored