@aics/vole-core 3.12.4

package/es/loaders/OmeZarrLoader.js

@@ -0,0 +1,495 @@
+import { Box3, Vector3 } from "three";
+import * as zarr from "@zarrita/core";
+import { get as zarrGet, slice } from "@zarrita/indexing";
+// Importing `FetchStore` from its home subpackage (@zarrita/storage) causes errors.
+// Getting it from the top-level package means we don't get its type. This is also a bug, but it's more acceptable.
+import { FetchStore } from "zarrita";
+import SubscribableRequestQueue from "../utils/SubscribableRequestQueue.js";
+import { ThreadableVolumeLoader } from "./IVolumeLoader.js";
+import { composeSubregion, computePackedAtlasDims, convertSubregionToPixels, pickLevelToLoad, unitNameToSymbol } from "./VolumeLoaderUtils.js";
+import ChunkPrefetchIterator from "./zarr_utils/ChunkPrefetchIterator.js";
+import WrappedStore from "./zarr_utils/WrappedStore.js";
+import { getDimensionCount, getScale, getSourceChannelNames, matchSourceScaleLevels, orderByDimension, orderByTCZYX, remapAxesToTCZYX } from "./zarr_utils/utils.js";
+import { VolumeLoadError, VolumeLoadErrorType, wrapVolumeLoadError } from "./VolumeLoadError.js";
+import { validateOMEZarrMetadata } from "./zarr_utils/validation.js";
+const CHUNK_REQUEST_CANCEL_REASON = "chunk request cancelled";
+
+// returns the converted data and the original min and max values
+function convertChannel(channelData, dtype) {
+  // get min and max
+  // TODO FIXME Histogram will also compute min and max!
+  let min = channelData[0];
+  let max = channelData[0];
+  for (let i = 0; i < channelData.length; i++) {
+    const val = channelData[i];
+    if (val < min) {
+      min = val;
+    }
+    if (val > max) {
+      max = val;
+    }
+  }
+  if (dtype === "float64") {
+    // convert to float32
+    const f32 = new Float32Array(channelData.length);
+    for (let i = 0; i < channelData.length; i++) {
+      f32[i] = channelData[i];
+    }
+    dtype = "float32";
+    channelData = f32;
+  }
+  return {
+    data: channelData,
+    dtype,
+    min,
+    max
+  };
+}
+const DEFAULT_FETCH_OPTIONS = {
+  maxPrefetchDistance: [5, 5, 5, 5],
+  maxPrefetchChunks: 30
+};
+class OMEZarrLoader extends ThreadableVolumeLoader {
+  /** The ID of the subscriber responsible for "actual loads" (non-prefetch requests) */
+
+  /** The ID of the subscriber responsible for prefetches, so that requests can be cancelled and reissued */
+
+  // TODO: this property should definitely be owned by `Volume` if this loader is ever used by multiple volumes.
+  //   This may cause errors or incorrect results otherwise!
+
+  syncChannels = false;
+  constructor(
+  /**
+   * Array of records, each containing the objects and metadata we need to load from one source of multiscale zarr
+   * data. See documentation on `ZarrSource` for more.
+   */
+  sources, /** Handle to a `SubscribableRequestQueue` for smart concurrency management and request cancelling/reissuing. */
+  requestQueue, /** Options to configure (pre)fetching behavior. */
+  fetchOptions = DEFAULT_FETCH_OPTIONS, /** Direction(s) to prioritize when prefetching. Stored separate from `fetchOptions` since it may be mutated. */
+  priorityDirections = []) {
+    super();
+    this.sources = sources;
+    this.requestQueue = requestQueue;
+    this.fetchOptions = fetchOptions;
+    this.priorityDirections = priorityDirections;
+  }
+
+  /**
+   * Creates a new `OMEZarrLoader`.
+   *
+   * @param urls The URL(s) of the OME-Zarr data to load. If `urls` is an array, the loader will attempt to find scale
+   *  levels with exactly the same size in every source. If matching level(s) are available, the loader will produce a
+   *  volume containing all channels from every provided zarr in the order they appear in `urls`. If no matching sets
+   *  of scale levels are available, creation fails.
+   * @param scenes The scene(s) to load from each URL. If `urls` is an array, `scenes` may either be an array of values
+   *  corresponding to each URL, or a single value to apply to all URLs. Default 0.
+   * @param cache A cache to use for storing fetched data. If not provided, a new cache will be created.
+   * @param queue A queue to use for managing requests. If not provided, a new queue will be created.
+   * @param fetchOptions Options to configure (pre)fetching behavior.
+   */
+  static async createLoader(urls, scenes = 0, cache, queue, fetchOptions) {
+    // Setup queue and store, get basic metadata
+    if (!queue) {
+      queue = new SubscribableRequestQueue(fetchOptions?.concurrencyLimit, fetchOptions?.prefetchConcurrencyLimit);
+    }
+    const urlsArr = Array.isArray(urls) ? urls : [urls];
+    const scenesArr = Array.isArray(scenes) ? scenes : [scenes];
+
+    // Create one `ZarrSource` per URL
+    const sourceProms = urlsArr.map(async (url, i) => {
+      const store = new WrappedStore(new FetchStore(url), cache, queue);
+      const root = zarr.root(store);
+      const group = await zarr.open(root, {
+        kind: "group"
+      }).catch(wrapVolumeLoadError(`Failed to open OME-Zarr data at ${url}`, VolumeLoadErrorType.NOT_FOUND));
+
+      // Pick scene (multiscale)
+      let scene = scenesArr[Math.min(i, scenesArr.length - 1)];
+      if (scene > group.attrs.multiscales?.length) {
+        console.warn(`WARNING: OMEZarrLoader: scene ${scene} is invalid. Using scene 0.`);
+        scene = 0;
+      }
+      validateOMEZarrMetadata(group.attrs, scene, urlsArr.length > 1 ? `Zarr source ${i}` : "Zarr");
+      const {
+        multiscales,
+        omero
+      } = group.attrs;
+      const multiscaleMetadata = multiscales[scene];
+
+      // Open all scale levels of multiscale
+      const lvlProms = multiscaleMetadata.datasets.map(({
+        path
+      }) => zarr.open(root.resolve(path), {
+        kind: "array"
+      }).catch(wrapVolumeLoadError(`Failed to open scale level ${path} of OME-Zarr data at ${url}`, VolumeLoadErrorType.NOT_FOUND)));
+      const scaleLevels = await Promise.all(lvlProms);
+      const axesTCZYX = remapAxesToTCZYX(multiscaleMetadata.axes);
+      return {
+        scaleLevels,
+        multiscaleMetadata,
+        omeroMetadata: omero,
+        axesTCZYX,
+        channelOffset: 0
+      };
+    });
+    const sources = await Promise.all(sourceProms);
+
+    // Set `channelOffset`s so we can match channel indices to sources
+    let channelCount = 0;
+    for (const s of sources) {
+      s.channelOffset = channelCount;
+      channelCount += s.omeroMetadata?.channels.length ?? s.scaleLevels[0].shape[s.axesTCZYX[1]];
+    }
+    // Ensure the sizes of all sources' scale levels are matched up. See this function's docs for more.
+    matchSourceScaleLevels(sources);
+    // TODO: if `matchSourceScaleLevels` returned successfully, every one of these sources' `multiscaleMetadata` is the
+    // same in every field we care about, so we only ever use the first source's `multiscaleMetadata` after this point.
+    // Should we only store one `OMEMultiscale` record total, rather than one per source?
+    const priorityDirs = fetchOptions?.priorityDirections ? fetchOptions.priorityDirections.slice() : undefined;
+    return new OMEZarrLoader(sources, queue, fetchOptions, priorityDirs);
+  }
+  getUnitSymbols() {
+    const source = this.sources[0];
+    // Assume all spatial axes in all sources have the same units - we have no means of storing per-axis unit symbols
+    const xi = source.axesTCZYX[4];
+    const spaceUnitName = source.multiscaleMetadata.axes[xi].unit;
+    const spaceUnitSymbol = unitNameToSymbol(spaceUnitName) || spaceUnitName || "";
+    const ti = source.axesTCZYX[0];
+    const timeUnitName = ti > -1 ? source.multiscaleMetadata.axes[ti].unit : undefined;
+    const timeUnitSymbol = unitNameToSymbol(timeUnitName) || timeUnitName || "";
+    return [spaceUnitSymbol, timeUnitSymbol];
+  }
+  getLevelShapesZYX() {
+    const source = this.sources[0];
+    const [z, y, x] = source.axesTCZYX.slice(-3);
+    return source.scaleLevels.map(({
+      shape
+    }) => [z === -1 ? 1 : shape[z], shape[y], shape[x]]);
+  }
+  getScale(level) {
+    return getScale(this.sources[0].multiscaleMetadata.datasets[level], this.sources[0].axesTCZYX);
+  }
+  orderByDimension(valsTCZYX, sourceIdx = 0) {
+    return orderByDimension(valsTCZYX, this.sources[sourceIdx].axesTCZYX);
+  }
+  orderByTCZYX(valsDimension, defaultValue, sourceIdx = 0) {
+    return orderByTCZYX(valsDimension, this.sources[sourceIdx].axesTCZYX, defaultValue);
+  }
+
+  /**
+   * Converts a volume channel index to the index of its zarr source and its channel index within that zarr.
+   * e.g., if the loader has 2 sources, the first with 3 channels and the second with 2, then `matchChannelToSource(4)`
+   * returns `[1, 1]` (the second channel of the second source).
+   */
+  matchChannelToSource(absoluteChannelIndex) {
+    const lastSrcIdx = this.sources.length - 1;
+    const lastSrc = this.sources[lastSrcIdx];
+    const lastSrcNumChannels = lastSrc.scaleLevels[0].shape[lastSrc.axesTCZYX[1]];
+    const maxChannelIndex = lastSrc.channelOffset + lastSrcNumChannels;
+    if (absoluteChannelIndex > maxChannelIndex) {
+      throw new VolumeLoadError(`Volume channel index ${absoluteChannelIndex} out of range (${maxChannelIndex} channels available)`, {
+        type: VolumeLoadErrorType.INVALID_METADATA
+      });
+    }
+    const firstGreaterIdx = this.sources.findIndex(src => src.channelOffset > absoluteChannelIndex);
+    const sourceIndex = firstGreaterIdx === -1 ? lastSrcIdx : firstGreaterIdx - 1;
+    const channelIndexInSource = absoluteChannelIndex - this.sources[sourceIndex].channelOffset;
+    return {
+      sourceIndex,
+      channelIndexInSource
+    };
+  }
+
+  /**
+   * Change which directions to prioritize when prefetching. All chunks will be prefetched in these directions before
+   * any chunks are prefetched in any other directions.
+   */
+  setPrefetchPriority(directions) {
+    this.priorityDirections = directions;
+  }
+  syncMultichannelLoading(sync) {
+    this.syncChannels = sync;
+  }
+  updateFetchOptions(options) {
+    this.fetchOptions = {
+      ...this.fetchOptions,
+      ...options
+    };
+  }
+  loadDims(loadSpec) {
+    const [spaceUnit, timeUnit] = this.getUnitSymbols();
+    // Compute subregion size so we can factor that in
+    const maxExtent = this.maxExtent ?? new Box3(new Vector3(0, 0, 0), new Vector3(1, 1, 1));
+    const subregion = composeSubregion(loadSpec.subregion, maxExtent);
+    const regionSize = subregion.getSize(new Vector3());
+    const regionArr = [1, 1, regionSize.z, regionSize.y, regionSize.x];
+    const result = this.sources[0].scaleLevels.map((level, i) => {
+      const scale = this.getScale(i);
+      const dims = {
+        spaceUnit: spaceUnit,
+        timeUnit: timeUnit,
+        shape: this.orderByTCZYX(level.shape, 1).map((val, idx) => Math.max(Math.ceil(val * regionArr[idx]), 1)),
+        spacing: this.orderByTCZYX(scale, 1),
+        dataType: level.dtype
+      };
+      return dims;
+    });
+    return Promise.resolve(result);
+  }
+  createImageInfo(loadSpec) {
+    // We ensured most info (dims, chunks, etc.) matched between sources earlier, so we can just use the first source.
+    const source0 = this.sources[0];
+    const [t,, z, y, x] = source0.axesTCZYX;
+    const hasT = t > -1;
+    const hasZ = z > -1;
+    const levelToLoad = pickLevelToLoad(loadSpec, this.getLevelShapesZYX());
+    const shapeLv = source0.scaleLevels[levelToLoad].shape;
+    const [spatialUnit, timeUnit] = this.getUnitSymbols();
+
+    // Now we care about other sources: # of channels is the `channelOffset` of the last source plus its # of channels
+    const sourceLast = this.sources[this.sources.length - 1];
+    const cLast = sourceLast.axesTCZYX[1];
+    const lastHasC = cLast > -1;
+    const numChannels = sourceLast.channelOffset + (lastHasC ? sourceLast.scaleLevels[levelToLoad].shape[cLast] : 1);
+    // we need to make sure that the corresponding matched shapes
+    // use the min size of T
+    let times = 1;
+    if (hasT) {
+      times = shapeLv[t];
+      for (let i = 0; i < this.sources.length; i++) {
+        const shape = this.sources[i].scaleLevels[levelToLoad].shape;
+        const tindex = this.sources[i].axesTCZYX[0];
+        if (shape[tindex] < times) {
+          console.warn("The number of time points is not consistent across sources: ", shape[tindex], times);
+          times = shape[tindex];
+        }
+      }
+    }
+    if (!this.maxExtent) {
+      this.maxExtent = loadSpec.subregion.clone();
+    }
+
+    // from source 0:
+    const pxDimsLv = convertSubregionToPixels(loadSpec.subregion, new Vector3(shapeLv[x], shapeLv[y], hasZ ? shapeLv[z] : 1));
+    const pxSizeLv = pxDimsLv.getSize(new Vector3());
+    const atlasTileDims = computePackedAtlasDims(pxSizeLv.z, pxSizeLv.x, pxSizeLv.y);
+
+    // Channel names is the other place where we have to check every source
+    // Track which channel names we've seen so far, so that we can rename them to avoid name collisions
+    const channelNamesMap = new Map();
+    const channelNames = this.sources.flatMap(src => {
+      const sourceChannelNames = getSourceChannelNames(src);
+
+      // Resolve name collisions
+      return sourceChannelNames.map(channelName => {
+        const numMatchingChannels = channelNamesMap.get(channelName);
+        if (numMatchingChannels !== undefined) {
+          // If e.g. we've seen channel "Membrane" once before, rename this one to "Membrane (1)"
+          channelNamesMap.set(channelName, numMatchingChannels + 1);
+          return `${channelName} (${numMatchingChannels})`;
+        } else {
+          channelNamesMap.set(channelName, 1);
+          return channelName;
+        }
+      });
+    });
+    const alldims = source0.scaleLevels.map((level, i) => {
+      const dims = {
+        spaceUnit: spatialUnit,
+        timeUnit: timeUnit,
+        shape: this.orderByTCZYX(level.shape, 1),
+        spacing: this.getScale(i),
+        dataType: level.dtype
+      };
+      return dims;
+    });
+    const imgdata = {
+      name: source0.omeroMetadata?.name || "Volume",
+      atlasTileDims: [atlasTileDims.x, atlasTileDims.y],
+      subregionSize: [pxSizeLv.x, pxSizeLv.y, pxSizeLv.z],
+      subregionOffset: [0, 0, 0],
+      combinedNumChannels: numChannels,
+      channelNames,
+      multiscaleLevel: levelToLoad,
+      multiscaleLevelDims: alldims,
+      transform: {
+        translation: [0, 0, 0],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1]
+      }
+    };
+
+    // The `LoadSpec` passed in at this stage should represent the subset which this loader loads, not that
+    // which the volume contains. The volume contains the full extent of the subset recognized by this loader.
+    const fullExtentLoadSpec = {
+      ...loadSpec,
+      subregion: new Box3(new Vector3(0, 0, 0), new Vector3(1, 1, 1))
+    };
+    return Promise.resolve({
+      imageInfo: imgdata,
+      loadSpec: fullExtentLoadSpec
+    });
+  }
+  async prefetchChunk(scaleLevel, coords, subscriber) {
+    const {
+      store,
+      path
+    } = scaleLevel;
+    const separator = path.endsWith("/") ? "" : "/";
+    const key = path + separator + this.orderByDimension(coords).join("/");
+    // Calling `get` and doing nothing with the result still triggers a cache check, fetch, and insertion
+    await store.get(key, {
+      subscriber,
+      isPrefetch: true
+    }).catch(wrapVolumeLoadError(`Unable to prefetch chunk with key ${key}`, VolumeLoadErrorType.LOAD_DATA_FAILED, CHUNK_REQUEST_CANCEL_REASON));
+  }
+
+  /** Reads a list of chunk keys requested by a `loadVolumeData` call and sets up appropriate prefetch requests. */
+  beginPrefetch(keys, scaleLevel) {
+    // Convert keys to arrays of coords
+    const chunkCoords = keys.map(({
+      sourceIdx,
+      key
+    }) => {
+      const numDims = getDimensionCount(this.sources[sourceIdx].axesTCZYX);
+      const coordsInDimensionOrder = key.trim().split("/").slice(-numDims).filter(s => s !== "").map(s => parseInt(s, 10));
+      const sourceCoords = this.orderByTCZYX(coordsInDimensionOrder, 0, sourceIdx);
+      // Convert source channel index to absolute channel index for `ChunkPrefetchIterator`'s benefit
+      // (we match chunk coordinates output from `ChunkPrefetchIterator` back to sources below)
+      sourceCoords[1] += this.sources[sourceIdx].channelOffset;
+      return sourceCoords;
+    });
+
+    // Get number of chunks per dimension in every source array
+    const chunkDimsTCZYX = this.sources.map(src => {
+      const level = src.scaleLevels[scaleLevel];
+      const chunkDimsUnordered = level.shape.map((dim, idx) => Math.ceil(dim / level.chunks[idx]));
+      return this.orderByTCZYX(chunkDimsUnordered, 1);
+    });
+    // `ChunkPrefetchIterator` yields chunk coordinates in order of roughly how likely they are to be loaded next
+    const prefetchIterator = new ChunkPrefetchIterator(chunkCoords, this.fetchOptions.maxPrefetchDistance, chunkDimsTCZYX, this.priorityDirections, this.fetchOptions.onlyPriorityDirections);
+    const subscriber = this.requestQueue.addSubscriber();
+    let prefetchCount = 0;
+    for (const chunk of prefetchIterator) {
+      if (prefetchCount >= this.fetchOptions.maxPrefetchChunks) {
+        break;
+      }
+      // Match absolute channel coordinate back to source index and channel index
+      const {
+        sourceIndex,
+        channelIndexInSource
+      } = this.matchChannelToSource(chunk[1]);
+      const sourceScaleLevel = this.sources[sourceIndex].scaleLevels[scaleLevel];
+      chunk[1] = channelIndexInSource;
+      this.prefetchChunk(sourceScaleLevel, chunk, subscriber);
+      prefetchCount++;
+    }
+
+    // Clear out old prefetch requests (requests which also cover this new prefetch will be preserved)
+    if (this.prefetchSubscriber !== undefined) {
+      this.requestQueue.removeSubscriber(this.prefetchSubscriber, CHUNK_REQUEST_CANCEL_REASON);
+    }
+    this.prefetchSubscriber = subscriber;
+  }
+  updateImageInfoForLoad(imageInfo, loadSpec) {
+    // Apply `this.maxExtent` to subregion, if it exists
+    const maxExtent = this.maxExtent ?? new Box3(new Vector3(0, 0, 0), new Vector3(1, 1, 1));
+    const subregion = composeSubregion(loadSpec.subregion, maxExtent);
+
+    // Pick the level to load based on the subregion size
+    const multiscaleLevel = pickLevelToLoad({
+      ...loadSpec,
+      subregion
+    }, this.getLevelShapesZYX());
+    const array0Shape = this.sources[0].scaleLevels[multiscaleLevel].shape;
+
+    // Convert subregion to volume voxels
+    const [z, y, x] = this.sources[0].axesTCZYX.slice(2);
+    const regionPx = convertSubregionToPixels(subregion, new Vector3(array0Shape[x], array0Shape[y], z === -1 ? 1 : array0Shape[z]));
+
+    // Derive other image info properties from subregion and level to load
+    const subregionSize = regionPx.getSize(new Vector3());
+    const atlasTileDims = computePackedAtlasDims(subregionSize.z, subregionSize.x, subregionSize.y);
+    return {
+      ...imageInfo,
+      atlasTileDims: [atlasTileDims.x, atlasTileDims.y],
+      subregionSize: [subregionSize.x, subregionSize.y, subregionSize.z],
+      subregionOffset: [regionPx.min.x, regionPx.min.y, regionPx.min.z],
+      multiscaleLevel
+    };
+  }
+  async loadRawChannelData(imageInfo, loadSpec, onUpdateMetadata, onData) {
+    // This seemingly useless line keeps a stable local copy of `syncChannels` which the async closures below capture
+    // so that changes to `this.syncChannels` don't affect the behavior of loads in progress.
+    const syncChannels = this.syncChannels;
+    const updatedImageInfo = this.updateImageInfoForLoad(imageInfo, loadSpec);
+    onUpdateMetadata(updatedImageInfo);
+    const {
+      combinedNumChannels,
+      multiscaleLevel
+    } = updatedImageInfo;
+    const channelIndexes = loadSpec.channels ?? Array.from({
+      length: combinedNumChannels
+    }, (_, i) => i);
+    const subscriber = this.requestQueue.addSubscriber();
+
+    // Prefetch housekeeping: we want to save keys involved in this load to prefetch later
+    const keys = [];
+    const reportKeyBase = (sourceIdx, key, sub) => {
+      if (sub === subscriber) {
+        keys.push({
+          sourceIdx,
+          key
+        });
+      }
+    };
+    const resultChannelIndices = [];
+    const resultChannelData = [];
+    const resultChannelDtype = [];
+    const resultChannelRanges = [];
+    const channelPromises = channelIndexes.map(async ch => {
+      // Build slice spec
+      const min = new Vector3(...updatedImageInfo.subregionOffset);
+      const max = min.clone().add(new Vector3(...updatedImageInfo.subregionSize));
+      const {
+        sourceIndex: sourceIdx,
+        channelIndexInSource: sourceCh
+      } = this.matchChannelToSource(ch);
+      const unorderedSpec = [loadSpec.time, sourceCh, slice(min.z, max.z), slice(min.y, max.y), slice(min.x, max.x)];
+      const level = this.sources[sourceIdx].scaleLevels[multiscaleLevel];
+      const sliceSpec = this.orderByDimension(unorderedSpec, sourceIdx);
+      const reportKey = (key, sub) => reportKeyBase(sourceIdx, key, sub);
+      const result = await zarrGet(level, sliceSpec, {
+        opts: {
+          subscriber,
+          reportKey
+        }
+      }).catch(wrapVolumeLoadError("Could not load OME-Zarr volume data", VolumeLoadErrorType.LOAD_DATA_FAILED, CHUNK_REQUEST_CANCEL_REASON));
+      if (result?.data === undefined) {
+        return;
+      }
+      const converted = convertChannel(result.data, level.dtype);
+      if (syncChannels) {
+        resultChannelDtype.push(converted.dtype);
+        resultChannelData.push(converted.data);
+        resultChannelIndices.push(ch);
+        resultChannelRanges.push([converted.min, converted.max]);
+      } else {
+        onData([ch], [converted.dtype], [converted.data], [[converted.min, converted.max]]);
+      }
+    });
+
+    // Cancel any in-flight requests from previous loads that aren't useful to this one
+    if (this.loadSubscriber !== undefined) {
+      this.requestQueue.removeSubscriber(this.loadSubscriber, CHUNK_REQUEST_CANCEL_REASON);
+    }
+    this.loadSubscriber = subscriber;
+    this.beginPrefetch(keys, multiscaleLevel);
+    await Promise.all(channelPromises);
+    if (syncChannels) {
+      onData(resultChannelIndices, resultChannelDtype, resultChannelData, resultChannelRanges);
+    }
+    this.requestQueue.removeSubscriber(subscriber, CHUNK_REQUEST_CANCEL_REASON);
+  }
+}
+export { OMEZarrLoader };

