@aics/vole-core 3.12.4

package/es/loaders/zarr_utils/WrappedStore.js

@@ -0,0 +1,51 @@
+/**
+ * `Readable` is zarrita's minimal abstraction for any source of data.
+ * `WrappedStore` wraps another `Readable` and adds (optional) connections to `VolumeCache` and `RequestQueue`.
+ */
+class WrappedStore {
+  constructor(baseStore, cache, queue) {
+    this.baseStore = baseStore;
+    this.cache = cache;
+    this.queue = queue;
+  }
+  // Dummy implementation to make this class easier to use in tests
+  set(_key, _value) {
+    return Promise.resolve();
+  }
+  async getAndCache(key, cacheKey, opts) {
+    const result = await this.baseStore.get(key, opts);
+    if (this.cache && result) {
+      this.cache.insert(cacheKey, result);
+    }
+    return result;
+  }
+  async get(key, opts) {
+    const ZARR_EXTS = [".zarray", ".zgroup", ".zattrs", "zarr.json"];
+    if (!this.cache || ZARR_EXTS.some(s => key.endsWith(s))) {
+      return this.baseStore.get(key, opts?.options);
+    }
+    if (opts?.reportKey) {
+      opts.reportKey(key, opts.subscriber);
+    }
+    let keyPrefix = this.baseStore.url ?? "";
+    if (keyPrefix !== "" && !(keyPrefix instanceof URL) && !keyPrefix.endsWith("/")) {
+      keyPrefix += "/";
+    }
+    const fullKey = keyPrefix + key.slice(1);
+
+    // Check the cache
+    const cacheResult = this.cache.get(fullKey);
+    if (cacheResult) {
+      return new Uint8Array(cacheResult);
+    }
+
+    // Not in cache; load the chunk and cache it
+    if (this.queue && opts) {
+      return this.queue.addRequest(fullKey, opts.subscriber, () => this.getAndCache(key, fullKey, opts?.options), opts.isPrefetch);
+    } else {
+      // Should we ever hit this code?  We should always have a request queue.
+      return this.getAndCache(key, fullKey, opts?.options);
+    }
+  }
+}
+export default WrappedStore;

package/es/loaders/zarr_utils/types.js

@@ -0,0 +1,24 @@
+/**
+ * Directions in which to move outward from the loaded set of chunks while prefetching.
+ *
+ * Ordered in pairs of opposite directions both because that's a sensible order in which to prefetch for our purposes,
+ * and because it lets us treat the least significant bit as the sign. So `direction >> 1` gives the index of the
+ * direction in TZYX-ordered arrays, and `direction & 1` gives the sign of the direction (e.g. positive vs negative Z).
+ */
+export let PrefetchDirection = /*#__PURE__*/function (PrefetchDirection) {
+  PrefetchDirection[PrefetchDirection["T_MINUS"] = 0] = "T_MINUS";
+  PrefetchDirection[PrefetchDirection["T_PLUS"] = 1] = "T_PLUS";
+  PrefetchDirection[PrefetchDirection["Z_MINUS"] = 2] = "Z_MINUS";
+  PrefetchDirection[PrefetchDirection["Z_PLUS"] = 3] = "Z_PLUS";
+  PrefetchDirection[PrefetchDirection["Y_MINUS"] = 4] = "Y_MINUS";
+  PrefetchDirection[PrefetchDirection["Y_PLUS"] = 5] = "Y_PLUS";
+  PrefetchDirection[PrefetchDirection["X_MINUS"] = 6] = "X_MINUS";
+  PrefetchDirection[PrefetchDirection["X_PLUS"] = 7] = "X_PLUS";
+  return PrefetchDirection;
+}({});
+
+/** https://ngff.openmicroscopy.org/latest/#multiscale-md */
+
+/** https://ngff.openmicroscopy.org/latest/#omero-md */
+
+/** A record with everything we need to access and use a single remote source of multiscale OME-Zarr data. */

package/es/loaders/zarr_utils/utils.js

