@vitessce/spatial-utils 3.6.6 → 3.6.8

package/dist/{deflate-Cumj_9kB.js → deflate-D50eseYg.js}

@@ -1,5 +1,5 @@
 import { i as inflate_1 } from "./pako.esm-SxljTded.js";
-import { B as BaseDecoder } from "./index-C6jVF_qi.js";
+import { B as BaseDecoder } from "./index-RMBcVNTZ.js";
 class DeflateDecoder extends BaseDecoder {
   decodeBlock(buffer) {
     return inflate_1(new Uint8Array(buffer)).buffer;

package/dist/{index-C6jVF_qi.js → index-RMBcVNTZ.js}

@@ -120365,22 +120365,22 @@ function addDecoder(cases, importFn) {
   }
   cases.forEach((c) => registry$2.set(c, importFn));
 }
-addDecoder([void 0, 1], () => import("./raw-DwHPYVQy.js").then((m) => m.default));
-addDecoder(5, () => import("./lzw-Ckpw-zOq.js").then((m) => m.default));
+addDecoder([void 0, 1], () => import("./raw-B-RRtlid.js").then((m) => m.default));
+addDecoder(5, () => import("./lzw-CS9qpOLK.js").then((m) => m.default));
 addDecoder(6, () => {
   throw new Error("old style JPEG compression is not supported.");
 });
-addDecoder(7, () => import("./jpeg-Bv9e5TsR.js").then((m) => m.default));
-addDecoder([8, 32946], () => import("./deflate-Cumj_9kB.js").then((m) => m.default));
-addDecoder(32773, () => import("./packbits-KgFJoulg.js").then((m) => m.default));
+addDecoder(7, () => import("./jpeg-Dp762_Sy.js").then((m) => m.default));
+addDecoder([8, 32946], () => import("./deflate-D50eseYg.js").then((m) => m.default));
+addDecoder(32773, () => import("./packbits-smBOUAP8.js").then((m) => m.default));
 addDecoder(
   34887,
-  () => import("./lerc-CN8oy9fE.js").then(async (m) => {
+  () => import("./lerc-R19D-u1d.js").then(async (m) => {
     await m.zstd.init();
     return m;
   }).then((m) => m.default)
 );
-addDecoder(50001, () => import("./webimage-BeD_xi6W.js").then((m) => m.default));
+addDecoder(50001, () => import("./webimage-CZyj01Qe.js").then((m) => m.default));
 function decodeRowAcc(row, stride) {
   let length2 = row.length - stride;
   let offset = 0;
@@ -137995,11 +137995,80 @@ function getNgffAxesForTiff(dimOrder) {
     type: getDefaultAxisType(name2)
   }));
 }
+function getSwapAxesMatrix(inputAxes, outputAxes) {
+  const size2 = inputAxes.length;
+  if (!(size2 === 2 || size2 === 3)) {
+    throw new Error(`Expected input and output axes to have 2 or 3 elements, got ${size2}.`);
+  }
+  const matrix2 = [
+    [0, 0, 0, 0],
+    [0, 0, 0, 0],
+    [0, 0, size2 === 2 ? 1 : 0, 0],
+    // In 2D, leave Z unchanged.
+    [0, 0, 0, 1]
+  ];
+  for (let outRow = 0; outRow < size2; outRow++) {
+    const axis = outputAxes[outRow];
+    const inCol = inputAxes.indexOf(axis);
+    if (inCol === -1) {
+      throw new Error(`Axis "${axis}" not found in inputAxes`);
+    }
+    matrix2[outRow][inCol] = 1;
+  }
+  return matrix2;
+}
 function coordinateTransformationsToMatrix(coordinateTransformations, axes) {
   let mat = new Matrix4().identity();
   if (coordinateTransformations && axes) {
     const xyzIndices = ["x", "y", "z"].map((name2) => axes.findIndex((axisObj) => axisObj.type === "space" && axisObj.name === name2));
     coordinateTransformations.forEach((transform2) => {
+      if (transform2.type === "affine") {
+        const { affine, input, output } = transform2;
+        const excludeEntries = input.axes.map((axis, i2) => [axis, i2]).filter(([axis, i2]) => axis.type !== "space").map(([axis, i2]) => i2);
+        const filteredAffine = affine.filter((_, i2) => !excludeEntries.includes(i2)).map((row) => row.filter((_, i2) => !excludeEntries.includes(i2)));
+        const spatialInputAxes = input.axes.filter((axis) => axis.type === "space");
+        const spatialOutputAxes = output.axes.filter((axis) => axis.type === "space");
+        const inputAxisNames = spatialInputAxes.map((axis) => axis.name);
+        const outputAxisNames = spatialOutputAxes.map((axis) => axis.name);
+        if (spatialInputAxes.length === 3) {
+          const nextMat = new Matrix4().fromArray([
+            ...filteredAffine[0],
+            ...filteredAffine[1],
+            ...filteredAffine[2],
+            0,
+            0,
+            0,
+            1
+          ]);
+          mat = mat.multiplyLeft(nextMat);
+          if (!isEqual$1(inputAxisNames, outputAxisNames)) {
+            const swapMatNested = getSwapAxesMatrix(inputAxisNames, outputAxisNames);
+            const swapMat = new Matrix4().fromArray(swapMatNested.flat());
+            mat = mat.multiplyLeft(swapMat);
+          }
+        } else if (spatialOutputAxes.length === 2) {
+          const nextMat = new Matrix4().fromArray([
+            ...filteredAffine[0],
+            ...filteredAffine[1],
+            0,
+            0,
+            1,
+            0,
+            0,
+            0,
+            0,
+            1
+          ]);
+          mat = mat.multiplyLeft(nextMat);
+          if (!isEqual$1(inputAxisNames, outputAxisNames)) {
+            const swapMatNested = getSwapAxesMatrix(inputAxisNames, outputAxisNames);
+            const swapMat = new Matrix4().fromArray(swapMatNested.flat());
+            mat = mat.multiplyLeft(swapMat);
+          }
+        } else {
+          throw new Error("Affine transformation must have 2 or 3 rows.");
+        }
+      }
       if (transform2.type === "translation") {
         const { translation: axisOrderedTranslation } = transform2;
         if (axisOrderedTranslation.length !== axes.length) {
@@ -138059,6 +138128,16 @@ function normalizeCoordinateTransformations(coordinateTransformations, datasets)
             scale: transform2.scale
           };
         }
+        if (type === "affine") {
+          return {
+            type,
+            affine: transform2.affine,
+            // Affine transformations can potentially swap axes,
+            // so we need to include the input and output axes.
+            input: transform2.input,
+            output: transform2.output
+          };
+        }
         if (type === "identity") {
           return { type };
         }
@@ -139564,6 +139643,24 @@ function createZarrArrayAdapter(arr) {
     }
   });
 }
+class VitessceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VitessceError";
+  }
+}
+class DataLoaderError extends VitessceError {
+  constructor(message) {
+    super(message);
+    this.name = "DataLoaderError";
+  }
+}
+class ZarrNodeNotFoundError extends DataLoaderError {
+  constructor(message) {
+    super(message);
+    this.name = "ZarrNodeNotFoundError";
+  }
+}
 function prevPowerOf2(x) {
   return 2 ** Math.floor(Math.log2(x));
 }
