@aics/vole-core 3.12.4

package/es/loaders/TiffLoader.js

@@ -0,0 +1,219 @@
+import { fromUrl } from "geotiff";
+import { deserializeError } from "serialize-error";
+import { ThreadableVolumeLoader, LoadSpec } from "./IVolumeLoader.js";
+import { computePackedAtlasDims, MAX_ATLAS_EDGE } from "./VolumeLoaderUtils.js";
+import { VolumeLoadError, VolumeLoadErrorType, wrapVolumeLoadError } from "./VolumeLoadError.js";
+import { CImageInfo } from "../ImageInfo.js";
+function prepareXML(xml) {
+  // trim trailing unicode zeros?
+  // eslint-disable-next-line no-control-regex
+  const expr = /[\u0000]$/g;
+  return xml.trim().replace(expr, "").trim();
+}
+function getOME(xml) {
+  const parser = new DOMParser();
+  try {
+    const xmlDoc = parser.parseFromString(xml, "text/xml");
+    return xmlDoc.getElementsByTagName("OME")[0];
+  } catch (e) {
+    throw new VolumeLoadError("Could not find OME metadata in TIFF file", {
+      type: VolumeLoadErrorType.INVALID_METADATA,
+      cause: e
+    });
+  }
+}
+class OMEDims {
+  sizex = 0;
+  sizey = 0;
+  sizez = 1;
+  sizec = 1;
+  sizet = 1;
+  unit = "";
+  pixeltype = "";
+  dimensionorder = "";
+  pixelsizex = 1;
+  pixelsizey = 1;
+  pixelsizez = 1;
+  channelnames = [];
+}
+function getDtype(omepixeltype) {
+  const mapping = {
+    uint8: "uint8",
+    uint16: "uint16",
+    uint32: "uint32",
+    int8: "int8",
+    int16: "int16",
+    int32: "int32",
+    float: "float32"
+  };
+  const dtype = mapping[omepixeltype];
+  if (dtype === undefined) {
+    console.warn(`Unsupported OME pixel type ${omepixeltype}; defaulting to uint8`);
+    return "uint8";
+  }
+  return dtype;
+}
+function getAttributeOrError(el, attr) {
+  const val = el.getAttribute(attr);
+  if (val === null) {
+    throw new VolumeLoadError(`Missing attribute ${attr} in OME-TIFF metadata`, {
+      type: VolumeLoadErrorType.INVALID_METADATA
+    });
+  }
+  return val;
+}
+function getOMEDims(imageEl) {
+  const dims = new OMEDims();
+  const pixelsEl = imageEl.getElementsByTagName("Pixels")[0];
+  dims.sizex = Number(getAttributeOrError(pixelsEl, "SizeX"));
+  dims.sizey = Number(getAttributeOrError(pixelsEl, "SizeY"));
+  dims.sizez = Number(pixelsEl.getAttribute("SizeZ"));
+  dims.sizec = Number(pixelsEl.getAttribute("SizeC"));
+  dims.sizet = Number(pixelsEl.getAttribute("SizeT"));
+  dims.unit = pixelsEl.getAttribute("PhysicalSizeXUnit") || "";
+  dims.pixeltype = pixelsEl.getAttribute("Type") || "";
+  dims.dimensionorder = pixelsEl.getAttribute("DimensionOrder") || "XYZCT";
+  dims.pixelsizex = Number(pixelsEl.getAttribute("PhysicalSizeX"));
+  dims.pixelsizey = Number(pixelsEl.getAttribute("PhysicalSizeY"));
+  dims.pixelsizez = Number(pixelsEl.getAttribute("PhysicalSizeZ"));
+  const channelsEls = pixelsEl.getElementsByTagName("Channel");
+  for (let i = 0; i < channelsEls.length; ++i) {
+    const name = channelsEls[i].getAttribute("Name");
+    const id = channelsEls[i].getAttribute("ID");
+    dims.channelnames.push(name ? name : id ? id : "Channel" + i);
+  }
+  return dims;
+}
+const getBytesPerSample = type => type === "uint8" ? 1 : type === "uint16" ? 2 : 4;
+
+// Despite the class `TiffLoader` extends, this loader is not threadable, since geotiff internally uses features that
+// aren't available on workers. It uses its own specialized workers anyways.
+class TiffLoader extends ThreadableVolumeLoader {
+  constructor(url) {
+    super();
+    this.url = url;
+  }
+  async loadOmeDims() {
+    if (!this.dims) {
+      const tiff = await fromUrl(this.url, {
+        allowFullFile: true
+      }).catch(wrapVolumeLoadError(`Could not open TIFF file at ${this.url}`, VolumeLoadErrorType.NOT_FOUND));
+      // DO NOT DO THIS, ITS SLOW
+      // const imagecount = await tiff.getImageCount();
+      // read the FIRST image
+      const image = await tiff.getImage().catch(wrapVolumeLoadError("Failed to open TIFF image", VolumeLoadErrorType.NOT_FOUND));
+      const tiffimgdesc = prepareXML(image.getFileDirectory().ImageDescription);
+      const omeEl = getOME(tiffimgdesc);
+      const image0El = omeEl.getElementsByTagName("Image")[0];
+      this.dims = getOMEDims(image0El);
+    }
+    return this.dims;
+  }
+  async loadDims(_loadSpec) {
+    const dims = await this.loadOmeDims();
+    const atlasDims = computePackedAtlasDims(dims.sizez, dims.sizex, dims.sizey);
+    // fit tiles to max of 2048x2048?
+    const targetSize = MAX_ATLAS_EDGE;
+    const tilesizex = Math.floor(targetSize / atlasDims.x);
+    const tilesizey = Math.floor(targetSize / atlasDims.y);
+    const d = {
+      shape: [dims.sizet, dims.sizec, dims.sizez, tilesizey, tilesizex],
+      spacing: [1, 1, dims.pixelsizez, dims.pixelsizey * dims.sizey / tilesizey, dims.pixelsizex * dims.sizex / tilesizex],
+      spaceUnit: dims.unit ? dims.unit : "micron",
+      dataType: getDtype(dims.pixeltype),
+      timeUnit: "s"
+    };
+    return [d];
+  }
+  async createImageInfo(_loadSpec) {
+    const dims = await this.loadOmeDims();
+    // compare with sizex, sizey
+    //const width = image.getWidth();
+    //const height = image.getHeight();
+
+    // TODO allow user setting of this downsampling info?
+    // TODO allow ROI selection: range of x,y,z,c for a given t
+    const atlasDims = computePackedAtlasDims(dims.sizez, dims.sizex, dims.sizey);
+    // fit tiles to max of 2048x2048?
+    const targetSize = MAX_ATLAS_EDGE;
+    const tilesizex = Math.floor(targetSize / atlasDims.x);
+    const tilesizey = Math.floor(targetSize / atlasDims.y);
+
+    // load tiff and check metadata
+
+    const imgdata = {
+      name: "TEST",
+      atlasTileDims: [atlasDims.x, atlasDims.y],
+      subregionSize: [tilesizex, tilesizey, dims.sizez],
+      subregionOffset: [0, 0, 0],
+      combinedNumChannels: dims.sizec,
+      channelNames: dims.channelnames,
+      multiscaleLevel: 0,
+      multiscaleLevelDims: [{
+        shape: [dims.sizet, dims.sizec, dims.sizez, tilesizey, tilesizex],
+        spacing: [1, 1, dims.pixelsizez, dims.pixelsizey * dims.sizey / tilesizey, dims.pixelsizex * dims.sizex / tilesizex],
+        spaceUnit: dims.unit || "",
+        timeUnit: "",
+        dataType: getDtype(dims.pixeltype)
+      }],
+      transform: {
+        translation: [0, 0, 0],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1]
+      }
+    };
+
+    // This loader uses no fields from `LoadSpec`. Initialize volume with defaults.
+    return {
+      imageInfo: imgdata,
+      loadSpec: new LoadSpec()
+    };
+  }
+  async loadRawChannelData(imageInfo, _loadSpec, _onUpdateMetadata, onData) {
+    const dims = await this.loadOmeDims();
+
+    // get some size info.
+    const cimageinfo = new CImageInfo(imageInfo);
+    const volumeSize = cimageinfo.volumeSize;
+    const channelProms = [];
+    // do each channel on a worker?
+    for (let channel = 0; channel < imageInfo.combinedNumChannels; ++channel) {
+      const thisChannelProm = new Promise((resolve, reject) => {
+        const params = {
+          channel: channel,
+          // these are target xy sizes for the in-memory volume data
+          // they may or may not be the same size as original xy sizes
+          tilesizex: volumeSize.x,
+          tilesizey: volumeSize.y,
+          sizec: imageInfo.combinedNumChannels,
+          sizez: volumeSize.z,
+          dimensionOrder: dims.dimensionorder,
+          bytesPerSample: getBytesPerSample(dims.pixeltype),
+          url: this.url
+        };
+        const worker = new Worker(new URL("../workers/FetchTiffWorker", import.meta.url));
+        worker.onmessage = e => {
+          if (e.data.isError) {
+            reject(deserializeError(e.data.error));
+            return;
+          }
+          const {
+            data,
+            dtype,
+            channel,
+            range
+          } = e.data;
+          onData([channel], [dtype], [data], [range]);
+          worker.terminate();
+          resolve();
+        };
+        worker.postMessage(params);
+      });
+      channelProms.push(thisChannelProm);
+    }
+
+    // waiting for all channels to load allows errors to propagate to the caller via this promise
+    await Promise.all(channelProms);
+  }
+}
+export { TiffLoader };