@@ -0,0 +1,225 @@
+import { VolumeLoadErrorType, VolumeLoadError } from "../VolumeLoadError.js";
+/** Extracts channel names from a `ZarrSource`. Handles missing `omeroMetadata`. Does *not* resolve name collisions. */
+export function getSourceChannelNames(src) {
+  if (src.omeroMetadata?.channels) {
+    return src.omeroMetadata.channels.map(({
+      label
+    }, idx) => label ?? `Channel ${idx + src.channelOffset}`);
+  }
+  const length = src.scaleLevels[0].shape[src.axesTCZYX[1]];
+  return Array.from({
+    length
+  }, (_, idx) => `Channel ${idx + src.channelOffset}`);
+}
+
+/** Turns `axesTCZYX` into the number of dimensions in the array */
+export const getDimensionCount = ([t, c, z]) => 2 + Number(t > -1) + Number(c > -1) + Number(z > -1);
+export function remapAxesToTCZYX(axes) {
+  const axesTCZYX = [-1, -1, -1, -1, -1];
+  const axisNames = ["t", "c", "z", "y", "x"];
+  axes.forEach((axis, idx) => {
+    const axisIdx = axisNames.indexOf(axis.name);
+    if (axisIdx > -1) {
+      axesTCZYX[axisIdx] = idx;
+    } else {
+      throw new VolumeLoadError(`Unrecognized axis in zarr: ${axis.name}`, {
+        type: VolumeLoadErrorType.INVALID_METADATA
+      });
+    }
+  });
+
+  // it is possible that Z might not exist but we require X and Y at least.
+  const noXAxis = axesTCZYX[4] === -1;
+  if (noXAxis || axesTCZYX[3] === -1) {
+    throw new VolumeLoadError(`Did not find ${noXAxis ? "an X" : "a Y"} axis in zarr`, {
+      type: VolumeLoadErrorType.INVALID_METADATA
+    });
+  }
+  return axesTCZYX;
+}
+
+/** Reorder an array of values [T, C, Z, Y, X] to the given dimension order */
+export function orderByDimension(valsTCZYX, orderTCZYX) {
+  const specLen = getDimensionCount(orderTCZYX);
+  const result = Array(specLen);
+  orderTCZYX.forEach((val, idx) => {
+    if (val >= 0) {
+      if (val >= specLen) {
+        throw new VolumeLoadError(`Unexpected axis index in zarr: ${val}`, {
+          type: VolumeLoadErrorType.INVALID_METADATA
+        });
+      }
+      result[val] = valsTCZYX[idx];
+    }
+  });
+  return result;
+}
+
+/** Reorder an array of values in the given dimension order to [T, C, Z, Y, X] */
+export function orderByTCZYX(valsDimension, orderTCZYX, defaultValue) {
+  const result = [defaultValue, defaultValue, defaultValue, defaultValue, defaultValue];
+  orderTCZYX.forEach((val, idx) => {
+    if (val >= 0) {
+      if (val >= valsDimension.length) {
+        throw new VolumeLoadError(`Unexpected axis index in zarr: ${val}`, {
+          type: VolumeLoadErrorType.INVALID_METADATA
+        });
+      }
+      result[idx] = valsDimension[val];
+    }
+  });
+  return result;
+}
+
+/** Select the scale transform from an OME metadata object with coordinate transforms, and return it in TCZYX order */
+export function getScale(dataset, orderTCZYX) {
+  const transforms = dataset.coordinateTransformations;
+  if (transforms === undefined) {
+    console.warn("WARNING: OMEZarrLoader: no coordinate transformations for scale level.");
+    return [1, 1, 1, 1, 1];
+  }
+
+  // this assumes we'll never encounter the "path" variant
+  const isScaleTransform = t => t.type === "scale";
+
+  // there can be any number of coordinateTransformations
+  // but there must be only one of type "scale".
+  const scaleTransform = transforms.find(isScaleTransform);
+  if (!scaleTransform) {
+    console.warn(`WARNING: OMEZarrLoader: no coordinate transformation of type "scale" for scale level.`);
+    return [1, 1, 1, 1, 1];
+  }
+  const scale = scaleTransform.scale.slice();
+  return orderByTCZYX(scale, orderTCZYX, 1);
+}
+
+/**
+ * Defines a partial order of zarr arrays based on their size. Specifically:
+ * - If array size x, y, z are all equal, the arrays are equal
+ * - otherwise, if all xyz of `a` are less than or equal to those of `b`, `a` is less than `b` (and vice versa)
+ * - if some xyz is less and some is greater, the arrays are uncomparable
+ */
+function compareZarrArraySize(aArr, aTCZYX, bArr, bTCZYX) {
+  const aZ = aTCZYX[2] > -1 ? aArr.shape[aTCZYX[2]] : 1;
+  const bZ = bTCZYX[2] > -1 ? bArr.shape[bTCZYX[2]] : 1;
+  const diffZ = aZ - bZ;
+  const diffY = aArr.shape[aTCZYX[3]] - bArr.shape[bTCZYX[3]];
+  const diffX = aArr.shape[aTCZYX[4]] - bArr.shape[bTCZYX[4]];
+  if (diffZ === 0 && diffY === 0 && diffX === 0) {
+    return 0;
+  } else if (diffZ <= 0 && diffY <= 0 && diffX <= 0) {
+    return -1;
+  } else if (diffZ >= 0 && diffY >= 0 && diffX >= 0) {
+    return 1;
+  } else {
+    return undefined;
+  }
+}
+const EPSILON = 0.00001;
+const aboutEquals = (a, b) => Math.abs(a - b) < EPSILON;
+function scaleTransformsAreEqual(aSrc, aLevel, bSrc, bLevel) {
+  const aScale = getScale(aSrc.multiscaleMetadata.datasets[aLevel], aSrc.axesTCZYX);
+  const bScale = getScale(bSrc.multiscaleMetadata.datasets[bLevel], bSrc.axesTCZYX);
+  return aboutEquals(aScale[2], bScale[2]) && aboutEquals(aScale[3], bScale[3]) && aboutEquals(aScale[4], bScale[4]);
+}
+
+/**
+ * Ensures that all scale levels in `sources` are matched up by size. More precisely: enforces that, for any scale
+ * level `i`, the size of zarr array `s[i]` is equal for every source `s`. We accomplish this by removing any arrays
+ * (and their associated OME dataset metadata) which don't match up in all sources.
+ *
+ * Note that this function modifies the input `sources` array rather than returning a new value.
+ *
+ * Assumes all sources have scale levels ordered by size from largest to smallest. (This should always be true for
+ * compliant OME-Zarr data.)
+ */
+export function matchSourceScaleLevels(sources) {
+  if (sources.length < 2) {
+    return;
+  }
+
+  // Save matching scale levels and metadata here
+  const matchedLevels = Array.from({
+    length: sources.length
+  }, () => []);
+  const matchedMetas = Array.from({
+    length: sources.length
+  }, () => []);
+
+  // Start as many index counters as we have sources
+  const scaleIndexes = new Array(sources.length).fill(0);
+  while (scaleIndexes.every((val, idx) => val < sources[idx].scaleLevels.length)) {
+    // First pass: find the smallest source / determine if all sources are equal
+    let allEqual = true;
+    let smallestIdx = 0;
+    let smallestSrc = sources[0];
+    let smallestArr = smallestSrc.scaleLevels[scaleIndexes[0]];
+    for (let currentIdx = 1; currentIdx < sources.length; currentIdx++) {
+      const currentSrc = sources[currentIdx];
+      const currentArr = currentSrc.scaleLevels[scaleIndexes[currentIdx]];
+      const ordering = compareZarrArraySize(smallestArr, smallestSrc.axesTCZYX, currentArr, currentSrc.axesTCZYX);
+      if (!ordering) {
+        // Arrays are equal, or they are uncomparable
+        if (ordering === undefined) {
+          throw new VolumeLoadError("Incompatible zarr arrays: pixel dimensions are mismatched", {
+            type: VolumeLoadErrorType.INVALID_MULTI_SOURCE_ZARR
+          });
+        }
+
+        // Now we know the arrays are equal, but they may still be invalid to match up because...
+        // ...they have different scale transformations
+        if (!scaleTransformsAreEqual(smallestSrc, scaleIndexes[smallestIdx], currentSrc, scaleIndexes[currentIdx])) {
+          // today we are going to treat this as a warning.
+          // For our implementation it is enough that the xyz pixel ranges are the same.
+          // Ideally scale*arraysize=physical size is really the quantity that should be equal, for combining two volume data sets as channels.
+          console.warn("Incompatible zarr arrays: scale levels of equal size have different scale transformations");
+        }
+
+        // ...they have different numbers of timesteps
+        const largestT = smallestSrc.axesTCZYX[0] > -1 ? smallestArr.shape[smallestSrc.axesTCZYX[0]] : 1;
+        const currentT = currentSrc.axesTCZYX[0] > -1 ? currentArr.shape[currentSrc.axesTCZYX[0]] : 1;
+        if (largestT !== currentT) {
+          // we also treat this as a warning.
+          // In OmeZarrLoader we will take the minimum T size of all sources
+          console.warn(`Incompatible zarr arrays: different numbers of timesteps: ${largestT} vs ${currentT}`);
+        }
+      } else {
+        allEqual = false;
+        if (ordering > 0) {
+          smallestIdx = currentIdx;
+          smallestSrc = currentSrc;
+          smallestArr = currentArr;
+        }
+      }
+    }
+    if (allEqual) {
+      // We've found a matching set of scale levels! Save it and increment all indexes
+      for (let i = 0; i < scaleIndexes.length; i++) {
+        const currentSrc = sources[i];
+        const matchedScaleLevel = scaleIndexes[i];
+        matchedLevels[i].push(currentSrc.scaleLevels[matchedScaleLevel]);
+        matchedMetas[i].push(currentSrc.multiscaleMetadata.datasets[matchedScaleLevel]);
+        scaleIndexes[i] += 1;
+      }
+    } else {
+      // Increment the indexes of the sources which are larger than the smallest
+      for (const [idx, srcIdx] of scaleIndexes.entries()) {
+        const currentSrc = sources[idx];
+        const currentArr = currentSrc.scaleLevels[srcIdx];
+        const ordering = compareZarrArraySize(smallestArr, smallestSrc.axesTCZYX, currentArr, currentSrc.axesTCZYX);
+        if (ordering !== 0) {
+          scaleIndexes[idx] += 1;
+        }
+      }
+    }
+  }
+  if (sources[0].scaleLevels.length === 0) {
+    throw new VolumeLoadError("Incompatible zarr arrays: no sets of scale levels found that matched in all sources", {
+      type: VolumeLoadErrorType.INVALID_MULTI_SOURCE_ZARR
+    });
+  }
+  for (let i = 0; i < sources.length; i++) {
+    sources[i].scaleLevels = matchedLevels[i];
+    sources[i].multiscaleMetadata.datasets = matchedMetas[i];
+  }
+}