@@ -139581,7 +139678,15 @@ function isAxis(axisOrLabel) {
   return typeof axisOrLabel[0] !== "string";
 }
 async function loadMultiscales(root2) {
-  const rootAttrs = (await open(root2)).attrs;
+  let rootAttrs;
+  try {
+    rootAttrs = (await open(root2)).attrs;
+  } catch (e2) {
+    if (e2.name === "NodeNotFoundError") {
+      throw new ZarrNodeNotFoundError(root2.path);
+    }
+    throw e2;
+  }
   let paths = ["0"];
   let labels = ["t", "c", "z", "y", "x"];
   if ("multiscales" in rootAttrs) {
@@ -139594,6 +139699,8 @@ async function loadMultiscales(root2) {
         labels = axes;
       }
     }
+  } else {
+    throw new Error("Expected the Zarr store to contain OME-NGFF multiscales metadata.");
   }
   const data = paths.map((path) => open(root2.resolve(path), { kind: "array" }));
   return {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { D, e, a, b, c, d, F, G, Z, C, r, n, E, A, y, l, m, z, x, h, q, v, o, i, f, j, k, u, t, s, p, w } from "./index-C6jVF_qi.js";
+import { D, e, a, b, c, d, F, G, Z, C, r, n, E, A, y, l, m, z, x, h, q, v, o, i, f, j, k, u, t, s, p, w } from "./index-RMBcVNTZ.js";
 export {
   D as DEFAULT_CELLS_LAYER,
   e as DEFAULT_LAYER_TYPE_ORDERING,

package/dist/{jpeg-Bv9e5TsR.js → jpeg-Dp762_Sy.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-C6jVF_qi.js";
+import { B as BaseDecoder } from "./index-RMBcVNTZ.js";
 const dctZigZag = new Int32Array([
   0,
   1,

package/dist/{lerc-CN8oy9fE.js → lerc-R19D-u1d.js}

@@ -1,5 +1,5 @@
 import { i as inflate_1 } from "./pako.esm-SxljTded.js";
-import { g as getDefaultExportFromCjs, B as BaseDecoder } from "./index-C6jVF_qi.js";
+import { g as getDefaultExportFromCjs, B as BaseDecoder } from "./index-RMBcVNTZ.js";
 const LercParameters = {
   AddCompression: 1
 };

package/dist/{lzw-Ckpw-zOq.js → lzw-CS9qpOLK.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-C6jVF_qi.js";
+import { B as BaseDecoder } from "./index-RMBcVNTZ.js";
 const MIN_BITS = 9;
 const CLEAR_CODE = 256;
 const EOI_CODE = 257;

package/dist/{packbits-KgFJoulg.js → packbits-smBOUAP8.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-C6jVF_qi.js";
+import { B as BaseDecoder } from "./index-RMBcVNTZ.js";
 class PackbitsDecoder extends BaseDecoder {
   decodeBlock(buffer) {
     const dataView = new DataView(buffer);

package/dist/{raw-DwHPYVQy.js → raw-B-RRtlid.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-C6jVF_qi.js";
+import { B as BaseDecoder } from "./index-RMBcVNTZ.js";
 class RawDecoder extends BaseDecoder {
   decodeBlock(buffer) {
     return buffer;

package/dist/{webimage-BeD_xi6W.js → webimage-CZyj01Qe.js}

@@ -1,4 +1,4 @@
-import { B as BaseDecoder } from "./index-C6jVF_qi.js";
+import { B as BaseDecoder } from "./index-RMBcVNTZ.js";
 class WebImageDecoder extends BaseDecoder {
   constructor() {
     super();

package/dist-tsc/load-ome-zarr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-ome-zarr.d.ts","sourceRoot":"","sources":["../src/load-ome-zarr.js"],"names":[],"mappings":"AAkBA,gDAMC;AAiDD;;;GAaC;AA7BD;IACE,kDASC;IADC,qBAAwB;CAE3B;oBApEmB,cAAc"}
+{"version":3,"file":"load-ome-zarr.d.ts","sourceRoot":"","sources":["../src/load-ome-zarr.js"],"names":[],"mappings":"AAmBA,gDAMC;AA6DD;;;GAaC;AA7BD;IACE,kDASC;IADC,qBAAwB;CAE3B;oBAjFmB,cAAc"}

package/dist-tsc/load-ome-zarr.js

@@ -1,6 +1,7 @@
 import { viv } from '@vitessce/gl';
 import { open as zarrOpen } from 'zarrita';
 import { createZarrArrayAdapter } from '@vitessce/zarr-utils';
+import { ZarrNodeNotFoundError } from '@vitessce/error';
 function prevPowerOf2(x) {
     return 2 ** Math.floor(Math.log2(x));
 }
@@ -24,7 +25,17 @@ function isAxis(axisOrLabel) {
     return typeof axisOrLabel[0] !== 'string';
 }
 async function loadMultiscales(root) {
-    const rootAttrs = (await zarrOpen(root)).attrs;
+    let rootAttrs;
+    try {
+        rootAttrs = (await zarrOpen(root)).attrs;
+    }
+    catch (e) {
+        if (e.name === 'NodeNotFoundError') {
+            throw new ZarrNodeNotFoundError(root.path);
+        }
+        // Re-throw the error if it is not a NodeNotFoundError.
+        throw e;
+    }
     let paths = ['0'];
     // Default axes used for v0.1 and v0.2.
     let labels = ['t', 'c', 'z', 'y', 'x'];
@@ -40,6 +51,10 @@ async function loadMultiscales(root) {
             }
         }
     }
+    else {
+        // TODO: Relax this after https://github.com/vitessce/vitessce/issues/2199
+        throw new Error('Expected the Zarr store to contain OME-NGFF multiscales metadata.');
+    }
     const data = paths
         .map(path => zarrOpen(root.resolve(path), { kind: 'array' }));
     return {

package/dist-tsc/spatial.d.ts

@@ -41,6 +41,14 @@ export function getNgffAxes(firstMultiscalesAxes: any): {
     name: string;
 }[];
 export function getNgffAxesForTiff(dimOrder: any): any;
+/**
+ * Get a 4x4 matrix that swaps axes.
+ * TODO: add unit tests.
+ * @param {("x"|"y"|"z")[]} inputAxes
+ * @param {("x"|"y"|"z")[]} outputAxes
+ * @return {number[][]} 4x4 matrix that swaps axes.
+ */
+export function getSwapAxesMatrix(inputAxes: ("x" | "y" | "z")[], outputAxes: ("x" | "y" | "z")[]): number[][];
 /**
  * Convert an array of coordinateTransformations objects to a 16-element
  * plain JS array using Matrix4 linear algebra transformation functions.

package/dist-tsc/spatial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spatial.d.ts","sourceRoot":"","sources":["../src/spatial.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,4CAJW,MAAM,SACN,MAAM,GAAG,SAAS,GAChB,MAAM,CAMlB;AAoCD;;;;GAIG;AACH,8BAHW,MAAM,YACN,KAAK,GAAC,IAAI,WAiBpB;AAID,sHAmCC;AAiHD;;GAEG;AACH,qCAFW,KAAK,CAAE,MAAM,CAAC,WAKxB;AAED;;;;;;GAMG;AACH,gDALW,MAAM,eAEJ,MAAM,EAAE,CAuCpB;AAED;;;;;;;;;GASG;AACH,gEAJW,MAAM,EAAE,sBAER,CAAC,MAAM,EAAE,GAAC,IAAI,CAAC,+CAuEzB;AASD;;;IAuBC;AAED,uDAQC;AAED;;;;;;;;GAQG;AACH,6EANW,MAAM,EAAE,GAAC,SAAS,QAElB,MAAM,EAAE,GAAC,SAAS,GAEhB,OAAO,CA4CnB;AAED,6CAOC;AAMD,8CASC;AAED;;;;;;;;;GASG;AACH,8EANW,MAAM,EAAE,GAAC,SAAS,YAGlB,MAAM,EAAE,GACN,MAAM,EAAE,CAoDpB;AAvgBM;;;;;EAYN;AAEM,yEAkBN;wBAnDuB,SAAS"}
+{"version":3,"file":"spatial.d.ts","sourceRoot":"","sources":["../src/spatial.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,4CAJW,MAAM,SACN,MAAM,GAAG,SAAS,GAChB,MAAM,CAMlB;AAoCD;;;;GAIG;AACH,8BAHW,MAAM,YACN,KAAK,GAAC,IAAI,WAiBpB;AAID,sHAmCC;AAiHD;;GAEG;AACH,qCAFW,KAAK,CAAE,MAAM,CAAC,WAKxB;AAED;;;;;;GAMG;AACH,gDALW,MAAM,eAEJ,MAAM,EAAE,CAuCpB;AAED;;;;;;;;;GASG;AACH,gEAJW,MAAM,EAAE,sBAER,CAAC,MAAM,EAAE,GAAC,IAAI,CAAC,+CAuEzB;AASD;;;IAuBC;AAED,uDAQC;AAED;;;;;;GAMG;AACH,6CAJW,CAAC,GAAG,GAAC,GAAG,GAAC,GAAG,CAAC,EAAE,cACf,CAAC,GAAG,GAAC,GAAG,GAAC,GAAG,CAAC,EAAE,GACd,MAAM,EAAE,EAAE,CA6BrB;AAED;;;;;;;;GAQG;AACH,6EANW,MAAM,EAAE,GAAC,SAAS,QAElB,MAAM,EAAE,GAAC,SAAS,GAEhB,OAAO,CA0GnB;AAED,6CAOC;AAMD,8CASC;AAED;;;;;;;;;GASG;AACH,8EANW,MAAM,EAAE,GAAC,SAAS,YAGlB,MAAM,EAAE,GACN,MAAM,EAAE,CA+DpB;AApnBM;;;;;EAYN;AAEM,yEAkBN;wBAnDuB,SAAS"}

package/dist-tsc/spatial.js

@@ -356,6 +356,38 @@ export function getNgffAxesForTiff(dimOrder) {
         type: getDefaultAxisType(name),
     }));
 }
+/**
+ * Get a 4x4 matrix that swaps axes.
+ * TODO: add unit tests.
+ * @param {("x"|"y"|"z")[]} inputAxes
+ * @param {("x"|"y"|"z")[]} outputAxes
+ * @return {number[][]} 4x4 matrix that swaps axes.
+ */
+export function getSwapAxesMatrix(inputAxes, outputAxes) {
+    const size = inputAxes.length;
+    if (!(size === 2 || size === 3)) {
+        throw new Error(`Expected input and output axes to have 2 or 3 elements, got ${size}.`);
+    }
+    // Initialize a 4x4 matrix.
+    const matrix = [
+        [0, 0, 0, 0],
+        [0, 0, 0, 0],
+        [0, 0, (size === 2 ? 1 : 0), 0], // In 2D, leave Z unchanged.
+        [0, 0, 0, 1],
+    ];
+    // Fill linear transformation (top-left 3x3)
+    // Iterate over output rows.
+    for (let outRow = 0; outRow < size; outRow++) {
+        // Get the axis name for the current output row.
+        const axis = outputAxes[outRow];
+        const inCol = inputAxes.indexOf(axis);
+        if (inCol === -1) {
+            throw new Error(`Axis "${axis}" not found in inputAxes`);
+        }
+        matrix[outRow][inCol] = 1;
+    }
+    return matrix;
+}
 /**
  * Convert an array of coordinateTransformations objects to a 16-element
  * plain JS array using Matrix4 linear algebra transformation functions.
@@ -373,6 +405,58 @@ export function coordinateTransformationsToMatrix(coordinateTransformations, axe
         // Apply each transformation sequentially and in order according to the OME-NGFF v0.4 spec.
         // Reference: https://ngff.openmicroscopy.org/0.4/#trafo-md
         coordinateTransformations.forEach((transform) => {
+            if (transform.type === 'affine') {
+                const { affine, input, output } = transform;
+                // This is needed since axes can include "c" for example.
+                const excludeEntries = input.axes
+                    .map((axis, i) => ([axis, i]))
+                    // eslint-disable-next-line no-unused-vars
+                    .filter(([axis, i]) => axis.type !== 'space')
+                    // eslint-disable-next-line no-unused-vars
+                    .map(([axis, i]) => i);
+                // We only want to keep the affine transformation entries for the spatial axes.
+                const filteredAffine = affine
+                    .filter((_, i) => !excludeEntries.includes(i))
+                    .map(row => row.filter((_, i) => !excludeEntries.includes(i)));
+                // TODO: if there was some affine transformation for the "c" axis, warn/error.
+                const spatialInputAxes = input.axes.filter(axis => axis.type === 'space');
+                const spatialOutputAxes = output.axes.filter(axis => axis.type === 'space');
+                const inputAxisNames = spatialInputAxes.map(axis => axis.name);
+                const outputAxisNames = spatialOutputAxes.map(axis => axis.name);
+                if (spatialInputAxes.length === 3) { // 3D case
+                    const nextMat = (new Matrix4()).fromArray([
+                        ...filteredAffine[0],
+                        ...filteredAffine[1],
+                        ...filteredAffine[2],
+                        0, 0, 0, 1,
+                    ]);
+                    mat = mat.multiplyLeft(nextMat);
+                    if (!isEqual(inputAxisNames, outputAxisNames)) {
+                        // Handle 3D axis swapping.
+                        const swapMatNested = getSwapAxesMatrix(inputAxisNames, outputAxisNames);
+                        const swapMat = (new Matrix4()).fromArray(swapMatNested.flat());
+                        mat = mat.multiplyLeft(swapMat);
+                    }
+                }
+                else if (spatialOutputAxes.length === 2) { // 2D case
+                    const nextMat = (new Matrix4()).fromArray([
+                        ...filteredAffine[0],
+                        ...filteredAffine[1],
+                        0, 0, 1, 0,
+                        0, 0, 0, 1,
+                    ]);
+                    mat = mat.multiplyLeft(nextMat);
+                    if (!isEqual(inputAxisNames, outputAxisNames)) {
+                        // Handle 2D axis swapping.
+                        const swapMatNested = getSwapAxesMatrix(inputAxisNames, outputAxisNames);
+                        const swapMat = (new Matrix4()).fromArray(swapMatNested.flat());
+                        mat = mat.multiplyLeft(swapMat);
+                    }
+                }
+                else {
+                    throw new Error('Affine transformation must have 2 or 3 rows.');
+                }
+            }
             if (transform.type === 'translation') {
                 const { translation: axisOrderedTranslation } = transform;
                 if (axisOrderedTranslation.length !== axes.length) {
@@ -385,6 +469,7 @@ export function coordinateTransformationsToMatrix(coordinateTransformations, axe
                     : defaultValue));
                 const nextMat = (new Matrix4()).translate(xyzTranslation);
                 mat = mat.multiplyLeft(nextMat);
+                // TODO: error if the user tries to use a translation on the "c" axis.
             }
             if (transform.type === 'scale') {
                 const { scale: axisOrderedScale } = transform;
@@ -399,6 +484,7 @@ export function coordinateTransformationsToMatrix(coordinateTransformations, axe
                     : defaultValue));
                 const nextMat = (new Matrix4()).scale(xyzScale);
                 mat = mat.multiplyLeft(nextMat);
+                // TODO: error if the user tries to use a scale on the "c" axis.
             }
         });
     }
@@ -457,6 +543,16 @@ export function normalizeCoordinateTransformations(coordinateTransformations, da
                         scale: transform.scale,
                     };
                 }
+                if (type === 'affine') {
+                    return {
+                        type,
+                        affine: transform.affine,
+                        // Affine transformations can potentially swap axes,
+                        // so we need to include the input and output axes.
+                        input: transform.input,
+                        output: transform.output,
+                    };
+                }
                 if (type === 'identity') {
                     return { type };
                 }

package/dist-tsc/spatial.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { coordinateTransformationsToMatrix, normalizeCoordinateTransformations, } from './spatial.js';
+import { coordinateTransformationsToMatrix, normalizeCoordinateTransformations, getSwapAxesMatrix, } from './spatial.js';
 const defaultAxes = [
     { type: 'time', name: 't' },
     { type: 'channel', name: 'c' },
@@ -35,6 +35,125 @@ describe('Spatial.js', () => {
                 0, 0, 0, 1,
             ]);
         });
+        it('swap axes works for 2D', () => {
+            const inputAxes = ['x', 'y'];
+            const outputAxes = ['y', 'x'];
+            const swapMatrix = getSwapAxesMatrix(inputAxes, outputAxes);
+            expect(swapMatrix.flat()).toEqual([
+                0, 1, 0, 0,
+                1, 0, 0, 0,
+                0, 0, 1, 0,
+                0, 0, 0, 1,
+            ]);
+        });
+        it('swap axes works for 3D', () => {
+            const inputAxes = ['x', 'y', 'z'];
+            const outputAxes = ['z', 'y', 'x'];
+            const swapMatrix = getSwapAxesMatrix(inputAxes, outputAxes);
+            expect(swapMatrix.flat()).toEqual([
+                0, 0, 1, 0,
+                0, 1, 0, 0,
+                1, 0, 0, 0,
+                0, 0, 0, 1,
+            ]);
+        });
+        it('swap axes works for 3D, different order', () => {
+            const inputAxes = ['x', 'z', 'y'];
+            const outputAxes = ['x', 'y', 'z'];
+            const swapMatrix = getSwapAxesMatrix(inputAxes, outputAxes);
+            expect(swapMatrix.flat()).toEqual([
+                1, 0, 0, 0,
+                0, 0, 1, 0,
+                0, 1, 0, 0,
+                0, 0, 0, 1,
+            ]);
+        });
+        it('supports 3D affine transformation, for coordinate system with C axis', () => {
+            const coordinateTransformations = [
+                { type: 'scale', scale: [1, 1, 1, 1] },
+                {
+                    type: 'affine',
+                    affine: [
+                        [1, 0, 0, 0, 0],
+                        [0, 0, 0, 1, 0],
+                        [0, 0, 1, 0, 0],
+                        [0, 13.76, 0, 0, -13.76],
+                    ],
+                    input: {
+                        name: 'czyx',
+                        axes: [
+                            { type: 'channel', name: 'c' },
+                            { type: 'space', name: 'x' },
+                            { type: 'space', name: 'y' },
+                            { type: 'space', name: 'z' },
+                        ],
+                    },
+                    output: {
+                        name: 'global',
+                        axes: [
+                            // Notice: swap-axes (CXYZ to CZYX).
+                            { type: 'channel', name: 'c' },
+                            { type: 'space', name: 'z' },
+                            { type: 'space', name: 'y' },
+                            { type: 'space', name: 'x' },
+                        ],
+                    },
+                },
+            ];
+            const axes = [
+                { type: 'channel', name: 'c' },
+                { type: 'space', name: 'x' },
+                { type: 'space', name: 'y' },
+                { type: 'space', name: 'z' },
+            ];
+            expect(coordinateTransformationsToMatrix(coordinateTransformations, axes)).toEqual([
+                1, 0, 0, 0,
+                0, 1, 0, 0,
+                0, 0, 13.76, -13.76, // scale in Z by 13.76; translate in Z by -13.76 after scaling.
+                0, 0, 0, 1,
+            ]);
+        });
+        it('supports 3D affine transformation, for coordinate system without C axis', () => {
+            const coordinateTransformations = [
+                { type: 'scale', scale: [1, 1, 1] },
+                {
+                    type: 'affine',
+                    affine: [
+                        [0, 0, 1, 0],
+                        [0, 1, 0, 0],
+                        [13.76, 0, 0, -13.76],
+                    ],
+                    input: {
+                        name: 'zyx',
+                        axes: [
+                            { type: 'space', name: 'z' },
+                            { type: 'space', name: 'y' },
+                            { type: 'space', name: 'x' },
+                        ],
+                    },
+                    output: {
+                        name: 'global',
+                        axes: [
+                            // Notice: swap-axes (ZYX to XYZ).
+                            { type: 'space', name: 'x' },
+                            { type: 'space', name: 'y' },
+                            { type: 'space', name: 'z' },
+                        ],
+                    },
+                },
+            ];
+            const axes = [
+                { type: 'space', name: 'z' },
+                { type: 'space', name: 'y' },
+                { type: 'space', name: 'x' },
+            ];
+            expect(coordinateTransformationsToMatrix(coordinateTransformations, axes)).toEqual([
+                1, 0, 0, 0,
+                0, 1, 0, 0,
+                0, 0, 13.76, -13.76, // scale in Z by 13.76; translate in Z by -13.76 after scaling.
+                0, 0, 0, 1,
+            ]);
+        });
     });
     describe('normalizeCoordinateTransformations', () => {
         it('does nothing for OME-NGFF v0.4 input', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitessce/spatial-utils",
-  "version": "3.6.6",
+  "version": "3.6.8",
   "author": "HIDIVE Lab at HMS",
   "homepage": "http://vitessce.io",
   "repository": {
@@ -20,11 +20,12 @@
     "zarrita": "0.5.2",
     "math.gl": "^3.5.6",
     "mathjs": "^9.2.0",
-    "@vitessce/gl": "3.6.6",
-    "@vitessce/utils": "3.6.6",
-    "@vitessce/zarr-utils": "3.6.6",
-    "@vitessce/constants-internal": "3.6.6",
-    "@vitessce/globals": "3.6.6"
+    "@vitessce/gl": "3.6.8",
+    "@vitessce/utils": "3.6.8",
+    "@vitessce/zarr-utils": "3.6.8",
+    "@vitessce/constants-internal": "3.6.8",
+    "@vitessce/globals": "3.6.8",
+    "@vitessce/error": "3.6.8"
   },
   "scripts": {
     "bundle": "pnpm exec vite build -c ../../../scripts/vite.config.js",

package/src/load-ome-zarr.js

@@ -1,6 +1,7 @@
 import { viv } from '@vitessce/gl';
 import { open as zarrOpen } from 'zarrita';
 import { createZarrArrayAdapter } from '@vitessce/zarr-utils';
+import { ZarrNodeNotFoundError } from '@vitessce/error';
 
 function prevPowerOf2(x) {
   return 2 ** Math.floor(Math.log2(x));
@@ -29,7 +30,16 @@ function isAxis(axisOrLabel) {
 }
 
 async function loadMultiscales(root) {
-  const rootAttrs = (await zarrOpen(root)).attrs;
+  let rootAttrs;
+  try {
+    rootAttrs = (await zarrOpen(root)).attrs;
+  } catch (e) {
+    if (e.name === 'NodeNotFoundError') {
+      throw new ZarrNodeNotFoundError(root.path);
+    }
+    // Re-throw the error if it is not a NodeNotFoundError.
+    throw e;
+  }
 
   let paths = ['0'];
   // Default axes used for v0.1 and v0.2.
@@ -44,6 +54,9 @@ async function loadMultiscales(root) {
         labels = axes;
       }
     }
+  } else {
+    // TODO: Relax this after https://github.com/vitessce/vitessce/issues/2199
+    throw new Error('Expected the Zarr store to contain OME-NGFF multiscales metadata.');
   }
 
   const data = paths

package/src/spatial.js

@@ -400,6 +400,42 @@ export function getNgffAxesForTiff(dimOrder) {
     }));
 }
 
+/**
+ * Get a 4x4 matrix that swaps axes.
+ * TODO: add unit tests.
+ * @param {("x"|"y"|"z")[]} inputAxes
+ * @param {("x"|"y"|"z")[]} outputAxes
+ * @return {number[][]} 4x4 matrix that swaps axes.
+ */
+export function getSwapAxesMatrix(inputAxes, outputAxes) {
+  const size = inputAxes.length;
+  if (!(size === 2 || size === 3)) {
+    throw new Error(`Expected input and output axes to have 2 or 3 elements, got ${size}.`);
+  }
+
+  // Initialize a 4x4 matrix.
+  const matrix = [
+    [0, 0, 0, 0],
+    [0, 0, 0, 0],
+    [0, 0, (size === 2 ? 1 : 0), 0], // In 2D, leave Z unchanged.
+    [0, 0, 0, 1],
+  ];
+
+  // Fill linear transformation (top-left 3x3)
+  // Iterate over output rows.
+  for (let outRow = 0; outRow < size; outRow++) {
+    // Get the axis name for the current output row.
+    const axis = outputAxes[outRow];
+    const inCol = inputAxes.indexOf(axis);
+    if (inCol === -1) {
+      throw new Error(`Axis "${axis}" not found in inputAxes`);
+    }
+    matrix[outRow][inCol] = 1;
+  }
+
+  return matrix;
+}
+
 /**
  * Convert an array of coordinateTransformations objects to a 16-element
  * plain JS array using Matrix4 linear algebra transformation functions.
@@ -417,6 +453,64 @@ export function coordinateTransformationsToMatrix(coordinateTransformations, axe
     // Apply each transformation sequentially and in order according to the OME-NGFF v0.4 spec.
     // Reference: https://ngff.openmicroscopy.org/0.4/#trafo-md
     coordinateTransformations.forEach((transform) => {
+      if (transform.type === 'affine') {
+        const { affine, input, output } = transform;
+
+        // This is needed since axes can include "c" for example.
+        const excludeEntries = input.axes
+          .map((axis, i) => ([axis, i]))
+          // eslint-disable-next-line no-unused-vars
+          .filter(([axis, i]) => axis.type !== 'space')
+          // eslint-disable-next-line no-unused-vars
+          .map(([axis, i]) => i);
+
+        // We only want to keep the affine transformation entries for the spatial axes.
+        const filteredAffine = affine
+          .filter((_, i) => !excludeEntries.includes(i))
+          .map(row => row.filter((_, i) => !excludeEntries.includes(i)));
+
+        // TODO: if there was some affine transformation for the "c" axis, warn/error.
+
+        const spatialInputAxes = input.axes.filter(axis => axis.type === 'space');
+        const spatialOutputAxes = output.axes.filter(axis => axis.type === 'space');
+
+        const inputAxisNames = spatialInputAxes.map(axis => axis.name);
+        const outputAxisNames = spatialOutputAxes.map(axis => axis.name);
+
+        if (spatialInputAxes.length === 3) { // 3D case
+          const nextMat = (new Matrix4()).fromArray([
+            ...filteredAffine[0],
+            ...filteredAffine[1],
+            ...filteredAffine[2],
+            0, 0, 0, 1,
+          ]);
+          mat = mat.multiplyLeft(nextMat);
+
+          if (!isEqual(inputAxisNames, outputAxisNames)) {
+            // Handle 3D axis swapping.
+            const swapMatNested = getSwapAxesMatrix(inputAxisNames, outputAxisNames);
+            const swapMat = (new Matrix4()).fromArray(swapMatNested.flat());
+            mat = mat.multiplyLeft(swapMat);
+          }
+        } else if (spatialOutputAxes.length === 2) { // 2D case
+          const nextMat = (new Matrix4()).fromArray([
+            ...filteredAffine[0],
+            ...filteredAffine[1],
+            0, 0, 1, 0,
+            0, 0, 0, 1,
+          ]);
+          mat = mat.multiplyLeft(nextMat);
+
+          if (!isEqual(inputAxisNames, outputAxisNames)) {
+            // Handle 2D axis swapping.
+            const swapMatNested = getSwapAxesMatrix(inputAxisNames, outputAxisNames);
+            const swapMat = (new Matrix4()).fromArray(swapMatNested.flat());
+            mat = mat.multiplyLeft(swapMat);
+          }
+        } else {
+          throw new Error('Affine transformation must have 2 or 3 rows.');
+        }
+      }
       if (transform.type === 'translation') {
         const { translation: axisOrderedTranslation } = transform;
         if (axisOrderedTranslation.length !== axes.length) {
@@ -431,6 +525,8 @@ export function coordinateTransformationsToMatrix(coordinateTransformations, axe
         ));
         const nextMat = (new Matrix4()).translate(xyzTranslation);
         mat = mat.multiplyLeft(nextMat);
+
+        // TODO: error if the user tries to use a translation on the "c" axis.
       }
       if (transform.type === 'scale') {
         const { scale: axisOrderedScale } = transform;
@@ -447,6 +543,8 @@ export function coordinateTransformationsToMatrix(coordinateTransformations, axe
         ));
         const nextMat = (new Matrix4()).scale(xyzScale);
         mat = mat.multiplyLeft(nextMat);
+
+        // TODO: error if the user tries to use a scale on the "c" axis.
       }
     });
   }
@@ -510,12 +608,23 @@ export function normalizeCoordinateTransformations(coordinateTransformations, da
             scale: transform.scale,
           };
         }
+        if (type === 'affine') {
+          return {
+            type,
+            affine: transform.affine,
+            // Affine transformations can potentially swap axes,
+            // so we need to include the input and output axes.
+            input: transform.input,
+            output: transform.output,
+          };
+        }
         if (type === 'identity') {
           return { type };
         }
         if (type === 'sequence') {
           return normalizeCoordinateTransformations(transform.transformations, datasets);
         }
+
         log.warn(`Coordinate transformation type "${type}" is not supported.`);
       }
       // Assume it was already an old-style (NGFF v0.4) coordinate transformation.

package/src/spatial.test.js

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
 import {
   coordinateTransformationsToMatrix,
   normalizeCoordinateTransformations,
+  getSwapAxesMatrix,
 } from './spatial.js';
 
 const defaultAxes = [
@@ -40,6 +41,127 @@ describe('Spatial.js', () => {
         0, 0, 0, 1,
       ]);
     });
+
+    it('swap axes works for 2D', () => {
+      const inputAxes = ['x', 'y'];
+      const outputAxes = ['y', 'x'];
+      const swapMatrix = getSwapAxesMatrix(inputAxes, outputAxes);
+      expect(swapMatrix.flat()).toEqual([
+        0, 1, 0, 0,
+        1, 0, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+      ]);
+    });
+    it('swap axes works for 3D', () => {
+      const inputAxes = ['x', 'y', 'z'];
+      const outputAxes = ['z', 'y', 'x'];
+      const swapMatrix = getSwapAxesMatrix(inputAxes, outputAxes);
+      expect(swapMatrix.flat()).toEqual([
+        0, 0, 1, 0,
+        0, 1, 0, 0,
+        1, 0, 0, 0,
+        0, 0, 0, 1,
+      ]);
+    });
+    it('swap axes works for 3D, different order', () => {
+      const inputAxes = ['x', 'z', 'y'];
+      const outputAxes = ['x', 'y', 'z'];
+      const swapMatrix = getSwapAxesMatrix(inputAxes, outputAxes);
+      expect(swapMatrix.flat()).toEqual([
+        1, 0, 0, 0,
+        0, 0, 1, 0,
+        0, 1, 0, 0,
+        0, 0, 0, 1,
+      ]);
+    });
+
+    it('supports 3D affine transformation, for coordinate system with C axis', () => {
+      const coordinateTransformations = [
+        { type: 'scale', scale: [1, 1, 1, 1] },
+        {
+          type: 'affine',
+          affine: [
+            [1, 0, 0, 0, 0],
+            [0, 0, 0, 1, 0],
+            [0, 0, 1, 0, 0],
+            [0, 13.76, 0, 0, -13.76],
+          ],
+          input: {
+            name: 'czyx',
+            axes: [
+              { type: 'channel', name: 'c' },
+              { type: 'space', name: 'x' },
+              { type: 'space', name: 'y' },
+              { type: 'space', name: 'z' },
+            ],
+          },
+          output: {
+            name: 'global',
+            axes: [
+              // Notice: swap-axes (CXYZ to CZYX).
+              { type: 'channel', name: 'c' },
+              { type: 'space', name: 'z' },
+              { type: 'space', name: 'y' },
+              { type: 'space', name: 'x' },
+            ],
+          },
+        },
+      ];
+      const axes = [
+        { type: 'channel', name: 'c' },
+        { type: 'space', name: 'x' },
+        { type: 'space', name: 'y' },
+        { type: 'space', name: 'z' },
+      ];
+      expect(coordinateTransformationsToMatrix(coordinateTransformations, axes)).toEqual([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 13.76, -13.76, // scale in Z by 13.76; translate in Z by -13.76 after scaling.
+        0, 0, 0, 1,
+      ]);
+    });
+    it('supports 3D affine transformation, for coordinate system without C axis', () => {
+      const coordinateTransformations = [
+        { type: 'scale', scale: [1, 1, 1] },
+        {
+          type: 'affine',
+          affine: [
+            [0, 0, 1, 0],
+            [0, 1, 0, 0],
+            [13.76, 0, 0, -13.76],
+          ],
+          input: {
+            name: 'zyx',
+            axes: [
+              { type: 'space', name: 'z' },
+              { type: 'space', name: 'y' },
+              { type: 'space', name: 'x' },
+            ],
+          },
+          output: {
+            name: 'global',
+            axes: [
+              // Notice: swap-axes (ZYX to XYZ).
+              { type: 'space', name: 'x' },
+              { type: 'space', name: 'y' },
+              { type: 'space', name: 'z' },
+            ],
+          },
+        },
+      ];
+      const axes = [
+        { type: 'space', name: 'z' },
+        { type: 'space', name: 'y' },
+        { type: 'space', name: 'x' },
+      ];
+      expect(coordinateTransformationsToMatrix(coordinateTransformations, axes)).toEqual([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 13.76, -13.76, // scale in Z by 13.76; translate in Z by -13.76 after scaling.
+        0, 0, 0, 1,
+      ]);
+    });
   });
   describe('normalizeCoordinateTransformations', () => {
     it('does nothing for OME-NGFF v0.4 input', () => {