package/es/loaders/VolumeLoadError.js

@@ -0,0 +1,44 @@
+import { errorConstructors } from "serialize-error";
+import { NodeNotFoundError, KeyError } from "@zarrita/core";
+// geotiff doesn't export its error types...
+
+/** Groups possible load errors into a few broad categories which we can give similar guidance to the user about. */
+export let VolumeLoadErrorType = /*#__PURE__*/function (VolumeLoadErrorType) {
+  VolumeLoadErrorType["UNKNOWN"] = "unknown";
+  VolumeLoadErrorType["NOT_FOUND"] = "not_found";
+  VolumeLoadErrorType["TOO_LARGE"] = "too_large";
+  VolumeLoadErrorType["LOAD_DATA_FAILED"] = "load_data_failed";
+  VolumeLoadErrorType["INVALID_METADATA"] = "invalid_metadata";
+  VolumeLoadErrorType["INVALID_MULTI_SOURCE_ZARR"] = "invalid_multi_source_zarr";
+  return VolumeLoadErrorType;
+}({});
+export class VolumeLoadError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "VolumeLoadError";
+    this.type = options?.type ?? VolumeLoadErrorType.UNKNOWN;
+  }
+}
+
+// serialize-error only ever calls an error constructor with zero arguments. The required `ErrorConstructor`
+// type is a bit too restrictive - as long as the constructor can be called with no arguments it's fine.
+errorConstructors.set("NodeNotFoundError", NodeNotFoundError);
+errorConstructors.set("KeyError", KeyError);
+errorConstructors.set("VolumeLoadError", VolumeLoadError);
+
+/** Curried function to re-throw an error wrapped in a `VolumeLoadError` with the given `message` and `type`. */
+export function wrapVolumeLoadError(message = "Unknown error occurred while loading volume data", type = VolumeLoadErrorType.UNKNOWN, ignore) {
+  return e => {
+    if (ignore !== undefined && e === ignore) {
+      return e;
+    }
+    if (e instanceof VolumeLoadError) {
+      throw e;
+    }
+    console.log(`Error loading volume data: ${e}`);
+    throw new VolumeLoadError(message, {
+      type,
+      cause: e
+    });
+  };
+}