package/es/loaders/OpenCellLoader.js

@@ -0,0 +1,65 @@
+import { ThreadableVolumeLoader, LoadSpec } from "./IVolumeLoader.js";
+import { computeAtlasSize } from "../ImageInfo.js";
+import { JsonImageInfoLoader } from "./JsonImageInfoLoader.js";
+import { getDataRange } from "../utils/num_utils.js";
+class OpenCellLoader extends ThreadableVolumeLoader {
+  async loadDims(_) {
+    const d = {
+      shape: [1, 2, 27, 600, 600],
+      spacing: [1, 1, 2, 1, 1],
+      spaceUnit: "",
+      // unknown unit.
+      dataType: "uint8",
+      timeUnit: ""
+    };
+    return [d];
+  }
+  async createImageInfo(_loadSpec) {
+    const numChannels = 2;
+
+    // we know these are standardized to 600x600, two channels, one channel per jpg.
+    const chnames = ["DNA", "Structure"];
+    const imgdata = {
+      name: "TEST",
+      atlasTileDims: [27, 1],
+      subregionSize: [600, 600, 27],
+      subregionOffset: [0, 0, 0],
+      combinedNumChannels: numChannels,
+      channelNames: chnames,
+      multiscaleLevel: 0,
+      multiscaleLevelDims: [{
+        shape: [1, numChannels, 27, 600, 600],
+        spacing: [1, 1, 2, 1, 1],
+        spaceUnit: "µm",
+        timeUnit: "",
+        dataType: "uint8"
+      }],
+      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()
+    };
+  }
+  loadRawChannelData(imageInfo, _loadSpec, _onUpdateMetadata, onData) {
+    // HQTILE or LQTILE
+    // make a json metadata dict for the two channels:
+    const urls = [{
+      name: "https://opencell.czbiohub.org/data/opencell-microscopy/roi/czML0383-P0007/czML0383-P0007-A02-PML0308-S13_ROI-0424-0025-0600-0600-LQTILE-CH405.jpg",
+      channels: [0]
+    }, {
+      name: "https://opencell.czbiohub.org/data/opencell-microscopy/roi/czML0383-P0007/czML0383-P0007-A02-PML0308-S13_ROI-0424-0025-0600-0600-LQTILE-CH488.jpg",
+      channels: [1]
+    }];
+    const [w, h] = computeAtlasSize(imageInfo);
+    // all data coming from this loader is natively 8-bit
+    return JsonImageInfoLoader.loadVolumeAtlasData(urls, (ch, dtype, data) => onData(ch, dtype, data, data.map(getDataRange), [w, h]));
+  }
+}
+export { OpenCellLoader };

