@fideus-labs/fidnii 0.5.0 → 0.7.0

package/src/RegionCoalescer.ts

@@ -44,15 +44,17 @@ const SPATIAL_DIM_MAP: Record<string, 0 | 1 | 2> = {
  * each zarr dimension to the correct slice:
  * - `"z"`, `"y"`, `"x"` → sliced by the corresponding PixelRegion axis
  * - `"c"` (channel) → `null` (select all components)
- * - `"t"` (time) → `0` (first timepoint)
+ * - `"t"` (time) → `timeIndex` (selects a single time point)
  *
  * @param dims - Dimension names from NgffImage (e.g. `["y", "x", "c"]`)
  * @param region - The pixel region in `[z, y, x]` order
+ * @param timeIndex - Time point index to select (default: 0)
  * @returns Selection array matching the zarr dim order
  */
 export function buildSelection(
   dims: string[],
   region: PixelRegion,
+  timeIndex: number = 0,
 ): (zarr.Slice | number | null)[] {
   return dims.map((dim) => {
     const spatialIdx = SPATIAL_DIM_MAP[dim]
@@ -60,7 +62,7 @@ export function buildSelection(
       return zarr.slice(region.start[spatialIdx], region.end[spatialIdx])
     }
     if (dim === "c") return null // select all channels
-    if (dim === "t") return 0 // first timepoint
+    if (dim === "t") return timeIndex // select specified time point
     // Unknown dimension — select all to avoid data loss
     return null
   })
@@ -96,16 +98,18 @@ export class RegionCoalescer {
   }
 
   /**
-   * Generate a unique key for a request based on image path, level index, and region.
+   * Generate a unique key for a request based on image path, level index,
+   * region, and time index.
    */
   private makeKey(
     imagePath: string,
     levelIndex: number,
     region: PixelRegion,
+    timeIndex: number,
   ): string {
     const start = region.start.join(",")
     const end = region.end.join(",")
-    return `${imagePath}:${levelIndex}:${start}:${end}`
+    return `${imagePath}:${levelIndex}:${start}:${end}:t${timeIndex}`
   }
 
   /**
@@ -115,6 +119,8 @@ export class RegionCoalescer {
    * @param levelIndex - The resolution level index
    * @param region - The pixel region to fetch
    * @param requesterId - ID of the requester (e.g., 'zoom', 'crop-change', 'progressive-load')
+   * @param timeIndex - Time point index to fetch (default: 0)
+   * @param signal - Optional AbortSignal to cancel the fetch
    * @returns The fetched region data
    */
   async fetchRegion(
@@ -122,8 +128,10 @@ export class RegionCoalescer {
     levelIndex: number,
     region: PixelRegion,
     requesterId: string = "default",
+    timeIndex: number = 0,
+    signal?: AbortSignal,
   ): Promise<RegionFetchResult> {
-    const key = this.makeKey(ngffImage.data.path, levelIndex, region)
+    const key = this.makeKey(ngffImage.data.path, levelIndex, region, timeIndex)
 
     // Check if there's already a pending request for this data
     const existing = this.pending.get(key)
@@ -156,14 +164,21 @@ export class RegionCoalescer {
       // Build a dim-aware selection that maps the [z, y, x] PixelRegion
       // to the actual zarr dimension order. Non-spatial dims are handled:
       //   "c" (channel) → null (fetch all components)
-      //   "t" (time)    → 0 (first timepoint, reduces dimension)
-      const selection = buildSelection(ngffImage.dims, region)
+      //   "t" (time)    → timeIndex (selects single time point)
+      const selection = buildSelection(ngffImage.dims, region, timeIndex)
       // Pass the chunk cache to fizarrita's getWorker via zarrGet.
       // The `cache` option is available in @fideus-labs/fizarrita >=1.2.0.
-      const zarrOpts = this._cache
-        ? ({ cache: this._cache } as Record<string, unknown>)
-        : undefined
-      const result = await zarrGet(ngffImage.data, selection, zarrOpts)
+      // When an AbortSignal is provided, forward it through `opts` so
+      // that the underlying FetchStore passes it as `RequestInit.signal`,
+      // allowing in-flight HTTP requests to be cancelled.
+      const zarrOpts: Record<string, unknown> = {}
+      if (this._cache) zarrOpts.cache = this._cache
+      if (signal) zarrOpts.opts = { signal }
+      const result = await zarrGet(
+        ngffImage.data,
+        selection,
+        Object.keys(zarrOpts).length > 0 ? zarrOpts : undefined,
+      )
 
       const fetchResult: RegionFetchResult = {
         data: result.data as TypedArray,
@@ -190,6 +205,7 @@ export class RegionCoalescer {
    * @param levelIndex - The resolution level index
    * @param regions - Array of pixel regions to fetch
    * @param requesterId - ID of the requester
+   * @param timeIndex - Time point index to fetch (default: 0)
    * @returns Array of fetched region data
    */
   async fetchRegions(
@@ -197,10 +213,11 @@ export class RegionCoalescer {
     levelIndex: number,
     regions: PixelRegion[],
     requesterId: string = "default",
+    timeIndex: number = 0,
   ): Promise<RegionFetchResult[]> {
     return Promise.all(
       regions.map((region) =>
-        this.fetchRegion(ngffImage, levelIndex, region, requesterId),
+        this.fetchRegion(ngffImage, levelIndex, region, requesterId, timeIndex),
       ),
     )
   }
@@ -212,8 +229,9 @@ export class RegionCoalescer {
     ngffImage: NgffImage,
     levelIndex: number,
     region: PixelRegion,
+    timeIndex: number = 0,
   ): boolean {
-    const key = this.makeKey(ngffImage.data.path, levelIndex, region)
+    const key = this.makeKey(ngffImage.data.path, levelIndex, region, timeIndex)
     return this.pending.has(key)
   }
 
@@ -225,8 +243,9 @@ export class RegionCoalescer {
     ngffImage: NgffImage,
     levelIndex: number,
     region: PixelRegion,
+    timeIndex: number = 0,
   ): Set<string> | undefined {
-    const key = this.makeKey(ngffImage.data.path, levelIndex, region)
+    const key = this.makeKey(ngffImage.data.path, levelIndex, region, timeIndex)
     return this.pending.get(key)?.requesters
   }
 

package/src/events.ts

@@ -112,6 +112,24 @@ export interface OMEZarrNVImageEventMap {
     levelIndex: number
     trigger: PopulateTrigger
   }
+
+  /**
+   * Fired when the active time index changes.
+   *
+   * The `cached` flag indicates whether the frame was served instantly
+   * from the pre-fetch cache (`true`) or required a fresh zarr fetch
+   * (`false`).
+   */
+  timeChange: {
+    /** New time index (0-based) */
+    index: number
+    /** Physical time value at the new index */
+    timeValue: number
+    /** Previous time index */
+    previousIndex: number
+    /** `true` if the frame was served from the pre-fetch cache */
+    cached: boolean
+  }
 }
 
 /**

package/src/index.ts

@@ -38,8 +38,10 @@ export type { DeflatePool, TiffStoreOptions } from "@fideus-labs/fiff"
 export { TiffStore } from "@fideus-labs/fiff"
 // Re-export Methods enum so consumers can check isLabelImage or compare method values
 export { Methods } from "@fideus-labs/ngff-zarr"
-// Worker pool lifecycle (re-exported from ngff-zarr)
+// Worker pool lifecycle & configuration (re-exported from ngff-zarr)
 export {
+  config as ngffZarrConfig,
+  setWorkerPoolSize,
   terminateOmeroWorkerPool,
   terminateWorkerPool,
 } from "@fideus-labs/ngff-zarr/browser"
@@ -99,6 +101,7 @@ export {
 // Types
 export type {
   AttachedNiivueState,
+  CachedTimeFrame,
   ChannelInfo,
   ChunkAlignedRegion,
   ChunkCache,
@@ -110,6 +113,8 @@ export type {
   ResolutionSelection,
   SlabBufferState,
   SlabSliceType,
+  TimeAxisInfo,
+  TimeUnit,
   TypedArray,
   VolumeBounds,
   ZarrDtype,

package/src/types.ts

@@ -165,6 +165,24 @@ export interface OMEZarrNVImageOptions {
    * This option has no effect on 3D volumes (images with a `"z"` axis).
    */
   flipY2D?: boolean
+  /**
+   * Initial time index to display (default: 0, or `omero.defaultT` if available).
+   *
+   * Only relevant for datasets with a `"t"` (time) dimension. Ignored
+   * when the dataset has no time axis.
+   */
+  timeIndex?: number
+  /**
+   * Number of adjacent time frames to pre-fetch in each direction (default: 2).
+   *
+   * When the user navigates to time index `t`, frames
+   * `[t - timePrefetchCount, t + timePrefetchCount]` are fetched in the
+   * background so that subsequent scrubbing can swap frames instantly from
+   * the cache. Set to `0` to disable pre-fetching.
+   *
+   * Only relevant for datasets with a `"t"` (time) dimension.
+   */
+  timePrefetchCount?: number
 }
 
 /**
@@ -278,18 +296,8 @@ export interface AttachedNiivueState {
   nv: Niivue
   /** The current slice type of this NV instance */
   currentSliceType: SLICE_TYPE
-  /** Previous onLocationChange callback (to chain) */
-  previousOnLocationChange?: (location: unknown) => void
-  /** Previous onOptsChange callback (to chain) */
-  previousOnOptsChange?: (
-    propertyName: string,
-    newValue: unknown,
-    oldValue: unknown,
-  ) => void
-  /** Previous onMouseUp callback (to chain, for viewport-aware mode) */
-  previousOnMouseUp?: (data: unknown) => void
-  /** Previous onZoom3DChange callback (to chain, for viewport-aware mode) */
-  previousOnZoom3DChange?: (zoom: number) => void
+  /** AbortController for niivue addEventListener listeners (sliceTypeChange, locationChange) */
+  eventAbortController: AbortController
   /** AbortController for viewport-aware event listeners (wheel, etc.) */
   viewportAbortController?: AbortController
   /** AbortController for the 3D zoom override wheel listener */
@@ -328,6 +336,74 @@ export const NiftiDataType = {
 export type NiftiDataTypeCode =
   (typeof NiftiDataType)[keyof typeof NiftiDataType]
 
+/**
+ * Time units supported by OME-Zarr NGFF.
+ *
+ * Matches the UDUNITS-2 time units recognized by the OME-Zarr
+ * specification for the `"time"` axis type.
+ */
+export type TimeUnit =
+  | "attosecond"
+  | "centisecond"
+  | "day"
+  | "decisecond"
+  | "exasecond"
+  | "femtosecond"
+  | "gigasecond"
+  | "hectosecond"
+  | "hour"
+  | "kilosecond"
+  | "megasecond"
+  | "microsecond"
+  | "millisecond"
+  | "minute"
+  | "nanosecond"
+  | "petasecond"
+  | "picosecond"
+  | "second"
+  | "terasecond"
+  | "yoctosecond"
+  | "yottasecond"
+  | "zeptosecond"
+  | "zettasecond"
+
+/**
+ * Time axis metadata extracted from OME-Zarr multiscales.
+ *
+ * Present only when the dataset has a `"t"` dimension. Contains
+ * the number of time points, physical time step, and unit
+ * information needed for time navigation.
+ */
+export interface TimeAxisInfo {
+  /** Number of time points (from the zarr array shape along `"t"`) */
+  readonly count: number
+  /** Index of the `"t"` dimension in `NgffImage.dims` */
+  readonly dimIndex: number
+  /** Physical time step between adjacent indices (from `scale.t`) */
+  readonly step: number
+  /** Time origin offset (from `translation.t`) */
+  readonly origin: number
+  /** Time unit (e.g., `"second"`, `"millisecond"`), or `undefined` if not specified */
+  readonly unit: TimeUnit | undefined
+}
+
+/**
+ * A pre-fetched 3D frame ready for instant buffer swap.
+ *
+ * Used by the time frame cache to avoid re-fetching when scrubbing
+ * through adjacent time points.
+ */
+export interface CachedTimeFrame {
+  /** The typed array pixel data for this frame */
+  data: TypedArray
+  /** Spatial shape in `[z, y, x]` order */
+  shape: [number, number, number]
+  /** The resolution level this was fetched at */
+  levelIndex: number
+  /** The chunk-aligned pixel region this was fetched for */
+  region: ChunkAlignedRegion
+}
+
 /**
  * Information about a channel (component) dimension in the image.
  */