package/es/loaders/VolumeLoaderUtils.js

@@ -0,0 +1,221 @@
+import { Box3, Vector2, Vector3 } from "three";
+import { CImageInfo } from "../ImageInfo.js";
+export const MAX_ATLAS_EDGE = 4096;
+
+// Map from units to their symbols
+const UNIT_SYMBOLS = {
+  angstrom: "Å",
+  day: "d",
+  foot: "ft",
+  hour: "h",
+  inch: "in",
+  meter: "m",
+  micron: "μm",
+  mile: "mi",
+  minute: "min",
+  parsec: "pc",
+  second: "s",
+  yard: "yd"
+};
+
+// Units which may take SI prefixes (e.g. micro-, tera-)
+const SI_UNITS = ["meter", "second"];
+
+// SI prefixes which abbreviate in nonstandard ways
+const SI_PREFIX_ABBVS = {
+  micro: "μ",
+  deca: "da"
+};
+
+/** Converts a full spatial or temporal unit name supported by OME-Zarr to its unit symbol */
+// (see https://ngff.openmicroscopy.org/latest/#axes-md)
+export function unitNameToSymbol(unitName) {
+  if (unitName === undefined) {
+    return null;
+  }
+  if (UNIT_SYMBOLS[unitName]) {
+    return UNIT_SYMBOLS[unitName];
+  }
+  const prefixedSIUnit = SI_UNITS.find(siUnit => unitName.endsWith(siUnit));
+  if (prefixedSIUnit) {
+    const prefix = unitName.substring(0, unitName.length - prefixedSIUnit.length);
+    if (SI_PREFIX_ABBVS[prefix]) {
+      // "special" SI prefix
+      return SI_PREFIX_ABBVS[prefix] + UNIT_SYMBOLS[prefixedSIUnit];
+    }
+
+    // almost all SI prefixes are abbreviated by first letter, capitalized if prefix ends with "a"
+    const capitalize = prefix.endsWith("a");
+    const prefixAbbr = capitalize ? prefix[0].toUpperCase() : prefix[0];
+    return prefixAbbr + UNIT_SYMBOLS[prefixedSIUnit];
+  }
+  return null;
+}
+
+// We want to find the most "square" packing of z tw by th tiles.
+// Compute number of rows and columns.
+export function computePackedAtlasDims(z, tw, th) {
+  let nextrows = 1;
+  let nextcols = z;
+  let ratio = nextcols * tw / (nextrows * th);
+  let nrows = nextrows;
+  let ncols = nextcols;
+  while (ratio > 1) {
+    nrows = nextrows;
+    ncols = nextcols;
+    nextcols -= 1;
+    nextrows = Math.ceil(z / nextcols);
+    ratio = nextcols * tw / (nextrows * th);
+  }
+  return new Vector2(nrows, ncols);
+}
+function doesSpatialDimensionFitInAtlas(spatialDimZYX, maxAtlasEdge = MAX_ATLAS_EDGE) {
+  // Estimate atlas size
+  const x = spatialDimZYX[2];
+  const y = spatialDimZYX[1];
+  const z = spatialDimZYX[0];
+  const xtiles = Math.floor(maxAtlasEdge / x);
+  const ytiles = Math.floor(maxAtlasEdge / y);
+  return xtiles * ytiles >= z;
+}
+
+/** Picks the largest scale level that can fit into a texture atlas with edges no longer than `maxAtlasEdge`. */
+export function estimateLevelForAtlas(spatialDimsZYX, maxAtlasEdge = MAX_ATLAS_EDGE) {
+  if (spatialDimsZYX.length <= 1) {
+    return 0;
+  }
+  for (let i = 0; i < spatialDimsZYX.length; ++i) {
+    // estimate atlas size:
+    if (doesSpatialDimensionFitInAtlas(spatialDimsZYX[i], maxAtlasEdge)) {
+      return i;
+    }
+  }
+  return undefined;
+}
+const maxCeil = val => Math.max(Math.ceil(val), 1);
+const scaleDims = (size, [z, y, x]) => [maxCeil(z * size.z), maxCeil(y * size.y), maxCeil(x * size.x)];
+export function scaleDimsToSubregion(subregion, dims) {
+  const size = subregion.getSize(new Vector3());
+  return scaleDims(size, dims);
+}
+export function scaleMultipleDimsToSubregion(subregion, dims) {
+  const size = subregion.getSize(new Vector3());
+  return dims.map(dim => scaleDims(size, dim));
+}
+
+/**
+ * Picks the best scale level to load based on scale level dimensions and a `LoadSpec`. This calls
+ * `estimateLevelForAtlas`, then accounts for `LoadSpec`'s scale level picking properties:
+ * - `multiscaleLevel` imposes a minimum scale level (or *maximum* resolution level) to load
+ * - `maxAtlasEdge` sets the maximum size of the texture atlas that may be produced by a load
+ * - `scaleLevelBias` offsets the scale level index after the optimal level is picked based on `maxAtlasEdge`
+ *
+ *  This function assumes that `spatialDimsZYX` has already been appropriately scaled to match `loadSpec`'s `subregion`.
+ */
+export function pickLevelToLoadUnscaled(loadSpec, spatialDimsZYX) {
+  if (loadSpec.useExplicitLevel && loadSpec.multiscaleLevel !== undefined) {
+    // clamp to actual allowed level range
+    return Math.max(0, Math.min(spatialDimsZYX.length - 1, loadSpec.multiscaleLevel));
+  }
+  let levelToLoad = estimateLevelForAtlas(spatialDimsZYX, loadSpec.maxAtlasEdge);
+  // Check here for whether levelToLoad is within max atlas size?
+  if (levelToLoad !== undefined) {
+    levelToLoad = Math.max(levelToLoad + (loadSpec.scaleLevelBias ?? 0), loadSpec.multiscaleLevel ?? 0);
+    levelToLoad = Math.max(0, Math.min(spatialDimsZYX.length - 1, levelToLoad));
+    if (doesSpatialDimensionFitInAtlas(spatialDimsZYX[levelToLoad], loadSpec.maxAtlasEdge)) {
+      return levelToLoad;
+    }
+  }
+
+  // Level to load could not be loaded due to atlas size constraints.
+  if (levelToLoad === undefined) {
+    // No optimal level exists so choose the smallest level to report out
+    levelToLoad = spatialDimsZYX.length - 1;
+  }
+  const smallestDims = spatialDimsZYX[levelToLoad];
+  console.error(`Volume is too large; no multiscale level found that fits in preferred memory footprint. Selected level ${levelToLoad}  has dimensions `, smallestDims, `. Max atlas edge allowed is ${loadSpec.maxAtlasEdge}.`);
+  console.log("All available levels: ", spatialDimsZYX);
+  return levelToLoad;
+}
+
+/**
+ * Picks the best scale level to load based on scale level dimensions and a `LoadSpec`. This calls
+ * `estimateLevelForAtlas` and accounts for all properties of `LoadSpec` considered by
+ * `pickLevelToLoadUnscaled`, and additionally scales the dimensions of the scale levels to account for the
+ * `LoadSpec`'s `subregion` property.
+ */
+export function pickLevelToLoad(loadSpec, spatialDimsZYX) {
+  const scaledDims = scaleMultipleDimsToSubregion(loadSpec.subregion, spatialDimsZYX);
+  return pickLevelToLoadUnscaled(loadSpec, scaledDims);
+}
+
+/** Given the size of a volume in pixels, convert a `Box3` in the 0-1 range to pixels */
+export function convertSubregionToPixels(region, size) {
+  const min = region.min.clone().multiply(size).floor();
+  const max = region.max.clone().multiply(size).ceil();
+
+  // ensure it's always valid to specify the same number at both ends and get a single slice
+  if (min.x === max.x && min.x < size.x) {
+    max.x += 1;
+  }
+  if (min.y === max.y && min.y < size.y) {
+    max.y += 1;
+  }
+  if (min.z === max.z && min.z < size.z) {
+    max.z += 1;
+  }
+  return new Box3(min, max);
+}
+
+/**
+ * Return the subset of `container` specified by `region`, assuming that `region` contains fractional values (between 0
+ * and 1). i.e. if `container`'s range on the X axis is 0-4 and `region`'s is 0.25-0.5, the result will have range 1-2.
+ */
+export function composeSubregion(region, container) {
+  const size = container.getSize(new Vector3());
+  const min = region.min.clone().multiply(size).add(container.min);
+  const max = region.max.clone().multiply(size).add(container.min);
+  return new Box3(min, max);
+}
+function isEmpty(obj) {
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// currently everything needed can come from the imageInfo
+// but in the future each IVolumeLoader could have a completely separate implementation.
+export function buildDefaultMetadata(rawImageInfo) {
+  // wrap
+  const imageInfo = new CImageInfo(rawImageInfo);
+  const physicalSize = imageInfo.volumeSize.clone().multiply(imageInfo.physicalPixelSize);
+  const metadata = {};
+  metadata["Dimensions"] = {
+    ...imageInfo.subregionSize
+  };
+  metadata["Original dimensions"] = {
+    ...imageInfo.originalSize
+  };
+  metadata["Physical size"] = {
+    x: physicalSize.x + imageInfo.spatialUnit,
+    y: physicalSize.y + imageInfo.spatialUnit,
+    z: physicalSize.z + imageInfo.spatialUnit
+  };
+  metadata["Physical size per pixel"] = {
+    x: imageInfo.physicalPixelSize.x + imageInfo.spatialUnit,
+    y: imageInfo.physicalPixelSize.y + imageInfo.spatialUnit,
+    z: imageInfo.physicalPixelSize.z + imageInfo.spatialUnit
+  };
+  metadata["Multiresolution levels"] = rawImageInfo.multiscaleLevelDims;
+  // TODO decide???? combined or not?
+  metadata["Channels"] = rawImageInfo.combinedNumChannels; //imageInfo.numChannels;
+  metadata["Time series frames"] = imageInfo.times || 1;
+  // don't add User data if it's empty
+  if (rawImageInfo.userData && !isEmpty(rawImageInfo.userData)) {
+    metadata["User data"] = rawImageInfo.userData;
+  }
+  return metadata;
+}

package/es/loaders/index.js

@@ -0,0 +1,40 @@
+import { OMEZarrLoader } from "./OmeZarrLoader.js";
+import { JsonImageInfoLoader } from "./JsonImageInfoLoader.js";
+import { RawArrayLoader } from "./RawArrayLoader.js";
+import { TiffLoader } from "./TiffLoader.js";
+export { PrefetchDirection } from "./zarr_utils/types.js";
+export let VolumeFileFormat = /*#__PURE__*/function (VolumeFileFormat) {
+  VolumeFileFormat["ZARR"] = "zarr";
+  VolumeFileFormat["JSON"] = "json";
+  VolumeFileFormat["TIFF"] = "tiff";
+  VolumeFileFormat["DATA"] = "data";
+  return VolumeFileFormat;
+}({});
+
+// superset of all necessary loader options
+
+export function pathToFileType(path) {
+  if (path.endsWith(".json")) {
+    return VolumeFileFormat.JSON;
+  } else if (path.endsWith(".tif") || path.endsWith(".tiff")) {
+    return VolumeFileFormat.TIFF;
+  }
+  return VolumeFileFormat.ZARR;
+}
+export async function createVolumeLoader(path, options) {
+  const pathString = Array.isArray(path) ? path[0] : path;
+  const fileType = options?.fileType || pathToFileType(pathString);
+  switch (fileType) {
+    case VolumeFileFormat.ZARR:
+      return await OMEZarrLoader.createLoader(path, options?.scene, options?.cache, options?.queue, options?.fetchOptions);
+    case VolumeFileFormat.JSON:
+      return new JsonImageInfoLoader(path, options?.cache);
+    case VolumeFileFormat.TIFF:
+      return new TiffLoader(pathString);
+    case VolumeFileFormat.DATA:
+      if (!options?.rawArrayOptions) {
+        throw new Error("Must provide RawArrayOptions for RawArrayLoader");
+      }
+      return new RawArrayLoader(options?.rawArrayOptions.data, options?.rawArrayOptions.metadata);
+  }
+}

package/es/loaders/zarr_utils/ChunkPrefetchIterator.js

@@ -0,0 +1,143 @@
+const allEqual = arr => arr.every(v => v === arr[0]);
+const pushN = (arr, val, n) => {
+  for (let i = 0; i < n; i++) {
+    arr.push(val);
+  }
+};
+const directionToIndex = dir => {
+  const absDir = dir >> 1; // shave off sign bit to get index in TZYX
+  return absDir + Number(absDir !== 0); // convert TZYX -> TCZYX by skipping c (index 1)
+};
+function updateMinMax(val, minmax) {
+  if (val < minmax[0]) {
+    minmax[0] = val;
+  }
+  if (val > minmax[1]) {
+    minmax[1] = val;
+  }
+}
+
+/**
+ * Since the user is most likely to want nearby data (in space or time) first, we should prefetch those chunks first.
+ *
+ * Given a list of just-loaded chunks and some bounds, `ChunkPrefetchIterator` iterates evenly outwards in T/Z/Y/X.
+ */
+// NOTE: Assumes `chunks` form a rectangular prism! Will create gaps otherwise! (in practice they always should)
+export default class ChunkPrefetchIterator {
+  constructor(chunks, tzyxMaxPrefetchOffset, tczyxChunksPerSource, priorityDirections, onlyPriorityDirections = false) {
+    // Get min and max chunk coordinates for T/Z/Y/X
+    const extrema = [[Infinity, -Infinity], [Infinity, -Infinity], [Infinity, -Infinity], [Infinity, -Infinity]];
+    for (const chunk of chunks) {
+      updateMinMax(chunk[0], extrema[0]);
+      updateMinMax(chunk[2], extrema[1]);
+      updateMinMax(chunk[3], extrema[2]);
+      updateMinMax(chunk[4], extrema[3]);
+    }
+
+    // Create `PrefetchDirectionState`s for each direction
+    this.directionStates = [];
+    this.priorityDirectionStates = [];
+
+    // iterating like this: direction is the index in the flattened entries
+    // and corresponds to our +T, -T, +Z, -Z, +Y, -Y, +X, -X directions in order
+    // because extrema is in TZYX order.
+    for (const [direction, start] of extrema.flat().entries()) {
+      const dimension = direction >> 1; // shave off sign bit to get index in TZYX
+      const tczyxIndex = dimension + Number(dimension !== 0); // convert TZYX -> TCZYX by skipping c (index 1)
+      let end;
+      if (direction & 1) {
+        // Positive direction - end is either the max coordinate in the fetched set plus the max offset in this
+        // dimension, or the max chunk coordinate in this dimension, whichever comes first
+        const endsPerSource = tczyxChunksPerSource.map(chunkDims => {
+          return Math.min(start + tzyxMaxPrefetchOffset[dimension], chunkDims[tczyxIndex] - 1);
+        });
+
+        // Save some time: if all sources have the same end, we can just store that
+        if (allEqual(endsPerSource)) {
+          end = endsPerSource[0];
+        } else {
+          // Otherwise, expand our ends per source array to ends per channel
+          end = [];
+          for (const [i, sourceEnd] of endsPerSource.entries()) {
+            pushN(end, sourceEnd, tczyxChunksPerSource[i][1]);
+          }
+        }
+        // end = Math.min(start + tzyxMaxPrefetchOffset[dimension], tczyxChunksPerDimension[dimension] - 1);
+      } else {
+        // Negative direction - end is either the min coordinate in the fetched set minus the max offset in this
+        // dimension, or 0, whichever comes first
+        end = Math.max(start - tzyxMaxPrefetchOffset[dimension], 0);
+      }
+      const directionState = {
+        direction,
+        start,
+        end,
+        chunks: []
+      };
+      if (priorityDirections && priorityDirections.includes(direction)) {
+        this.priorityDirectionStates.push(directionState);
+      } else {
+        // we have an option setting that can let us ignore non-priority directions
+        if (!onlyPriorityDirections) {
+          this.directionStates.push(directionState);
+        }
+      }
+    }
+
+    // Fill each `PrefetchDirectionState` with chunks at the border of the fetched set
+    for (const chunk of chunks) {
+      for (const dir of this.directionStates) {
+        if (chunk[directionToIndex(dir.direction)] === dir.start) {
+          dir.chunks.push(chunk);
+        }
+      }
+      for (const dir of this.priorityDirectionStates) {
+        if (chunk[directionToIndex(dir.direction)] === dir.start) {
+          dir.chunks.push(chunk);
+        }
+      }
+    }
+  }
+  static *iterateDirections(directions) {
+    let offset = 1;
+    while (directions.length > 0) {
+      // Remove directions in which we have reached the end (or, if per-channel ends, the end for all channels)
+      directions = directions.filter(dir => {
+        const end = Array.isArray(dir.end) ? Math.max(...dir.end) : dir.end;
+        if (dir.direction & 1) {
+          return dir.start + offset <= end;
+        } else {
+          return dir.start - offset >= end;
+        }
+      });
+
+      // Yield chunks one chunk farther out in every remaining direction
+      for (const dir of directions) {
+        const offsetDir = offset * (dir.direction & 1 ? 1 : -1);
+        for (const chunk of dir.chunks) {
+          // Skip this chunk if this channel has a specific per-channel end and we've reached it
+          if (Array.isArray(dir.end) && chunk[directionToIndex(dir.direction)] + offsetDir > dir.end[chunk[1]]) {
+            continue;
+          }
+          const newChunk = chunk.slice();
+          newChunk[directionToIndex(dir.direction)] += offsetDir;
+          yield newChunk;
+        }
+      }
+      offset += 1;
+    }
+  }
+  *[Symbol.iterator]() {
+    // Yield all chunks in priority direction(s) first, if any
+    if (this.priorityDirectionStates.length > 0) {
+      for (const chunk of ChunkPrefetchIterator.iterateDirections(this.priorityDirectionStates)) {
+        yield chunk;
+      }
+    }
+
+    // Then yield all chunks in other directions
+    for (const chunk of ChunkPrefetchIterator.iterateDirections(this.directionStates)) {
+      yield chunk;
+    }
+  }
+}