package/es/loaders/RawArrayLoader.js

@@ -0,0 +1,89 @@
+import { Box3, Vector3 } from "three";
+import { ThreadableVolumeLoader } from "./IVolumeLoader.js";
+import { computePackedAtlasDims } from "./VolumeLoaderUtils.js";
+import { getDataRange } from "../utils/num_utils.js";
+
+// this is the form in which a 4D numpy array arrives as converted
+// by jupyterlab into a js object.
+// This loader does not yet support multiple time samples.
+
+// minimal metadata for visualization
+
+const convertImageInfo = json => {
+  const atlasTileDims = computePackedAtlasDims(json.sizeZ, json.sizeX, json.sizeY);
+  return {
+    name: json.name,
+    // assumption: the data is already sized to fit in our viewer's preferred
+    // memory footprint (a tiled atlas texture as of this writing)
+    atlasTileDims: [atlasTileDims.x, atlasTileDims.y],
+    subregionSize: [json.sizeX, json.sizeY, json.sizeZ],
+    subregionOffset: [0, 0, 0],
+    combinedNumChannels: json.sizeC,
+    channelNames: json.channelNames,
+    channelColors: undefined,
+    multiscaleLevel: 0,
+    multiscaleLevelDims: [{
+      shape: [1, json.sizeC, json.sizeZ, json.sizeY, json.sizeX],
+      spacing: [1, 1, json.physicalPixelSize[2], json.physicalPixelSize[1], json.physicalPixelSize[0]],
+      spaceUnit: json.spatialUnit || "μm",
+      timeUnit: "s",
+      dataType: "uint8"
+    }],
+    transform: {
+      translation: [0, 0, 0],
+      rotation: [0, 0, 0],
+      scale: [1, 1, 1]
+    },
+    userData: json.userData
+  };
+};
+class RawArrayLoader extends ThreadableVolumeLoader {
+  constructor(rawData, rawDataInfo) {
+    super();
+    this.jsonInfo = rawDataInfo;
+    this.data = rawData;
+    // check consistent dims
+    if (this.data.shape[0] !== this.jsonInfo.sizeC || this.data.shape[1] !== this.jsonInfo.sizeZ || this.data.shape[2] !== this.jsonInfo.sizeY || this.data.shape[3] !== this.jsonInfo.sizeX) {
+      throw new Error("RawArrayLoader: data shape does not match metadata");
+    }
+  }
+  async loadDims(_loadSpec) {
+    const jsonInfo = this.jsonInfo;
+    const d = {
+      shape: [1, jsonInfo.sizeC, jsonInfo.sizeZ, jsonInfo.sizeY, jsonInfo.sizeX],
+      spacing: [1, 1, jsonInfo.physicalPixelSize[2], jsonInfo.physicalPixelSize[1], jsonInfo.physicalPixelSize[0]],
+      spaceUnit: jsonInfo.spatialUnit || "μm",
+      dataType: "uint8",
+      timeUnit: "s" // time unit not specified
+    };
+    return [d];
+  }
+  async createImageInfo(loadSpec) {
+    return {
+      imageInfo: convertImageInfo(this.jsonInfo),
+      loadSpec
+    };
+  }
+  loadRawChannelData(imageInfo, loadSpec, onUpdateMetadata, onData) {
+    const requestedChannels = loadSpec.channels;
+    const adjustedLoadSpec = {
+      ...loadSpec,
+      // `subregion` and `multiscaleLevel` are unused by this loader
+      subregion: new Box3(new Vector3(0, 0, 0), new Vector3(1, 1, 1)),
+      multiscaleLevel: 0
+    };
+    onUpdateMetadata(undefined, adjustedLoadSpec);
+    for (let chindex = 0; chindex < imageInfo.combinedNumChannels; ++chindex) {
+      if (requestedChannels && requestedChannels.length > 0 && !requestedChannels.includes(chindex)) {
+        continue;
+      }
+      const volSizeBytes = this.data.shape[3] * this.data.shape[2] * this.data.shape[1]; // x*y*z pixels * 1 byte/pixel
+      const channelData = new Uint8Array(this.data.buffer.buffer, chindex * volSizeBytes, volSizeBytes);
+      const range = getDataRange(channelData);
+      // all data coming from this loader is natively 8-bit
+      onData([chindex], ["uint8"], [channelData], [range]);
+    }
+    return Promise.resolve();
+  }
+}
+export { RawArrayLoader };