package/es/loaders/zarr_utils/validation.js

@@ -0,0 +1,49 @@
+import { VolumeLoadError, VolumeLoadErrorType } from "../VolumeLoadError.js";
+function isObjectWithProp(obj, prop) {
+  return typeof obj === "object" && obj !== null && prop in obj;
+}
+function assertMetadataHasProp(obj, prop, name = "zarr") {
+  if (!isObjectWithProp(obj, prop)) {
+    throw new VolumeLoadError(`${name} metadata is missing required entry "${prop}"`, {
+      type: VolumeLoadErrorType.INVALID_METADATA
+    });
+  }
+}
+function assertPropIsArray(obj, prop, name = "zarr") {
+  if (!Array.isArray(obj[prop])) {
+    throw new VolumeLoadError(`${name} metadata entry "${prop}" is not an array`, {
+      type: VolumeLoadErrorType.INVALID_METADATA
+    });
+  }
+}
+
+/**
+ * Validates that the `OMEZarrMetadata` record `data` has the minimal amount of data required to open a volume. Since
+ * we only ever open one multiscale, we only validate the multiscale metadata record at index `multiscaleIdx` here.
+ * `name` is used in error messages to identify the source of the metadata.
+ */
+export function validateOMEZarrMetadata(data, multiscaleIdx = 0, name = "zarr") {
+  // data is an object with a key "multiscales", which is an array
+  assertMetadataHasProp(data, "multiscales", name);
+  assertPropIsArray(data, "multiscales", name);
+
+  // check that a multiscale metadata entry exists at `multiscaleIdx`
+  const multiscaleMeta = data.multiscales[multiscaleIdx];
+  if (!multiscaleMeta) {
+    throw new VolumeLoadError(`${name} metadata does not have requested multiscale level ${multiscaleIdx}`, {
+      type: VolumeLoadErrorType.INVALID_METADATA
+    });
+  }
+  const multiscaleMetaName = isObjectWithProp(multiscaleMeta, "name") ? ` ("${multiscaleMeta.name})` : "";
+  const multiscaleName = `${name} multiscale ${multiscaleIdx}${multiscaleMetaName}`;
+
+  // multiscale has a key "axes", which is an array. Each axis has a "name".
+  assertMetadataHasProp(multiscaleMeta, "axes", multiscaleName);
+  assertPropIsArray(multiscaleMeta, "axes", multiscaleName);
+  multiscaleMeta.axes.forEach((axis, i) => assertMetadataHasProp(axis, "name", `${multiscaleName} axis ${i}`));
+
+  // multiscale has a key "datasets", which is an array. Each dataset has a "path".
+  assertMetadataHasProp(multiscaleMeta, "datasets", name);
+  assertPropIsArray(multiscaleMeta, "datasets", name);
+  multiscaleMeta.datasets.forEach((data, i) => assertMetadataHasProp(data, "path", `${multiscaleName} dataset ${i}`));
+}

