@fideus-labs/fidnii 0.2.0 → 0.3.0

package/src/BufferManager.ts

@@ -10,6 +10,18 @@ import { getBytesPerPixel, getTypedArrayConstructor } from "./types.js"
  * The buffer is resized to match the fetched data dimensions exactly.
  * Memory is reused when possible to avoid unnecessary allocations.
  *
+ * For multi-component images (RGB/RGBA), `componentsPerVoxel` controls
+ * how many scalar elements each spatial voxel occupies. The buffer is
+ * sized to hold `spatialPixels * componentsPerVoxel` elements, and the
+ * typed array view spans all of them. Spatial dimensions (`[z, y, x]`)
+ * track only the spatial extent; the component count is a fixed
+ * multiplier on the element count.
+ *
+ * When the source dtype is not uint8 and `componentsPerVoxel > 1`
+ * (non-uint8 RGB/RGBA), the buffer stores **uint8** data because NiiVue
+ * only supports `DT_RGB24` / `DT_RGBA32` (uint8-per-channel). The raw
+ * data is normalized to uint8 externally before being written here.
+ *
  * Memory reuse strategy:
  * - Reuse buffer if newSize <= currentCapacity
  * - Reallocate if newSize > currentCapacity OR newSize < 25% of currentCapacity
@@ -22,17 +34,48 @@ export class BufferManager {
   private readonly bytesPerPixel: number
   private readonly dtype: ZarrDtype
 
+  /**
+   * Number of scalar components per spatial voxel.
+   * 1 for scalar images, 3 for RGB, 4 for RGBA.
+   */
+  readonly componentsPerVoxel: number
+
+  /**
+   * Whether this buffer stores normalized uint8 data for a non-uint8
+   * RGB/RGBA source. When `true`, {@link getTypedArray} returns a
+   * `Uint8Array` and `bytesPerPixel` is 1, regardless of the source
+   * dtype.
+   */
+  readonly isNormalizedRGB: boolean
+
   /**
    * Create a new BufferManager.
    *
    * @param maxPixels - Maximum number of pixels allowed (budget)
    * @param dtype - Data type for the buffer
+   * @param componentsPerVoxel - Number of components per spatial voxel
+   *   (default: 1; pass 3 for RGB, 4 for RGBA)
    */
-  constructor(maxPixels: number, dtype: ZarrDtype) {
+  constructor(
+    maxPixels: number,
+    dtype: ZarrDtype,
+    componentsPerVoxel: number = 1,
+  ) {
     this.maxPixels = maxPixels
     this.dtype = dtype
-    this.TypedArrayCtor = getTypedArrayConstructor(dtype)
-    this.bytesPerPixel = getBytesPerPixel(dtype)
+    this.componentsPerVoxel = componentsPerVoxel
+
+    // Non-uint8 RGB/RGBA: the output buffer stores normalized uint8 data
+    // because NiiVue only supports uint8-per-channel color rendering.
+    this.isNormalizedRGB = componentsPerVoxel > 1 && dtype !== "uint8"
+
+    if (this.isNormalizedRGB) {
+      this.TypedArrayCtor = Uint8Array
+      this.bytesPerPixel = 1
+    } else {
+      this.TypedArrayCtor = getTypedArrayConstructor(dtype)
+      this.bytesPerPixel = getBytesPerPixel(dtype)
+    }
 
     // Initialize with empty buffer - will be allocated on first resize
     this.currentDimensions = [0, 0, 0]
@@ -53,27 +96,30 @@ export class BufferManager {
    * @returns TypedArray view over the (possibly new) buffer
    */
   resize(dimensions: [number, number, number]): TypedArray {
-    const requiredPixels = dimensions[0] * dimensions[1] * dimensions[2]
+    const spatialPixels = dimensions[0] * dimensions[1] * dimensions[2]
 
-    if (requiredPixels > this.maxPixels) {
+    if (spatialPixels > this.maxPixels) {
       console.warn(
         `[fidnii] BufferManager: Requested dimensions [${dimensions.join(
           ", ",
-        )}] = ${requiredPixels} pixels exceeds maxPixels (${this.maxPixels}). ` +
+        )}] = ${spatialPixels} pixels exceeds maxPixels (${this.maxPixels}). ` +
           `Proceeding anyway (likely at lowest resolution).`,
       )
     }
 
-    const currentCapacityPixels = this.buffer.byteLength / this.bytesPerPixel
+    // Total elements = spatial pixels × components per voxel
+    const requiredElements = spatialPixels * this.componentsPerVoxel
+    const currentCapacityElements = this.buffer.byteLength / this.bytesPerPixel
     const utilizationRatio =
-      currentCapacityPixels > 0 ? requiredPixels / currentCapacityPixels : 0
+      currentCapacityElements > 0
+        ? requiredElements / currentCapacityElements
+        : 0
 
     const needsReallocation =
-      requiredPixels > currentCapacityPixels || utilizationRatio < 0.25
+      requiredElements > currentCapacityElements || utilizationRatio < 0.25
 
     if (needsReallocation) {
-      // Allocate new buffer
-      const newByteLength = requiredPixels * this.bytesPerPixel
+      const newByteLength = requiredElements * this.bytesPerPixel
       this.buffer = new ArrayBuffer(newByteLength)
     }
 
@@ -91,14 +137,19 @@ export class BufferManager {
   /**
    * Get a typed array view over the current buffer region.
    *
-   * The view is sized to match currentDimensions, not the full buffer capacity.
+   * The view is sized to match `spatialPixels × componentsPerVoxel`,
+   * not the full buffer capacity.
    */
   getTypedArray(): TypedArray {
-    const pixelCount =
+    const spatialPixels =
       this.currentDimensions[0] *
       this.currentDimensions[1] *
       this.currentDimensions[2]
-    return new this.TypedArrayCtor(this.buffer, 0, pixelCount)
+    return new this.TypedArrayCtor(
+      this.buffer,
+      0,
+      spatialPixels * this.componentsPerVoxel,
+    )
   }
 
   /**
@@ -109,7 +160,8 @@ export class BufferManager {
   }
 
   /**
-   * Get the total number of pixels in the current buffer region.
+   * Get the total number of spatial pixels in the current buffer region.
+   * This does NOT include the component multiplier.
    */
   getPixelCount(): number {
     return (
@@ -120,7 +172,15 @@ export class BufferManager {
   }
 
   /**
-   * Get the buffer capacity in pixels.
+   * Get the total number of scalar elements in the current buffer region.
+   * For multi-component images, this is `spatialPixels × componentsPerVoxel`.
+   */
+  getElementCount(): number {
+    return this.getPixelCount() * this.componentsPerVoxel
+  }
+
+  /**
+   * Get the buffer capacity in scalar elements.
    */
   getCapacity(): number {
     return this.buffer.byteLength / this.bytesPerPixel
@@ -151,12 +211,12 @@ export class BufferManager {
    * Clear the current buffer region to zeros.
    */
   clear(): void {
-    const pixelCount = this.getPixelCount()
-    if (pixelCount > 0) {
+    const elementCount = this.getElementCount()
+    if (elementCount > 0) {
       const view = new Uint8Array(
         this.buffer,
         0,
-        pixelCount * this.bytesPerPixel,
+        elementCount * this.bytesPerPixel,
       )
       view.fill(0)
     }
@@ -169,8 +229,9 @@ export class BufferManager {
    * @returns True if current buffer can fit the dimensions
    */
   canAccommodate(dimensions: [number, number, number]): boolean {
-    const requiredPixels = dimensions[0] * dimensions[1] * dimensions[2]
-    const currentCapacityPixels = this.buffer.byteLength / this.bytesPerPixel
-    return requiredPixels <= currentCapacityPixels
+    const requiredElements =
+      dimensions[0] * dimensions[1] * dimensions[2] * this.componentsPerVoxel
+    const currentCapacityElements = this.buffer.byteLength / this.bytesPerPixel
+    return requiredElements <= currentCapacityElements
   }
 }

package/src/OMEZarrNVImage.ts

@@ -29,6 +29,8 @@ import {
   type OMEZarrNVImageEventMap,
   type PopulateTrigger,
 } from "./events.js"
+import type { ChannelWindow } from "./normalize.js"
+import { computeChannelMinMax, normalizeToUint8 } from "./normalize.js"
 import { RegionCoalescer } from "./RegionCoalescer.js"
 import type { OrthogonalAxis } from "./ResolutionSelector.js"
 import {
@@ -39,6 +41,7 @@ import {
 } from "./ResolutionSelector.js"
 import type {
   AttachedNiivueState,
+  ChannelInfo,
   ChunkAlignedRegion,
   ChunkCache,
   ClipPlane,
@@ -53,7 +56,12 @@ import type {
 } from "./types.js"
 import {
   getBytesPerPixel,
+  getChannelInfo,
   getNiftiDataType,
+  getRGBNiftiDataType,
+  isRGBImage,
+  NiftiDataType,
+  needsRGBNormalization,
   parseZarritaDtype,
 } from "./types.js"
 import {
@@ -124,6 +132,24 @@ export class OMEZarrNVImage extends NVImage {
   /** Data type of the volume */
   private readonly dtype: ZarrDtype
 
+  /**
+   * Channel dimension info, or `null` for scalar (single-component) images.
+   * When non-null, the image has a `"c"` dimension and is treated as
+   * multi-component (RGB/RGBA) data.
+   */
+  private readonly _channelInfo: ChannelInfo | null
+
+  /**
+   * Whether the image is 2D (no `"z"` dimension).
+   */
+  private readonly _is2D: boolean
+
+  /**
+   * Whether to negate the y-scale in the NIfTI affine for 2D images
+   * so that NiiVue renders them right-side up.
+   */
+  private readonly _flipY2D: boolean
+
   /** Full volume bounds in world space */
   private readonly _volumeBounds: VolumeBounds
 
@@ -258,6 +284,23 @@ export class OMEZarrNVImage extends NVImage {
     const highResImage = this.multiscales.images[0]
     this.dtype = parseZarritaDtype(highResImage.data.dtype)
 
+    // Detect channel (component) dimension for multi-component images
+    this._channelInfo = getChannelInfo(highResImage)
+
+    // Validate multi-component images: only RGB (3) / RGBA (4) are supported
+    if (this._channelInfo && !isRGBImage(highResImage)) {
+      throw new Error(
+        `Unsupported multi-component image: found ${this._channelInfo.components} ` +
+          `components with dtype '${this.dtype}'. Only RGB (3 components) ` +
+          `and RGBA (4 components) images are supported. For other ` +
+          `multi-component images, select a single component before loading.`,
+      )
+    }
+
+    // Detect 2D images (no z axis) and store y-flip preference
+    this._is2D = highResImage.dims.indexOf("z") === -1
+    this._flipY2D = options.flipY2D ?? true
+
     // Calculate volume bounds from highest resolution for most accurate bounds
     const highResAffine = createAffineFromNgffImage(highResImage)
     const highResShape = getVolumeShape(highResImage)
@@ -276,8 +319,15 @@ export class OMEZarrNVImage extends NVImage {
     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)
+    // Create buffer manager (dynamic sizing, no pre-allocation).
+    // For multi-component images, each spatial voxel has multiple
+    // scalar elements (e.g. 3 for RGB, 4 for RGBA).
+    const componentsPerVoxel = this._channelInfo?.components ?? 1
+    this.bufferManager = new BufferManager(
+      this.maxPixels,
+      this.dtype,
+      componentsPerVoxel,
+    )
 
     // Initialize NVImage properties with placeholder values
     // Actual values will be set when data is first loaded
@@ -336,17 +386,24 @@ export class OMEZarrNVImage extends NVImage {
     // 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
+    // Set data type — use RGB24/RGBA32 for multi-component images
+    // (any dtype; non-uint8 data is normalized to uint8 at load time)
+    if (this._channelInfo && isRGBImage(this.multiscales.images[0])) {
+      const rgbCode = getRGBNiftiDataType(this._channelInfo)
+      hdr.datatypeCode = rgbCode
+      hdr.numBitsPerVoxel = rgbCode === NiftiDataType.RGB24 ? 24 : 32
+    } else {
+      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)
+    // Placeholder affine (identity, with y-flip for 2D images)
     hdr.affine = [
       [1, 0, 0, 0],
-      [0, 1, 0, 0],
+      [0, this._flipY2D && this._is2D ? -1 : 1, 0, 0],
       [0, 0, 1, 0],
       [0, 0, 0, 1],
     ]
@@ -533,8 +590,29 @@ export class OMEZarrNVImage extends NVImage {
     // Resize buffer to match fetched data exactly (no upsampling!)
     const targetData = this.bufferManager.resize(fetchedShape)
 
-    // Direct copy of fetched data
-    targetData.set(result.data)
+    // For non-uint8 RGB/RGBA, we need OMERO metadata *before* copying
+    // so we can normalize the raw data to uint8 using channel windows.
+    const normalize = needsRGBNormalization(ngffImage, this.dtype)
+    if (normalize && !this.isLabelImage) {
+      await this.ensureOmeroMetadata(ngffImage, levelIndex)
+    }
+
+    if (normalize && this._channelInfo) {
+      // Non-uint8 RGB/RGBA: normalize raw data to uint8 using OMERO windows
+      const windows = this._getChannelWindows(
+        result.data,
+        this._channelInfo.components,
+      )
+      const normalized = normalizeToUint8(
+        result.data,
+        this._channelInfo.components,
+        windows,
+      )
+      targetData.set(normalized)
+    } else {
+      // uint8 RGB or scalar: direct copy
+      targetData.set(result.data)
+    }
 
     // Update this.img to point to the (possibly new) buffer
     this.img = this.bufferManager.getTypedArray() as NVImage["img"]
@@ -545,8 +623,9 @@ export class OMEZarrNVImage extends NVImage {
     if (this.isLabelImage) {
       // Label images: apply a discrete colormap instead of OMERO windowing
       this._applyLabelColormap(this, result.data)
-    } else {
-      // Compute or apply OMERO metadata for cal_min/cal_max
+    } else if (!normalize) {
+      // Scalar / uint8 RGB: compute or apply OMERO for cal_min/cal_max.
+      // (Normalized RGB already consumed the OMERO window above.)
       await this.ensureOmeroMetadata(ngffImage, levelIndex)
     }
 
@@ -630,12 +709,8 @@ export class OMEZarrNVImage extends NVImage {
     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
+    // Update current buffer bounds from the un-flipped affine
+    // (bounds stay in OME-Zarr world space for clip plane math)
     this._currentBufferBounds = {
       min: [
         affine[12], // x offset (world coord of buffer origin)
@@ -649,6 +724,17 @@ export class OMEZarrNVImage extends NVImage {
       ],
     }
 
+    // For 2D images, negate y-scale so NiiVue's calculateRAS() flips
+    // the rows to account for top-to-bottom pixel storage order.
+    if (this._flipY2D && this._is2D) {
+      affine[5] = -sy
+      affine[13] += (fetchedShape[1] - 1) * sy
+    }
+
+    // Update affine in header
+    const srows = affineToNiftiSrows(affine)
+    this.hdr.affine = [srows.srow_x, srows.srow_y, srows.srow_z, [0, 0, 0, 1]]
+
     // Recalculate RAS orientation
     this.calculateRAS()
   }
@@ -788,7 +874,15 @@ export class OMEZarrNVImage extends NVImage {
         (isTargetLevel && this._omeroComputedForLevel !== this.targetLevelIndex)
 
       if (needsCompute) {
-        const computedOmero = await computeOmeroFromNgffImage(ngffImage)
+        // Pass the chunk cache so decoded chunks from OMERO statistics
+        // computation are reused by subsequent zarrGet() calls.
+        const omeroOpts = this._chunkCache
+          ? ({ cache: this._chunkCache } as Record<string, unknown>)
+          : undefined
+        const computedOmero = await computeOmeroFromNgffImage(
+          ngffImage,
+          omeroOpts,
+        )
         this._omero = computedOmero
         this._omeroComputedForLevel = levelIndex
         this.applyOmeroToHeader()
@@ -796,6 +890,42 @@ export class OMEZarrNVImage extends NVImage {
     }
   }
 
+  /**
+   * Get per-channel normalization windows for non-uint8 RGB/RGBA.
+   *
+   * Uses OMERO `window.start`/`window.end` (or `window.min`/`window.max`)
+   * when available. Falls back to computing min/max from the raw data.
+   *
+   * @param data - Raw multi-component data from the zarr fetch
+   * @param components - Number of components per voxel (3 or 4)
+   * @returns Per-channel windows for normalization to uint8
+   */
+  private _getChannelWindows(
+    data: TypedArray,
+    components: number,
+  ): ChannelWindow[] {
+    if (this._omero?.channels?.length) {
+      const windows: ChannelWindow[] = []
+      for (let c = 0; c < components; c++) {
+        const channel =
+          this._omero.channels[Math.min(c, this._omero.channels.length - 1)]
+        const win = channel?.window
+        if (win) {
+          windows.push({
+            start: win.start ?? win.min ?? 0,
+            end: win.end ?? win.max ?? 1,
+          })
+        } else {
+          windows.push({ start: 0, end: 1 })
+        }
+      }
+      return windows
+    }
+
+    // No OMERO metadata: fall back to per-channel min/max from data
+    return computeChannelMinMax(data, components)
+  }
+
   /**
    * Handle clip plane change from NiiVue.
    * This is called when the user interacts with clip planes in NiiVue.
@@ -1798,15 +1928,26 @@ export class OMEZarrNVImage extends NVImage {
    * Create a new slab buffer state for a slice type.
    */
   private _createSlabBuffer(sliceType: SlabSliceType): SlabBufferState {
-    const bufferManager = new BufferManager(this.maxPixels, this.dtype)
+    const componentsPerVoxel = this._channelInfo?.components ?? 1
+    const bufferManager = new BufferManager(
+      this.maxPixels,
+      this.dtype,
+      componentsPerVoxel,
+    )
     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
+    if (this._channelInfo && isRGBImage(this.multiscales.images[0])) {
+      const rgbCode = getRGBNiftiDataType(this._channelInfo)
+      hdr.datatypeCode = rgbCode
+      hdr.numBitsPerVoxel = rgbCode === NiftiDataType.RGB24 ? 24 : 32
+    } else {
+      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],
@@ -2088,7 +2229,25 @@ export class OMEZarrNVImage extends NVImage {
 
     // Resize buffer and copy data
     const targetData = slabState.bufferManager.resize(fetchedShape)
-    targetData.set(result.data)
+    const normalize = needsRGBNormalization(ngffImage, this.dtype)
+
+    if (normalize && this._channelInfo) {
+      // Non-uint8 RGB/RGBA: normalize raw data to uint8 using OMERO windows
+      const windows = this._getChannelWindows(
+        result.data,
+        this._channelInfo.components,
+      )
+      const normalized = normalizeToUint8(
+        result.data,
+        this._channelInfo.components,
+        windows,
+      )
+      targetData.set(normalized)
+    } else {
+      // uint8 RGB or scalar: direct copy
+      targetData.set(result.data)
+    }
+
     slabState.nvImage.img =
       slabState.bufferManager.getTypedArray() as NVImage["img"]
 
@@ -2108,8 +2267,9 @@ export class OMEZarrNVImage extends NVImage {
     if (this.isLabelImage) {
       // Label images: apply discrete colormap to the slab NVImage
       this._applyLabelColormap(slabState.nvImage, result.data)
-    } else if (this._omero) {
-      // Apply OMERO metadata if available
+    } else if (this._omero && !normalize) {
+      // Apply OMERO metadata for scalar / uint8 RGB.
+      // Normalized RGB already consumed the OMERO window during normalization.
       this._applyOmeroToSlabHeader(slabState.nvImage)
     }
 
@@ -2213,6 +2373,12 @@ export class OMEZarrNVImage extends NVImage {
     affine[13] += fetchStart[1] * sy // y offset
     affine[14] += fetchStart[0] * sz // z offset
 
+    // For 2D images, negate y-scale before normalization
+    if (this._flipY2D && this._is2D) {
+      affine[5] = -sy
+      affine[13] += (fetchedShape[1] - 1) * sy
+    }
+
     // Apply normalization to the entire affine (scale columns + translation)
     for (let i = 0; i < 15; i++) {
       affine[i] *= normalizationScale

package/src/RegionCoalescer.ts

@@ -26,6 +26,46 @@ interface PendingRequest {
   requesters: Set<string>
 }
 
+/**
+ * Map from [z, y, x] PixelRegion indices to the zarr dim name.
+ * Index 0 → "z", index 1 → "y", index 2 → "x".
+ */
+const SPATIAL_DIM_MAP: Record<string, 0 | 1 | 2> = {
+  z: 0,
+  y: 1,
+  x: 2,
+}
+
+/**
+ * Build a zarr selection array that respects the actual dimension order
+ * of the zarr array.
+ *
+ * The `PixelRegion` is always in `[z, y, x]` order. This function maps
+ * 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)
+ *
+ * @param dims - Dimension names from NgffImage (e.g. `["y", "x", "c"]`)
+ * @param region - The pixel region in `[z, y, x]` order
+ * @returns Selection array matching the zarr dim order
+ */
+export function buildSelection(
+  dims: string[],
+  region: PixelRegion,
+): (zarr.Slice | number | null)[] {
+  return dims.map((dim) => {
+    const spatialIdx = SPATIAL_DIM_MAP[dim]
+    if (spatialIdx !== undefined) {
+      return zarr.slice(region.start[spatialIdx], region.end[spatialIdx])
+    }
+    if (dim === "c") return null // select all channels
+    if (dim === "t") return 0 // first timepoint
+    // Unknown dimension — select all to avoid data loss
+    return null
+  })
+}
+
 /**
  * RegionCoalescer handles fetching sub-regions from OME-Zarr images with:
  *
@@ -113,11 +153,11 @@ export class RegionCoalescer {
 
     // Fetch using fizarrita's worker-accelerated zarrGet
     try {
-      const selection = [
-        zarr.slice(region.start[0], region.end[0]),
-        zarr.slice(region.start[1], region.end[1]),
-        zarr.slice(region.start[2], region.end[2]),
-      ]
+      // 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)
       // 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

package/src/ResolutionSelector.ts

@@ -93,51 +93,67 @@ export function selectResolution(
 }
 
 /**
- * Get the chunk shape for a volume.
+ * Get the chunk shape for a volume as [z, y, x].
+ *
+ * Looks up `"z"`, `"y"`, `"x"` dimensions by name. If `"z"` is absent
+ * (e.g., 2D images with `dims=["y", "x"]` or `["y", "x", "c"]`),
+ * the z chunk size defaults to 1. Non-spatial dimensions like `"c"` and
+ * `"t"` are ignored.
  *
  * @param ngffImage - The NgffImage to get chunk shape from
  * @returns Chunk shape as [z, y, x]
+ * @throws If neither `"y"` nor `"x"` can be found in dims
  */
 export function getChunkShape(ngffImage: NgffImage): [number, number, number] {
   const chunks = ngffImage.data.chunks
   const dims = ngffImage.dims
 
-  // Find z, y, x indices in dims
-  const zIdx = dims.indexOf("z")
   const yIdx = dims.indexOf("y")
   const xIdx = dims.indexOf("x")
 
-  if (zIdx === -1 || yIdx === -1 || xIdx === -1) {
-    // Fallback: assume last 3 dimensions are z, y, x
-    const n = chunks.length
-    return [chunks[n - 3] || 1, chunks[n - 2] || 1, chunks[n - 1] || 1]
+  if (yIdx === -1 || xIdx === -1) {
+    throw new Error(
+      `Cannot determine chunk shape: dims=[${dims.join(",")}] ` +
+        `is missing required "y" and/or "x" axes`,
+    )
   }
 
-  return [chunks[zIdx], chunks[yIdx], chunks[xIdx]]
+  const zIdx = dims.indexOf("z")
+  const cz = zIdx !== -1 ? chunks[zIdx] : 1
+
+  return [cz, chunks[yIdx], chunks[xIdx]]
 }
 
 /**
- * Get the shape of a volume as [z, y, x].
+ * Get the spatial shape of a volume as [z, y, x].
+ *
+ * Looks up `"z"`, `"y"`, `"x"` dimensions by name. If `"z"` is absent
+ * (e.g., 2D images with `dims=["y", "x"]` or `["y", "x", "c"]`),
+ * the z size defaults to 1. Non-spatial dimensions like `"c"` and
+ * `"t"` are ignored.
  *
  * @param ngffImage - The NgffImage
  * @returns Shape as [z, y, x]
+ * @throws If neither `"y"` nor `"x"` can be found in dims
  */
 export function getVolumeShape(ngffImage: NgffImage): [number, number, number] {
   const shape = ngffImage.data.shape
   const dims = ngffImage.dims
 
-  // Find z, y, x indices in dims
-  const zIdx = dims.indexOf("z")
   const yIdx = dims.indexOf("y")
   const xIdx = dims.indexOf("x")
 
-  if (zIdx === -1 || yIdx === -1 || xIdx === -1) {
-    // Fallback: assume last 3 dimensions are z, y, x
-    const n = shape.length
-    return [shape[n - 3] || 1, shape[n - 2] || 1, shape[n - 1] || 1]
+  if (yIdx === -1 || xIdx === -1) {
+    throw new Error(
+      `Cannot determine volume shape: dims=[${dims.join(",")}] ` +
+        `is missing required "y" and/or "x" axes`,
+    )
   }
 
-  return [shape[zIdx], shape[yIdx], shape[xIdx]]
+  const zIdx = dims.indexOf("z")
+  const sz = zIdx !== -1 ? shape[zIdx] : 1
+
+  return [sz, shape[yIdx], shape[xIdx]]
 }
 
 /**