@fideus-labs/fidnii 0.4.0 → 0.5.0

package/dist/utils/affine.js

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
 // SPDX-License-Identifier: MIT
 import { mat4 } from "gl-matrix";
+import { applyOrientationToAffine } from "./orientation.js";
 /**
  * Create a 4x4 affine transformation matrix from OME-Zarr scale and translation.
  *
@@ -60,11 +61,22 @@ export function createAffineFromOMEZarr(scale, translation) {
 /**
  * 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) {
-    return createAffineFromOMEZarr(ngffImage.scale, ngffImage.translation);
+    const affine = createAffineFromOMEZarr(ngffImage.scale, ngffImage.translation);
+    return applyOrientationToAffine(affine, ngffImage.axesOrientations);
 }
 /**
  * Convert an affine matrix to a flat array for NIfTI header.

package/dist/utils/affine.js.map

@@ -1 +1 @@
-{"version":3,"file":"affine.js","sourceRoot":"","sources":["../../src/utils/affine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"affine.js","sourceRoot":"","sources":["../../src/utils/affine.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,+BAA+B;AAG/B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA6B,EAC7B,WAAmC;IAEnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;IAE5B,qDAAqD;IACrD,8EAA8E;IAC9E,2EAA2E;IAE3E,8CAA8C;IAC9C,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAA;IAClC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAA;IAClC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAA;IAElC,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,IAAI,CAAC,CAAA;IAC9C,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,IAAI,CAAC,CAAA;IAC9C,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,IAAI,CAAC,CAAA;IAE9C,sBAAsB;IACtB,0EAA0E;IAC1E,oEAAoE;IAEpE,4DAA4D;IAC5D,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAA;IACd,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACb,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACb,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAEb,6DAA6D;IAC7D,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACb,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAA;IACd,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACb,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAEb,4DAA4D;IAC5D,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACb,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACb,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAA;IACf,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IAEd,wBAAwB;IACxB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAA;IACf,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAA;IACf,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAA;IACf,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IAEd,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAoB;IAC5D,MAAM,MAAM,GAAG,uBAAuB,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,WAAW,CAAC,CAAA;IAC9E,OAAO,wBAAwB,CAAC,MAAM,EAAE,SAAS,CAAC,gBAAgB,CAAC,CAAA;AACrE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAY;IAK7C,oCAAoC;IACpC,uCAAuC;IACvC,uCAAuC;IACvC,wCAAwC;IACxC,OAAO;QACL,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACrD,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACrD,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;KACvD,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAY;IAC7C,6DAA6D;IAC7D,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IACtE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IACtE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;IAEvE,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,cAAoB,EACpB,WAAqC,EACrC,WAAqC;IAErC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAA;IAEzC,6BAA6B;IAC7B,yBAAyB;IACzB,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA,CAAC,iBAAiB;IAC7C,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA;IAC3B,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA;IAE3B,yBAAyB;IACzB,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA,CAAC,iBAAiB;IAC7C,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA;IAC3B,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA;IAE3B,yBAAyB;IACzB,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA,CAAC,iBAAiB;IAC7C,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA;IAC3B,MAAM,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAA;IAE5B,uCAAuC;IACvC,mEAAmE;IACnE,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAA;IAE5D,MAAM,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAA,CAAC,WAAW;IAC/D,MAAM,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAA,CAAC,WAAW;IAC/D,MAAM,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAA,CAAC,WAAW;IAE/D,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAY,EACZ,UAAoC;IAEpC,uDAAuD;IACvD,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,UAAU,CAAA;IACrC,MAAM,OAAO,GAAG;QACd,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACT,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QACZ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACZ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC;QACZ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACf,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC;QACf,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;QACf,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;KACnB,CAAA;IAED,IAAI,IAAI,GAAG,QAAQ,EACjB,IAAI,GAAG,QAAQ,EACf,IAAI,GAAG,QAAQ,CAAA;IACjB,IAAI,IAAI,GAAG,CAAC,QAAQ,EAClB,IAAI,GAAG,CAAC,QAAQ,EAChB,IAAI,GAAG,CAAC,QAAQ,CAAA;IAElB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;QAChC,gDAAgD;QAChD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAA;QACrE,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAA;QACrE,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAA;QAEtE,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QACzB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QACzB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QACzB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QACzB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QACzB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAC3B,CAAC;IAED,OAAO;QACL,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;QACvB,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;KACxB,CAAA;AACH,CAAC"}

package/dist/utils/orientation.d.ts

@@ -0,0 +1,157 @@
+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;
+}
+/**
+ * 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 declare function getOrientationInfo(orientation: AnatomicalOrientation): OrientationMapping | undefined;
+/**
+ * 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 declare function getOrientationMapping(axesOrientations: Record<string, AnatomicalOrientation> | undefined): {
+    x: OrientationMapping;
+    y: OrientationMapping;
+    z: OrientationMapping;
+};
+/**
+ * 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 declare function getOrientationSigns(axesOrientations: Record<string, AnatomicalOrientation> | undefined): OrientationSigns;
+/**
+ * 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 declare function applyOrientationToAffine(affine: mat4, axesOrientations: Record<string, AnatomicalOrientation> | undefined): mat4;
+//# sourceMappingURL=orientation.d.ts.map

package/dist/utils/orientation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orientation.d.ts","sourceRoot":"","sources":["../../src/utils/orientation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAErC;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;CACnB;AAuBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,qBAAqB,GACjC,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAAG,SAAS,GAClE;IAAE,CAAC,EAAE,kBAAkB,CAAC;IAAC,CAAC,EAAE,kBAAkB,CAAC;IAAC,CAAC,EAAE,kBAAkB,CAAA;CAAE,CA2CzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAAG,SAAS,GAClE,gBAAgB,CAOlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,IAAI,EACZ,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAAG,SAAS,GAClE,IAAI,CAiDN"}

package/dist/utils/orientation.js

@@ -0,0 +1,225 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+/**
+ * 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 = {
+    // 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) {
+    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) {
+    const defaultMapping = {
+        x: { physicalRow: 0, sign: 1 },
+        y: { physicalRow: 1, sign: 1 },
+        z: { physicalRow: 2, sign: 1 },
+    };
+    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) {
+    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, axesOrientations) {
+    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;
+}
+//# sourceMappingURL=orientation.js.map

package/dist/utils/orientation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orientation.js","sourceRoot":"","sources":["../../src/utils/orientation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fideus-labs/fidnii",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Render OME-Zarr images in NiiVue with progressive multi-resolution loading",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,18 +16,18 @@
     "src"
   ],
   "dependencies": {
-    "@fideus-labs/fiff": "^0.3.2",
-    "@fideus-labs/ngff-zarr": "^0.11.0",
+    "@fideus-labs/fiff": "^0.5.2",
+    "@fideus-labs/ngff-zarr": "^0.12.0",
     "@itk-wasm/downsample": "^1.8.1",
-    "lru-cache": "^11.1.0",
     "@niivue/niivue": "^0.67.0",
     "gl-matrix": "^3.4.4",
+    "lru-cache": "^11.1.0",
     "nifti-reader-js": "^0.8.0",
     "zarrita": "^0.6.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@fideus-labs/fizarrita": "^1.3.0",
+    "@fideus-labs/fizarrita": "^1.4.0",
     "@fideus-labs/worker-pool": "^1.0.0",
     "@playwright/test": "^1.58.1",
     "@types/node": "^20.19.30",

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)