package/es/test/ChunkPrefetchIterator.test.js

@@ -0,0 +1,208 @@
+import { expect } from "chai";
+import ChunkPrefetchIterator from "../loaders/zarr_utils/ChunkPrefetchIterator";
+import { PrefetchDirection } from "../loaders/zarr_utils/types";
+const EXPECTED_3X3X3X3 = [[0, 0, 1, 1, 1],
+// T-
+[2, 0, 1, 1, 1],
+// T+
+[1, 0, 0, 1, 1],
+// Z-
+[1, 0, 2, 1, 1],
+// Z+
+[1, 0, 1, 0, 1],
+// Y-
+[1, 0, 1, 2, 1],
+// Y+
+[1, 0, 1, 1, 0],
+// X-
+[1, 0, 1, 1, 2] // X+
+];
+
+// move from the middle of a 3x3x3x3 cube to the middle of a 5x5x5x5 cube
+const EXPECTED_5X5X5X5_1 = EXPECTED_3X3X3X3.map(([t, c, z, y, x]) => [t + 1, c, z + 1, y + 1, x + 1]);
+// offset = 2!
+const EXPECTED_5X5X5X5_2 = [[0, 0, 2, 2, 2],
+// T--
+[4, 0, 2, 2, 2],
+// T++
+[2, 0, 0, 2, 2],
+// Z--
+[2, 0, 4, 2, 2],
+// Z++
+[2, 0, 2, 0, 2],
+// Y--
+[2, 0, 2, 4, 2],
+// Y++
+[2, 0, 2, 2, 0],
+// X--
+[2, 0, 2, 2, 4] // X++
+];
+function validate(iter, expected) {
+  expect([...iter]).to.deep.equal(expected);
+}
+describe("ChunkPrefetchIterator", () => {
+  it("iterates outward in TZYX order, negative then positive", () => {
+    // 3x3x3x3, with one chunk in the center
+    const iterator = new ChunkPrefetchIterator([[1, 0, 1, 1, 1]], [1, 1, 1, 1], [[3, 1, 3, 3, 3]]);
+    validate(iterator, EXPECTED_3X3X3X3);
+  });
+  it("finds the borders of a set of multiple chunks and iterates outward from them", () => {
+    // 4x4x4, with a 2x2x2 set of chunks in the center
+    const fetchedChunks = [[1, 0, 1, 1, 1], [1, 0, 1, 1, 2], [1, 0, 1, 2, 1], [1, 0, 1, 2, 2], [1, 0, 2, 1, 1], [1, 0, 2, 1, 2], [1, 0, 2, 2, 1], [1, 0, 2, 2, 2]];
+    const iterator = new ChunkPrefetchIterator(fetchedChunks, [1, 1, 1, 1], [[3, 1, 4, 4, 4]]);
+    const expected = [...fetchedChunks.map(([_t, c, z, y, x]) => [0, c, z, y, x]),
+    // T-
+    ...fetchedChunks.map(([_t, c, z, y, x]) => [2, c, z, y, x]),
+    // T+
+    ...fetchedChunks.filter(([_t, _c, z, _y, _x]) => z === 1).map(([t, c, _z, y, x]) => [t, c, 0, y, x]),
+    // Z-
+    ...fetchedChunks.filter(([_t, _c, z, _y, _x]) => z === 2).map(([t, c, _z, y, x]) => [t, c, 3, y, x]),
+    // Z+
+    ...fetchedChunks.filter(([_t, _c, _z, y, _x]) => y === 1).map(([t, c, z, _y, x]) => [t, c, z, 0, x]),
+    // Y-
+    ...fetchedChunks.filter(([_t, _c, _z, y, _x]) => y === 2).map(([t, c, z, _y, x]) => [t, c, z, 3, x]),
+    // Y+
+    ...fetchedChunks.filter(([_t, _c, _z, _y, x]) => x === 1).map(([t, c, z, y, _x]) => [t, c, z, y, 0]),
+    // X-
+    ...fetchedChunks.filter(([_t, _c, _z, _y, x]) => x === 2).map(([t, c, z, y, _x]) => [t, c, z, y, 3]) // X+
+    ];
+    validate(iterator, expected);
+  });
+  it("iterates through the same offset in all dimensions before increasing the offset", () => {
+    // 5x5x5, with one chunk in the center
+    const iterator = new ChunkPrefetchIterator([[2, 0, 2, 2, 2]], [2, 2, 2, 2], [[5, 1, 5, 5, 5]]);
+    const expected = [
+    // offset = 1
+    ...EXPECTED_5X5X5X5_1,
+    // offset = 2!
+    ...EXPECTED_5X5X5X5_2];
+    validate(iterator, expected);
+  });
+  it("stops at the max offset in each dimension", () => {
+    // 5x5x5, with one chunk in the center
+    const iterator = new ChunkPrefetchIterator([[2, 0, 2, 2, 2]], [1, 1, 1, 1], [[5, 1, 5, 5, 5]]);
+    validate(iterator, EXPECTED_5X5X5X5_1); // never reaches offset = 2, as it does above
+  });
+  it("stops at the borders of the zarr", () => {
+    // 3x3x3x3, with one chunk in the center
+    const iterator = new ChunkPrefetchIterator([[1, 0, 1, 1, 1]], [2, 2, 2, 2], [[3, 1, 3, 3, 3]]);
+    validate(iterator, EXPECTED_3X3X3X3);
+  });
+  it("does not iterate in dimensions which are entirely covered by the fetched set", () => {
+    // 3x3x3x3, with a 1x1x3x3 slice covering all of x and y
+    const fetchedChunks = [[1, 0, 1, 0, 0],
+    // 0, 0
+    [1, 0, 1, 0, 1],
+    // 0, 1
+    [1, 0, 1, 0, 2],
+    // 0, 2
+    [1, 0, 1, 1, 0],
+    // 1, 0
+    [1, 0, 1, 1, 1],
+    // 1, 1
+    [1, 0, 1, 1, 2],
+    // 1, 2
+    [1, 0, 1, 2, 0],
+    // 2, 0
+    [1, 0, 1, 2, 1],
+    // 2, 1
+    [1, 0, 1, 2, 2] // 2, 2
+    ];
+    const iterator = new ChunkPrefetchIterator(fetchedChunks, [1, 1, 1, 1], [[3, 1, 3, 3, 3]]);
+    const expected = [...fetchedChunks.map(([_t, c, z, y, x]) => [0, c, z, y, x]),
+    // T-
+    ...fetchedChunks.map(([_t, c, z, y, x]) => [2, c, z, y, x]),
+    // T+
+    ...fetchedChunks.map(([t, c, _z, y, x]) => [t, c, 0, y, x]),
+    // Z-
+    ...fetchedChunks.map(([t, c, _z, y, x]) => [t, c, 2, y, x]) // Z+
+    // skips x and y
+    ];
+    validate(iterator, expected);
+  });
+  it("does not iterate in dimensions where the max offset is 0", () => {
+    // 3x3x3x3, with one chunk in the center
+    const iterator = new ChunkPrefetchIterator([[1, 0, 1, 1, 1]], [1, 0, 1, 0], [[3, 1, 3, 3, 3]]);
+    const expected = [[0, 0, 1, 1, 1],
+    // T-
+    [2, 0, 1, 1, 1],
+    // T+
+    // skips z
+    [1, 0, 1, 0, 1],
+    // Y-
+    [1, 0, 1, 2, 1] // Y+
+    // skips x
+    ];
+    validate(iterator, expected);
+  });
+  it("yields chunks in all prioritized directions first", () => {
+    // 5x5x5, with one chunk in the center
+    const iterator = new ChunkPrefetchIterator([[2, 0, 2, 2, 2]], [2, 2, 2, 2], [[5, 1, 5, 5, 5]], [PrefetchDirection.T_PLUS, PrefetchDirection.Y_MINUS]);
+    const expected = [[3, 0, 2, 2, 2],
+    // T+
+    [2, 0, 2, 1, 2],
+    // Y-
+    [4, 0, 2, 2, 2],
+    // T++
+    [2, 0, 2, 0, 2],
+    // Y--
+    ...EXPECTED_5X5X5X5_1.filter(([t, _c, _z, y, _x]) => t <= 2 && y >= 2), ...EXPECTED_5X5X5X5_2.filter(([t, _c, _z, y, _x]) => t <= 2 && y >= 2)];
+    validate(iterator, expected);
+  });
+  it("continues iterating in other dimensions when some reach their limits", () => {
+    // final boss: 4x4x6 volume with off-center fetched set
+    // t has a max offset of 2, but is already at its maximum of 2 and never iterates in positive direction
+    // z has a max offset of 2, but stops early in negative direction at 0
+    // y has a max offset of 2, but is already covered in the negative direction by chunks in the fetched set
+    // x has a max offset of 1, which stops iteration before it gets to either edge
+    const fetchedChunks = [[2, 0, 1, 0, 2], [2, 0, 1, 0, 3], [2, 0, 1, 1, 2], [2, 0, 1, 1, 3]];
+    const iterator = new ChunkPrefetchIterator(fetchedChunks, [2, 2, 2, 1], [[3, 1, 4, 4, 6]]);
+
+    // prettier-ignore
+    const expected = [...fetchedChunks.map(([_t, c, z, y, x]) => [1, c, z, y, x]),
+    // T-
+    // skip t+: already at max t
+    ...fetchedChunks.map(([t, c, _z, y, x]) => [t, c, 0, y, x]),
+    // Z-
+    ...fetchedChunks.map(([t, c, _z, y, x]) => [t, c, 2, y, x]),
+    // Z+
+    // skip y-: already covered by fetched chunks
+    [2, 0, 1, 2, 2], [2, 0, 1, 2, 3],
+    // Y+
+    [2, 0, 1, 0, 1], [2, 0, 1, 1, 1],
+    // X-
+    [2, 0, 1, 0, 4], [2, 0, 1, 1, 4],
+    // X+
+    ...fetchedChunks.map(([_t, c, z, y, x]) => [0, c, z, y, x]),
+    // T--
+    // skip t++: still at max t
+    // skip z--: already reached z = 0 above
+    ...fetchedChunks.map(([t, c, _z, y, x]) => [t, c, 3, y, x]),
+    // Z++
+    // skip y-: still already covered by fetched chunks
+    [2, 0, 1, 3, 2], [2, 0, 1, 3, 3] // Y+
+    // skip x: already at max offset in x
+    ];
+    validate(iterator, expected);
+  });
+  it("correctly handles sources with differing chunk dimensions", () => {
+    const allChannels = (x, y, ch = [0, 1, 2, 3]) => ch.map(c => [0, c, 0, y, x]);
+    const iterator = new ChunkPrefetchIterator(allChannels(1, 2), [0, 0, 2, 2], [[0, 1, 0, 4, 3], [0, 2, 0, 5, 2], [0, 1, 0, 3, 4]]);
+    const expected = [...allChannels(1, 1),
+    // Y-
+    ...allChannels(1, 3, [0, 1, 2]),
+    // Y+: channel 3 is maxed out
+    ...allChannels(0, 2),
+    // X-
+    ...allChannels(2, 2, [0, 3]),
+    // X+: channels 1 and 2 are maxed out
+    ...allChannels(1, 0),
+    // Y--
+    ...allChannels(1, 4, [1, 2]),
+    // Y++: channels 0 and 3 are maxed out
+    // skip X--
+    [0, 3, 0, 2, 3] // X++: all channels but channel 3 are maxed out
+    ];
+    validate(iterator, expected);
+  });
+});