@fideus-labs/fidnii 0.3.0 → 0.5.0

package/src/OMEZarrNVImage.ts

@@ -68,8 +68,14 @@ import {
   affineToNiftiSrows,
   calculateWorldBounds,
   createAffineFromNgffImage,
+  createAffineFromOMEZarr,
 } from "./utils/affine.js"
 import { worldToPixel } from "./utils/coordinates.js"
+import {
+  applyOrientationToAffine,
+  getOrientationMapping,
+  getOrientationSigns,
+} from "./utils/orientation.js"
 import {
   boundsApproxEqual,
   computeViewportBounds2D,
@@ -301,8 +307,14 @@ export class OMEZarrNVImage extends NVImage {
     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)
+    // 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.
+    // Orientation is only applied to the NIfTI affine passed to NiiVue.
+    const highResAffine = createAffineFromOMEZarr(
+      highResImage.scale,
+      highResImage.translation,
+    )
     const highResShape = getVolumeShape(highResImage)
     this._volumeBounds = calculateWorldBounds(highResAffine, highResShape)
 
@@ -400,13 +412,27 @@ export class OMEZarrNVImage extends NVImage {
     // Placeholder pixel dimensions
     hdr.pixDims = [1, 1, 1, 1, 0, 0, 0, 0]
 
-    // Placeholder affine (identity, with y-flip for 2D images)
-    hdr.affine = [
-      [1, 0, 0, 0],
-      [0, this._flipY2D && this._is2D ? -1 : 1, 0, 0],
-      [0, 0, 1, 0],
+    // Placeholder affine (unit scale with orientation permutation/signs)
+    // This is replaced by real data when loadResolutionLevel completes,
+    // but having a reasonable placeholder avoids rendering glitches during
+    // the initial frame.
+    const mapping = getOrientationMapping(
+      this.multiscales.images[0]?.axesOrientations,
+    )
+    const placeholderAffine = [
+      [0, 0, 0, 0],
+      [0, 0, 0, 0],
+      [0, 0, 0, 0],
       [0, 0, 0, 1],
     ]
+    placeholderAffine[mapping.x.physicalRow][0] = mapping.x.sign
+    let ySign = mapping.y.sign
+    if (this._flipY2D && this._is2D) {
+      ySign = (ySign * -1) as 1 | -1
+    }
+    placeholderAffine[mapping.y.physicalRow][1] = ySign
+    placeholderAffine[mapping.z.physicalRow][2] = mapping.z.sign
+    hdr.affine = placeholderAffine
 
     hdr.sform_code = 1 // Scanner coordinates
 
@@ -698,25 +724,22 @@ export class OMEZarrNVImage extends NVImage {
       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
+    // 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.
     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 from the un-flipped affine
-    // (bounds stay in OME-Zarr world space for clip plane math)
+    // Update current buffer bounds in OME-Zarr world space
     this._currentBufferBounds = {
-      min: [
-        affine[12], // x offset (world coord of buffer origin)
-        affine[13], // y offset
-        affine[14], // z offset
-      ],
+      min: [affine[12], affine[13], affine[14]],
       max: [
         affine[12] + fetchedShape[2] * sx,
         affine[13] + fetchedShape[1] * sy,
@@ -724,11 +747,21 @@ 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.
+    // Apply orientation signs so the NIfTI affine encodes anatomical
+    // direction for NiiVue's calculateRAS()
+    applyOrientationToAffine(affine, ngffImage.axesOrientations)
+
+    // 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
+    // y column. This composes correctly with any orientation sign.
     if (this._flipY2D && this._is2D) {
-      affine[5] = -sy
-      affine[13] += (fetchedShape[1] - 1) * sy
+      // Get the y axis orientation mapping to find where the y scale is stored
+      const mapping = getOrientationMapping(ngffImage.axesOrientations)
+      // The y scale is at affine[4 + physicalRow] (column 1, appropriate row)
+      const yScaleIndex = 4 + mapping.y.physicalRow
+      affine[13] += affine[yScaleIndex] * (fetchedShape[1] - 1)
+      affine[yScaleIndex] = -affine[yScaleIndex]
     }
 
     // Update affine in header
@@ -2366,17 +2399,28 @@ export class OMEZarrNVImage extends NVImage {
       1,
     ]
 
-    // Build affine with offset for region start, then normalize
+    // 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).
     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] * sx // x offset
-    affine[13] += fetchStart[1] * sy // y offset
-    affine[14] += fetchStart[0] * sz // z offset
+    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)
 
-    // For 2D images, negate y-scale before normalization
+    // For 2D images, flip y before normalization (composes with orientation)
     if (this._flipY2D && this._is2D) {
-      affine[5] = -sy
-      affine[13] += (fetchedShape[1] - 1) * sy
+      // Get the y axis orientation mapping to find where the y scale is stored
+      const mapping = getOrientationMapping(ngffImage.axesOrientations)
+      // The y scale is at affine[4 + physicalRow] (column 1, appropriate row)
+      const yScaleIndex = 4 + mapping.y.physicalRow
+      affine[13] += affine[yScaleIndex] * (fetchedShape[1] - 1)
+      affine[yScaleIndex] = -affine[yScaleIndex]
     }
 
     // Apply normalization to the entire affine (scale columns + translation)

package/src/fromTiff.ts

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+/**
+ * Load TIFF files (OME-TIFF, pyramidal, plain) and produce a
+ * {@link Multiscales} object ready for {@link OMEZarrNVImage.create}.
+ *
+ * Uses {@link https://github.com/fideus-labs/fiff | @fideus-labs/fiff}
+ * to present TIFFs as zarrita-compatible stores, then delegates to
+ * {@link fromNgffZarr} for OME-Zarr metadata parsing.
+ */
+
+import type { DeflatePool, TiffStoreOptions } from "@fideus-labs/fiff"
+import { TiffStore } from "@fideus-labs/fiff"
+import type { Multiscales } from "@fideus-labs/ngff-zarr"
+import type { FromNgffZarrOptions } from "@fideus-labs/ngff-zarr/browser"
+import { fromNgffZarr } from "@fideus-labs/ngff-zarr/browser"
+import type { Readable } from "zarrita"
+
+/** Options for {@link fromTiff}. */
+export interface FromTiffOptions {
+  /** Options forwarded to {@link TiffStore} (e.g. IFD offsets, HTTP headers). */
+  tiff?: TiffStoreOptions
+  /** Options forwarded to {@link fromNgffZarr} (e.g. validate, cache). */
+  ngffZarr?: Omit<FromNgffZarrOptions, "version">
+  /**
+   * Optional worker pool for offloading deflate decompression to Web
+   * Workers when reading compressed TIFFs.
+   *
+   * When provided, registers a worker-backed deflate decoder with
+   * geotiff.js so that all subsequent chunk reads decompress off the
+   * main thread.
+   *
+   * Accepts any object matching the {@link DeflatePool} interface
+   * (e.g. `new WorkerPool(n)` from `@fideus-labs/worker-pool`).
+   *
+   * This is a convenience shorthand — the same pool can also be
+   * passed via `tiff.pool`.
+   *
+   * Note: {@link fromTiff} does not manage the lifecycle of the pool.
+   * If you create a pool and pass it here (or via `tiff.pool`), you
+   * are responsible for terminating it when it is no longer needed,
+   * e.g. by calling `pool.terminateWorkers()` after you are done with
+   * the associated {@link TiffStore} and image usage.
+   */
+  pool?: DeflatePool
+}
+
+/**
+ * Load a TIFF file and return a {@link Multiscales} object ready for
+ * {@link OMEZarrNVImage.create}.
+ *
+ * Supports OME-TIFF, pyramidal TIFF (SubIFDs / legacy / COG), and
+ * plain single-image TIFFs. Both local (Blob/ArrayBuffer) and
+ * remote (URL with HTTP range requests) sources are supported.
+ *
+ * @param source - A URL string, Blob/File, ArrayBuffer, or
+ *   pre-built {@link TiffStore}.
+ * @param options - Optional {@link FromTiffOptions}.
+ * @returns A {@link Multiscales} object for use with
+ *   {@link OMEZarrNVImage.create}.
+ * @throws If the source cannot be opened as a TIFF or if the
+ *   synthesized OME-Zarr metadata is invalid.
+ *
+ * @example
+ * ```typescript
+ * // From a remote URL
+ * const ms = await fromTiff("https://example.com/image.ome.tif")
+ * const image = await OMEZarrNVImage.create({
+ *   multiscales: ms,
+ *   niivue: nv,
+ * })
+ *
+ * // From a File input
+ * const file = inputElement.files[0]
+ * const ms = await fromTiff(file)
+ * ```
+ */
+export async function fromTiff(
+  source: string | Blob | ArrayBuffer | TiffStore,
+  options: FromTiffOptions = {},
+): Promise<Multiscales> {
+  // Merge top-level pool into tiff sub-options (top-level takes precedence)
+  const tiffOpts: TiffStoreOptions | undefined = options.pool
+    ? { ...options.tiff, pool: options.pool }
+    : options.tiff
+
+  let store: TiffStore
+  if (source instanceof TiffStore) {
+    // Note: When passing a pre-built TiffStore, configure the pool via
+    // TiffStore constructor options rather than through FromTiffOptions.pool.
+    store = source
+  } else if (typeof source === "string") {
+    store = await TiffStore.fromUrl(source, tiffOpts)
+  } else if (source instanceof Blob) {
+    store = await TiffStore.fromBlob(source, tiffOpts)
+  } else if (source instanceof ArrayBuffer) {
+    store = await TiffStore.fromArrayBuffer(source, tiffOpts)
+  } else {
+    throw new Error(
+      "[fidnii] fromTiff: source must be a URL string, Blob, " +
+        "ArrayBuffer, or TiffStore",
+    )
+  }
+
+  // TiffStore implements zarrita's Readable interface structurally
+  // (its get() method accepts string keys including the leading "/"
+  // that zarrita uses for AbsolutePath). Since fromNgffZarr (v0.10+)
+  // accepts zarr.Readable directly, we only need a type assertion.
+  //
+  // TiffStore always produces OME-Zarr v0.5 metadata.
+  return fromNgffZarr(store as unknown as Readable, {
+    version: "0.5",
+    ...options.ngffZarr,
+  })
+}

package/src/index.ts

@@ -34,6 +34,8 @@
  * ```
  */
 
+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)
@@ -72,6 +74,9 @@ export type {
 } from "./events.js"
 // Event system (browser-native EventTarget API)
 export { OMEZarrNVImageEvent } from "./events.js"
+export type { FromTiffOptions } from "./fromTiff.js"
+// TIFF support (via @fideus-labs/fiff)
+export { fromTiff } from "./fromTiff.js"
 // RGB normalization utilities
 export type { ChannelWindow } from "./normalize.js"
 export { computeChannelMinMax, normalizeToUint8 } from "./normalize.js"
@@ -145,6 +150,17 @@ export {
   worldToPixel,
   worldToPixelAffine,
 } from "./utils/coordinates.js"
+// Orientation utilities (NGFF RFC-4 anatomical orientation)
+export type {
+  OrientationMapping,
+  OrientationSigns,
+} from "./utils/orientation.js"
+export {
+  applyOrientationToAffine,
+  getOrientationInfo,
+  getOrientationMapping,
+  getOrientationSigns,
+} from "./utils/orientation.js"
 // Viewport bounds utilities
 export {
   boundsApproxEqual,

package/src/utils/affine.ts

@@ -4,6 +4,8 @@
 import type { NgffImage } from "@fideus-labs/ngff-zarr"
 import { mat4 } from "gl-matrix"
 
+import { applyOrientationToAffine } from "./orientation.js"
+
 /**
  * Create a 4x4 affine transformation matrix from OME-Zarr scale and translation.
  *
@@ -76,11 +78,22 @@ export function createAffineFromOMEZarr(
 /**
  * Create an affine matrix from an NgffImage.
  *
- * @param ngffImage - The NgffImage containing scale and translation
- * @returns 4x4 affine matrix
+ * If the image has RFC-4 anatomical orientation metadata
+ * (`axesOrientations`), the affine column vectors and translations
+ * are sign-flipped so the matrix encodes direction relative to
+ * the NIfTI RAS+ convention. This allows NiiVue's `calculateRAS()`
+ * to correctly determine the anatomical layout.
+ *
+ * When no orientation metadata is present, the matrix is identical
+ * to a plain scale + translation affine (backward-compatible).
+ *
+ * @param ngffImage - The NgffImage containing scale, translation,
+ *   and optional `axesOrientations`
+ * @returns 4x4 affine matrix with orientation signs applied
  */
 export function createAffineFromNgffImage(ngffImage: NgffImage): mat4 {
-  return createAffineFromOMEZarr(ngffImage.scale, ngffImage.translation)
+  const affine = createAffineFromOMEZarr(ngffImage.scale, ngffImage.translation)
+  return applyOrientationToAffine(affine, ngffImage.axesOrientations)
 }
 
 /**

package/src/utils/orientation.ts

@@ -0,0 +1,292 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+import type { AnatomicalOrientation } from "@fideus-labs/ngff-zarr"
+import type { mat4 } from "gl-matrix"
+
+/**
+ * Mapping from an array axis orientation to the physical (RAS) row
+ * and sign it should occupy in the NIfTI affine.
+ *
+ * - `physicalRow`: which row of the 4x4 affine the scale/translation
+ *   should be placed in (0 = R/L, 1 = A/P, 2 = S/I)
+ * - `sign`: `1` if the orientation is in the RAS+ direction,
+ *   `-1` if opposite
+ */
+export interface OrientationMapping {
+  readonly physicalRow: 0 | 1 | 2
+  readonly sign: 1 | -1
+}
+
+/**
+ * Sign multipliers for each spatial axis, used to encode anatomical
+ * orientation into the NIfTI affine matrix.
+ *
+ * A value of `1` means the axis increases in the RAS+ direction
+ * (Right, Anterior, Superior). A value of `-1` means it increases
+ * in the opposite direction (Left, Posterior, Inferior).
+ *
+ * @deprecated Use {@link getOrientationMapping} for full permutation
+ *   support. This interface only captures sign, not axis permutations.
+ */
+export interface OrientationSigns {
+  readonly x: 1 | -1
+  readonly y: 1 | -1
+  readonly z: 1 | -1
+}
+
+/**
+ * Lookup table mapping each RFC-4 anatomical orientation string to
+ * its NIfTI RAS+ physical row and sign.
+ *
+ * RAS+ convention:
+ * - Row 0 (X): left-to-right (R+)
+ * - Row 1 (Y): posterior-to-anterior (A+)
+ * - Row 2 (Z): inferior-to-superior (S+)
+ */
+const ORIENTATION_INFO: Record<string, OrientationMapping> = {
+  // L/R pair → physical row 0
+  "left-to-right": { physicalRow: 0, sign: 1 },
+  "right-to-left": { physicalRow: 0, sign: -1 },
+  // A/P pair → physical row 1
+  "posterior-to-anterior": { physicalRow: 1, sign: 1 },
+  "anterior-to-posterior": { physicalRow: 1, sign: -1 },
+  // S/I pair → physical row 2
+  "inferior-to-superior": { physicalRow: 2, sign: 1 },
+  "superior-to-inferior": { physicalRow: 2, sign: -1 },
+}
+
+/**
+ * Get the orientation mapping (physical row + RAS sign) for a single
+ * axis orientation.
+ *
+ * For unknown/exotic orientations, returns `undefined`.
+ *
+ * @param orientation - The anatomical orientation for one axis
+ * @returns The physical row and sign, or `undefined` if not a standard
+ *   L/R, A/P, or S/I orientation
+ */
+export function getOrientationInfo(
+  orientation: AnatomicalOrientation,
+): OrientationMapping | undefined {
+  return ORIENTATION_INFO[orientation.value]
+}
+
+/**
+ * Get orientation mappings for all three spatial axes.
+ *
+ * Each mapping tells you which physical (RAS) row the array axis
+ * maps to and what sign to apply. This supports both sign flips
+ * (e.g. LPS) and axis permutations (e.g. when the OME-Zarr y axis
+ * encodes S/I instead of A/P).
+ *
+ * When no orientation metadata is present, returns the identity
+ * mapping: x→row 0 sign +1, y→row 1 sign +1, z→row 2 sign +1.
+ *
+ * @param axesOrientations - Orientation metadata from
+ *   `NgffImage.axesOrientations`, or `undefined`
+ * @returns Mappings for x, y, and z axes
+ *
+ * @example
+ * ```typescript
+ * // LPS data: x→row0 sign-1, y→row1 sign-1, z→row2 sign+1
+ * getOrientationMapping(LPS)
+ *
+ * // Permuted (mri.nii.gz): x→row0 sign-1, y→row2 sign-1, z→row1 sign+1
+ * getOrientationMapping(permutedOrientations)
+ * ```
+ */
+export function getOrientationMapping(
+  axesOrientations: Record<string, AnatomicalOrientation> | undefined,
+): { x: OrientationMapping; y: OrientationMapping; z: OrientationMapping } {
+  const defaultMapping = {
+    x: { physicalRow: 0 as const, sign: 1 as const },
+    y: { physicalRow: 1 as const, sign: 1 as const },
+    z: { physicalRow: 2 as const, sign: 1 as const },
+  }
+
+  if (!axesOrientations) {
+    return defaultMapping
+  }
+
+  const xOrientation = axesOrientations.x ?? axesOrientations.X
+  const yOrientation = axesOrientations.y ?? axesOrientations.Y
+  const zOrientation = axesOrientations.z ?? axesOrientations.Z
+
+  const mapping = {
+    x:
+      (xOrientation ? getOrientationInfo(xOrientation) : undefined) ??
+      defaultMapping.x,
+    y:
+      (yOrientation ? getOrientationInfo(yOrientation) : undefined) ??
+      defaultMapping.y,
+    z:
+      (zOrientation ? getOrientationInfo(zOrientation) : undefined) ??
+      defaultMapping.z,
+  }
+
+  // Validate that each physicalRow is used exactly once to prevent
+  // degenerate affine matrices where columns overwrite each other
+  const rowsUsed = new Set([
+    mapping.x.physicalRow,
+    mapping.y.physicalRow,
+    mapping.z.physicalRow,
+  ])
+
+  if (rowsUsed.size !== 3) {
+    console.warn(
+      "[fidnii] Invalid orientation metadata: multiple axes map to the same physical row. Falling back to identity mapping.",
+    )
+    return defaultMapping
+  }
+
+  return mapping
+}
+
+/**
+ * Compute RAS+ sign multipliers from RFC-4 anatomical orientation metadata.
+ *
+ * For each spatial axis, determines whether the axis direction is aligned
+ * with (+1) or opposite to (-1) the NIfTI RAS+ convention:
+ * - x: positive = left-to-right (R), negative = right-to-left (L)
+ * - y: positive = posterior-to-anterior (A), negative = anterior-to-posterior (P)
+ * - z: positive = inferior-to-superior (S), negative = superior-to-inferior (I)
+ *
+ * Only the 6 standard L/R, A/P, I/S orientations are handled. Exotic
+ * orientations (dorsal/ventral, rostral/caudal, etc.) are treated as
+ * unknown and default to +1.
+ *
+ * **Note**: This function only returns sign information, not axis
+ * permutation. For full permutation support, use
+ * {@link getOrientationMapping} and {@link applyOrientationToAffine}.
+ *
+ * @param axesOrientations - Orientation metadata from `NgffImage.axesOrientations`,
+ *   or `undefined` if no orientation metadata is present
+ * @returns Sign multipliers for x, y, and z axes
+ *
+ * @example
+ * ```typescript
+ * import { LPS, RAS } from "@fideus-labs/ngff-zarr"
+ *
+ * // LPS data: x and y are anti-RAS+
+ * getOrientationSigns(LPS)
+ * // => { x: -1, y: -1, z: 1 }
+ *
+ * // RAS data: all axes are RAS+
+ * getOrientationSigns(RAS)
+ * // => { x: 1, y: 1, z: 1 }
+ *
+ * // No orientation: defaults to all positive
+ * getOrientationSigns(undefined)
+ * // => { x: 1, y: 1, z: 1 }
+ * ```
+ */
+export function getOrientationSigns(
+  axesOrientations: Record<string, AnatomicalOrientation> | undefined,
+): OrientationSigns {
+  const mapping = getOrientationMapping(axesOrientations)
+  return {
+    x: mapping.x.sign,
+    y: mapping.y.sign,
+    z: mapping.z.sign,
+  }
+}
+
+/**
+ * Apply anatomical orientation to an affine matrix in place.
+ *
+ * Builds a rotation/permutation matrix from the orientation metadata
+ * and applies it to the affine's 3x3 rotation/scale submatrix. This
+ * supports both simple sign flips (e.g. LPS where axes align with
+ * physical axes but directions differ) and full axis permutations
+ * (e.g. when OME-Zarr y axis encodes S/I instead of A/P).
+ *
+ * The input affine is expected to be a diagonal scale+translation
+ * matrix in gl-matrix column-major format, as produced by
+ * `createAffineFromOMEZarr()`:
+ *
+ * ```
+ * | sx  0   0  tx |
+ * | 0   sy  0  ty |
+ * | 0   0   sz tz |
+ * | 0   0   0  1  |
+ * ```
+ *
+ * **3x3 submatrix**: Each column's scale is placed in the row
+ * corresponding to the physical RAS axis the array axis maps to,
+ * with the appropriate sign:
+ *
+ * ```
+ * Column j (array axis j):
+ *   row = physicalRow for axis j
+ *   affine[j*4 + row] = sign * scale_j
+ * ```
+ *
+ * **Translation column**: Sign-flipped for LPS→RAS conversion but
+ * NOT row-permuted. This is because `itkImageToNgffImage` stores
+ * the ITK LPS origin values in array-axis-label order without
+ * transforming them through the direction matrix. The label
+ * assignment (x/y/z) follows the reversed ITK axis indices, so the
+ * physical meaning of each translation value matches its original
+ * LPS axis, regardless of axis permutation.
+ *
+ * When `axesOrientations` is `undefined`, the affine is left
+ * unchanged (backward-compatible identity mapping).
+ *
+ * @param affine - 4x4 affine matrix (column-major, modified in place)
+ * @param axesOrientations - Orientation metadata from `NgffImage.axesOrientations`
+ * @returns The same affine matrix (for chaining)
+ */
+export function applyOrientationToAffine(
+  affine: mat4,
+  axesOrientations: Record<string, AnatomicalOrientation> | undefined,
+): mat4 {
+  if (!axesOrientations) {
+    return affine
+  }
+
+  const mapping = getOrientationMapping(axesOrientations)
+
+  // Extract the current diagonal scale and translation values
+  // (the input affine is expected to be diagonal from createAffineFromOMEZarr)
+  const sx = affine[0]
+  const sy = affine[5]
+  const sz = affine[10]
+  const tx = affine[12]
+  const ty = affine[13]
+  const tz = affine[14]
+
+  // Clear the 3x3 submatrix (translation will be overwritten below)
+  // Column 0
+  affine[0] = 0
+  affine[1] = 0
+  affine[2] = 0
+  // Column 1
+  affine[4] = 0
+  affine[5] = 0
+  affine[6] = 0
+  // Column 2
+  affine[8] = 0
+  affine[9] = 0
+  affine[10] = 0
+
+  // Place each axis' scale into the correct physical row.
+  // gl-matrix is column-major: index = col * 4 + row
+
+  // Column 0 (array x axis): place sx at physicalRow for x
+  affine[0 + mapping.x.physicalRow] = mapping.x.sign * sx
+
+  // Column 1 (array y axis): place sy at physicalRow for y
+  affine[4 + mapping.y.physicalRow] = mapping.y.sign * sy
+
+  // Column 2 (array z axis): place sz at physicalRow for z
+  affine[8 + mapping.z.physicalRow] = mapping.z.sign * sz
+
+  // Translation: sign-flip for LPS→RAS but keep at original row
+  // positions (x→row 0, y→row 1, z→row 2). See JSDoc for why.
+  affine[12] = mapping.x.sign * tx
+  affine[13] = mapping.y.sign * ty
+  affine[14] = mapping.z.sign * tz
+
+  return affine
+}