@aics/vole-core 3.12.4 → 3.13.1

package/README.md

@@ -1,6 +1,9 @@
 # Vol-E core
 
-This is a WebGL canvas-based volume viewer. It can display multichannel volume data with high channel counts, and is optimized for OME-Zarr files. With OME-Zarr, the viewer can prefetch and cache Zarr chunks in browser memory for optimized performance.
+![NPM Version](https://img.shields.io/npm/v/%40aics%2Fvole-core)
+![NPM Last Update](https://img.shields.io/npm/last-update/%40aics%2Fvole-core)
+
+**Vol-E core** is a WebGL canvas-based volume viewer. It can display multichannel volume data with high channel counts. The viewer is optimized for OME-Zarr files, and can prefetch and cache Zarr chunks in browser memory for performance.
 
 The Vol-E core package exposes several key modules:
 
@@ -16,7 +19,7 @@ There are several ways to deliver volume data to the viewer:
 - Load raw TypedArrays of 3d volume data ( see `RawArrayLoader` and `Volume.setChannelDataFromVolume` ).
 - (legacy) Load texture atlases as .png files or Uint8Arrays containing volume slices tiled across a 2d image ( see `JsonImageInfoLoader` and `Volume.setChannelDataFromAtlas` ).
 
-# Example
+## Example
 
 See [`public/index.ts`](./public/index.ts) for a working example. (`npm install; npm run dev` will run that code)
 
@@ -59,19 +62,20 @@ view3D.addVolume(volume);
 loader.loadVolumeData(volume);
 ```
 
-# React example
+## React example
 
-See [vole-app](https://github.com/allen-cell-animated/website-3d-cell-viewer) for a complete application that wraps View3D in a React component.
+See [vole-app](https://github.com/allen-cell-animated/vole-app) for a complete application that wraps Vol-E core in a React component.
 
-# Acknowledgements
+## Acknowledgements
 
 The ray marched volume shader is a heavily modified version of one that has its origins in [Bisque](http://bioimage.ucsb.edu/bisque).
 The core path tracing implementation was adapted from ExposureRender.
 
-## BisQue license
+### BisQue license
 
 Center for Bio-Image Informatics, University of California at Santa Barbara
 
+```text
 Copyright (c) 2007-2017 by the Regents of the University of California
 All rights reserved
 
@@ -106,14 +110,18 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 The views and conclusions contained in the software and documentation
 are those of the authors and should not be interpreted as representing
 official policies, either expressed or implied, of the Regents of the University of California.
+```
 
 ## Exposure Render license
 
-    Copyright (c) 2011, T. Kroes <t.kroes@tudelft.nl>
-    All rights reserved.
-    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-    - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-    - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-    - Neither the name of the TU Delft nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+```text
+Copyright (c) 2011, T. Kroes <t.kroes@tudelft.nl>
+All rights reserved.
 
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+- Neither the name of the TU Delft nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```

package/es/View3d.js

@@ -96,6 +96,9 @@ export class View3d {
   getDOMElement() {
     return this.canvas3d.containerdiv;
   }
+  getCanvasDOMElement() {
+    return this.canvas3d.renderer.domElement;
+  }
   getCameraState() {
     return this.canvas3d.getCameraState();
   }
@@ -106,9 +109,16 @@ export class View3d {
 
   /**
    * Force a redraw.
+   * @param synchronous If true, the redraw will be done synchronously. If false (default), the
+   * redraw will be done asynchronously via `requestAnimationFrame`. Redraws should be done async
+   * whenever possible for the best performance.
    */
-  redraw() {
-    this.canvas3d.redraw();
+  redraw(synchronous = false) {
+    if (synchronous) {
+      this.canvas3d.onAnimationLoop();
+    } else {
+      this.canvas3d.redraw();
+    }
   }
   unsetImage() {
     if (this.image) {
@@ -206,10 +216,11 @@ export class View3d {
   }
   setTime(volume, time, onChannelLoaded) {
     const timeClamped = Math.max(0, Math.min(time, volume.imageInfo.times - 1));
-    volume.updateRequiredData({
+    const loadPromise = volume.updateRequiredData({
       time: timeClamped
     }, onChannelLoaded);
     this.updateTimestepIndicator(volume);
+    return loadPromise;
   }
 
   /**
@@ -826,16 +837,21 @@ export class View3d {
     const prefetch = pane.addFolder({
       title: "Prefetch"
     });
+    // Not all `IVolumeLoader`s implement `updateFetchOptions`. This cast makes it sound to try to call it, but we
+    //   still have to be careful to null-check it!
+    // TODO depending on how the relationship between loaders and images pans out, it's not impossible that the loader
+    //   for an image will be changeable and this variable will capture a stale reference to old loaders. Careful!
+    const loader = this.image?.volume.loader;
     // one number will be used for all axis directions
     prefetch.addInput(allGlobalLoadingOptions, "numChunksToPrefetchAhead").on("change", event => {
-      this.loaderContext?.getActiveLoader()?.updateFetchOptions({
+      loader?.updateFetchOptions?.({
         maxPrefetchDistance: [event.value, event.value, event.value, event.value]
       });
       this.image?.volume.updateRequiredData({});
     });
     // should we try to prefetch along Z even if we are only playing along T?
     prefetch.addInput(allGlobalLoadingOptions, "prefetchAlongNonPlayingAxis").on("change", event => {
-      this.loaderContext?.getActiveLoader()?.updateFetchOptions({
+      loader?.updateFetchOptions?.({
         onlyPriorityDirections: !event.value
       });
     });

package/es/Volume.js

@@ -139,7 +139,7 @@ export default class Volume {
       }
     }
     if (shouldReload) {
-      this.loadNewData(onChannelLoaded);
+      await this.loadNewData(onChannelLoaded);
     }
   }
   async loadScaleLevelDims() {

package/es/VolumeCache.js

@@ -1,3 +1,9 @@
+export const isChunk = data => data.data !== undefined;
+const chunkSize = ({
+  data
+}) => Array.isArray(data) ? data.length : data.byteLength;
+const dataSize = data => data.byteLength ?? chunkSize(data);
+
 /** Default: 250MB. Should be large enough to be useful but safe for most any computer that can run the app */
 const CACHE_MAX_SIZE_DEFAULT = 250_000_000;
 export default class VolumeCache {
@@ -31,7 +37,7 @@ export default class VolumeCache {
    */
   removeEntryFromStore(entry) {
     this.entries.delete(entry.key);
-    this.currentSize -= entry.data.byteLength;
+    this.currentSize -= dataSize(entry.data);
   }
 
   /**
@@ -98,7 +104,8 @@ export default class VolumeCache {
    * @returns {boolean} a boolean indicating whether the insertion succeeded.
    */
   insert(key, data) {
-    if (data.byteLength > this.maxSize) {
+    const size = dataSize(data);
+    if (size > this.maxSize) {
       console.error("VolumeCache: attempt to insert a single entry larger than the cache");
       return false;
     }
@@ -120,7 +127,7 @@ export default class VolumeCache {
     };
     this.addEntryAsFirst(newEntry);
     this.entries.set(key, newEntry);
-    this.currentSize += data.byteLength;
+    this.currentSize += size;
 
     // Evict until size is within limit
     while (this.currentSize > this.maxSize) {

package/es/VolumeRenderSettings.js

@@ -3,14 +3,23 @@ import { Euler, Vector2, Vector3 } from "three";
  * Marks groups of related settings that may have changed.
  */
 export let SettingsFlags = /*#__PURE__*/function (SettingsFlags) {
+  /** parameters: translation, rotation, scale, flipAxes */
   SettingsFlags[SettingsFlags["TRANSFORM"] = 1] = "TRANSFORM";
+  /** parameters: gammaMin, gammaLevel, gammaMax, brightness*/
   SettingsFlags[SettingsFlags["CAMERA"] = 2] = "CAMERA";
+  /** parameters: showBoundingBox, boundingBoxColor */
   SettingsFlags[SettingsFlags["BOUNDING_BOX"] = 4] = "BOUNDING_BOX";
+  /** parameters: bounds, zSlice */
   SettingsFlags[SettingsFlags["ROI"] = 8] = "ROI";
+  /** parameters: maskAlpha */
   SettingsFlags[SettingsFlags["MASK_ALPHA"] = 16] = "MASK_ALPHA";
+  /** parameters: density, diffuse, specular, emissive, glossiness */
   SettingsFlags[SettingsFlags["MATERIAL"] = 32] = "MATERIAL";
+  /** parameters: resolution, useInterpolation, pixelSamplingRate, primaryRayStepSize, secondaryRayStepSize*/
   SettingsFlags[SettingsFlags["SAMPLING"] = 64] = "SAMPLING";
+  /** parameters: isOrtho, orthoScale, viewAxis, visible, maxProjectMode */
   SettingsFlags[SettingsFlags["VIEW"] = 128] = "VIEW";
+  /** parameters: maskChannelIndex */
   SettingsFlags[SettingsFlags["MASK_DATA"] = 256] = "MASK_DATA";
   SettingsFlags[SettingsFlags["ALL"] = 1023] = "ALL";
   return SettingsFlags;
@@ -19,7 +28,9 @@ export let Axis = /*#__PURE__*/function (Axis) {
   Axis["X"] = "x";
   Axis["Y"] = "y";
   Axis["Z"] = "z";
+  /** Alias for NONE, indicates 3D mode */
   Axis["XYZ"] = "";
+  /** No current axis, indicates 3D mode */
   Axis["NONE"] = "";
   return Axis;
 }({});

package/es/loaders/JsonImageInfoLoader.js

@@ -1,6 +1,7 @@
 import { Box3, Vector3 } from "three";
 import { ThreadableVolumeLoader } from "./IVolumeLoader.js";
 import { computeAtlasSize } from "../ImageInfo.js";
+import { isChunk } from "../VolumeCache.js";
 import { getDataRange } from "../utils/num_utils.js";
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -169,7 +170,7 @@ class JsonImageInfoLoader extends ThreadableVolumeLoader {
       for (let j = 0; j < Math.min(image.channels.length, 4); ++j) {
         const chindex = image.channels[j];
         const cacheResult = cache?.get(`${image.name}/${chindex}`);
-        if (cacheResult) {
+        if (cacheResult && !isChunk(cacheResult)) {
           // all data coming from this loader is natively 8-bit
           const channelData = new Uint8Array(cacheResult);
           if (syncChannels) {

package/es/loaders/OmeZarrLoader.js

@@ -1,17 +1,16 @@
 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 * as zarr from "zarrita";
+const {
+  slice
+} = zarr;
 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 { 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";
+import wrapArray from "./zarr_utils/wrapArray.js";
+import { assertMetadataHasMultiscales, toOMEZarrMetaV4, 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
@@ -97,23 +96,26 @@ class OMEZarrLoader extends ThreadableVolumeLoader {
 
     // Create one `ZarrSource` per URL
     const sourceProms = urlsArr.map(async (url, i) => {
-      const store = new WrappedStore(new FetchStore(url), cache, queue);
+      const store = new zarr.FetchStore(url);
       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));
+      const sourceName = urlsArr.length > 1 ? `Zarr source ${i}` : "Zarr";
+      const meta = toOMEZarrMetaV4(group.attrs);
+      assertMetadataHasMultiscales(meta, sourceName);
 
       // Pick scene (multiscale)
       let scene = scenesArr[Math.min(i, scenesArr.length - 1)];
-      if (scene > group.attrs.multiscales?.length) {
+      if (scene > meta.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");
+      validateOMEZarrMetadata(meta, scene, sourceName);
       const {
         multiscales,
         omero
-      } = group.attrs;
+      } = meta;
       const multiscaleMetadata = multiscales[scene];
 
       // Open all scale levels of multiscale
@@ -121,7 +123,7 @@ class OMEZarrLoader extends ThreadableVolumeLoader {
         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)));
+      }).then(array => wrapArray(array, url, cache, queue)).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 {
@@ -330,30 +332,25 @@ class OMEZarrLoader extends ThreadableVolumeLoader {
       loadSpec: fullExtentLoadSpec
     });
   }
-  async prefetchChunk(scaleLevel, coords, subscriber) {
-    const {
-      store,
-      path
-    } = scaleLevel;
-    const separator = path.endsWith("/") ? "" : "/";
-    const key = path + separator + this.orderByDimension(coords).join("/");
+  prefetchChunk(scaleLevel, coords, subscriber) {
     // Calling `get` and doing nothing with the result still triggers a cache check, fetch, and insertion
-    await store.get(key, {
+    scaleLevel.getChunk(this.orderByDimension(coords), {
       subscriber,
       isPrefetch: true
-    }).catch(wrapVolumeLoadError(`Unable to prefetch chunk with key ${key}`, VolumeLoadErrorType.LOAD_DATA_FAILED, CHUNK_REQUEST_CANCEL_REASON));
+    }).catch(wrapVolumeLoadError(`Unable to prefetch chunk with coords ${coords.join(", ")}`, 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
+    if (keys.length === 0) {
+      return;
+    }
     const chunkCoords = keys.map(({
       sourceIdx,
-      key
+      coords
     }) => {
-      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);
+      const sourceCoords = this.orderByTCZYX(coords, 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;
@@ -366,6 +363,7 @@ class OMEZarrLoader extends ThreadableVolumeLoader {
       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();
@@ -435,11 +433,11 @@ class OMEZarrLoader extends ThreadableVolumeLoader {
 
     // Prefetch housekeeping: we want to save keys involved in this load to prefetch later
     const keys = [];
-    const reportKeyBase = (sourceIdx, key, sub) => {
+    const reportChunkBase = (sourceIdx, coords, sub) => {
       if (sub === subscriber) {
         keys.push({
           sourceIdx,
-          key
+          coords
         });
       }
     };
@@ -458,11 +456,12 @@ class OMEZarrLoader extends ThreadableVolumeLoader {
       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, {
+      const reportChunk = (coords, sub) => reportChunkBase(sourceIdx, coords, sub);
+      console.log(level);
+      const result = await zarr.get(level, sliceSpec, {
         opts: {
           subscriber,
-          reportKey
+          reportChunk
         }
       }).catch(wrapVolumeLoadError("Could not load OME-Zarr volume data", VolumeLoadErrorType.LOAD_DATA_FAILED, CHUNK_REQUEST_CANCEL_REASON));
       if (result?.data === undefined) {

package/es/loaders/TiffLoader.js

@@ -191,7 +191,9 @@ class TiffLoader extends ThreadableVolumeLoader {
           bytesPerSample: getBytesPerSample(dims.pixeltype),
           url: this.url
         };
-        const worker = new Worker(new URL("../workers/FetchTiffWorker", import.meta.url));
+        const worker = new Worker(new URL("../workers/FetchTiffWorker", import.meta.url), {
+          type: "module"
+        });
         worker.onmessage = e => {
           if (e.data.isError) {
             reject(deserializeError(e.data.error));

package/es/loaders/VolumeLoadError.js

@@ -1,5 +1,5 @@
 import { errorConstructors } from "serialize-error";
-import { NodeNotFoundError, KeyError } from "@zarrita/core";
+import { NodeNotFoundError, KeyError } from "zarrita";
 // 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. */

package/es/loaders/zarr_utils/ChunkPrefetchIterator.js

@@ -34,6 +34,13 @@ export default class ChunkPrefetchIterator {
       updateMinMax(chunk[4], extrema[3]);
     }
 
+    // Bail out if we have any non-finite values in the extrema (the iterator will be empty)
+    if (extrema.flat().some(val => !Number.isFinite(val))) {
+      this.directionStates = [];
+      this.priorityDirectionStates = [];
+      return;
+    }
+
     // Create `PrefetchDirectionState`s for each direction
     this.directionStates = [];
     this.priorityDirectionStates = [];

package/es/loaders/zarr_utils/validation.js

@@ -1,4 +1,11 @@
 import { VolumeLoadError, VolumeLoadErrorType } from "../VolumeLoadError.js";
+/**
+ * If `meta` is the top-level metadata of a zarr node formatted according to the OME-Zarr spec version 0.5, returns
+ * the object formatted according to v0.4 of the spec. For our purposes this just means flattening out the `ome` key.
+ *
+ * Return type is `unknown` because this does no actual validation; use `validateOMEZarrMetadata` for that.
+ */
+export const toOMEZarrMetaV4 = meta => meta.ome ?? meta;
 function isObjectWithProp(obj, prop) {
   return typeof obj === "object" && obj !== null && prop in obj;
 }
@@ -17,18 +24,22 @@ function assertPropIsArray(obj, prop, name = "zarr") {
   }
 }
 
+/** Intermediate stage of validation, before we've picked a single multiscale to validate */
+
+export function assertMetadataHasMultiscales(meta, name = "zarr") {
+  // data is an object with a key "multiscales", which is a non-empty array
+  assertMetadataHasProp(meta, "multiscales", name);
+  assertPropIsArray(meta, "multiscales", name);
+}
+
 /**
- * Validates that the `OMEZarrMetadata` record `data` has the minimal amount of data required to open a volume. Since
+ * Validates that the `OMEZarrMetadata` record `meta` 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);
-
+export function validateOMEZarrMetadata(meta, multiscaleIdx = 0, name = "zarr") {
   // check that a multiscale metadata entry exists at `multiscaleIdx`
-  const multiscaleMeta = data.multiscales[multiscaleIdx];
+  const multiscaleMeta = meta.multiscales[multiscaleIdx];
   if (!multiscaleMeta) {
     throw new VolumeLoadError(`${name} metadata does not have requested multiscale level ${multiscaleIdx}`, {
       type: VolumeLoadErrorType.INVALID_METADATA

package/es/loaders/zarr_utils/wrapArray.js

@@ -0,0 +1,39 @@
+import { isChunk } from "../../VolumeCache.js";
+export default function wrapArray(array, basePath, cache, queue) {
+  const path = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  const keyBase = path + array.path + (array.path.endsWith("/") ? "" : "/");
+  const getChunk = async (coords, opts) => {
+    if (opts?.subscriber && opts.reportChunk) {
+      opts.reportChunk(coords, opts.subscriber);
+    }
+    const fullKey = keyBase + coords.join(",");
+    const cacheResult = cache?.get(fullKey);
+    if (cacheResult && isChunk(cacheResult)) {
+      return cacheResult;
+    }
+    let result;
+    if (queue && opts?.subscriber) {
+      result = await queue.addRequest(fullKey, opts?.subscriber, () => array.getChunk(coords, opts), opts.isPrefetch);
+    } else {
+      result = await array.getChunk(coords, opts);
+    }
+    cache?.insert(fullKey, result);
+    return result;
+  };
+  return new Proxy(array, {
+    get: (target, prop) => {
+      if (prop === "getChunk") {
+        return getChunk;
+      }
+
+      // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy#no_private_property_forwarding
+      const value = target[prop];
+      if (value instanceof Function) {
+        return function (...args) {
+          return value.apply(target, args);
+        };
+      }
+      return value;
+    }
+  });
+}

package/es/types/NaiveSurfaceNets.d.ts

@@ -7,5 +7,5 @@ declare function SurfaceNets(data: any, dims: any, isovalue: any): {
     vertices: number[][];
     faces: number[][];
 };
-declare function ConstructTHREEGeometry(surfaceNetResult: any): BufferGeometry[];
+declare function ConstructTHREEGeometry(surfaceNetResult: any): BufferGeometry<import("three").NormalBufferAttributes>[];
 import { BufferGeometry } from "three/src/core/BufferGeometry";

package/es/types/RayMarchedAtlasVolume.d.ts

@@ -33,7 +33,7 @@ export default class RayMarchedAtlasVolume implements VolumeRenderImpl {
     private createGeometry;
     private createTickMarks;
     cleanup(): void;
-    doRender(renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | Texture): void;
+    doRender(renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | Texture | null): void;
     get3dObject(): Group;
     private setUniform;
     updateActiveChannels(channelcolors: FuseChannel[], channeldata: Channel[]): void;

package/es/types/ThreeJsPanel.d.ts

@@ -18,7 +18,7 @@ export declare class ThreeJsPanel {
     scene: Scene;
     private meshRenderTarget;
     private meshRenderToBuffer;
-    animateFuncs: ((renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture) => void)[];
+    animateFuncs: ((renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | null) => void)[];
     private inRenderLoop;
     private requestedRender;
     hasWebGL2: boolean;
@@ -81,7 +81,7 @@ export declare class ThreeJsPanel {
     replaceCamera(newCam: PerspectiveCamera | OrthographicCamera): void;
     replaceControls(newControls: TrackballControls): void;
     switchViewMode(mode: string): void;
-    getMeshDepthTexture(): DepthTexture;
+    getMeshDepthTexture(): DepthTexture | null;
     resize(comp: HTMLElement | null, w?: number, h?: number, _ow?: number, _oh?: number, _eOpts?: unknown): void;
     setClearColor(color: Color, alpha: number): void;
     getWidth(): number;

package/es/types/TrackballControls.d.ts

@@ -1,5 +1,5 @@
 export default TrackballControls;
-declare class TrackballControls extends EventDispatcher<import("three").Event> {
+declare class TrackballControls extends EventDispatcher<any> {
     constructor(object: any, domElement: any);
     object: any;
     domElement: any;

package/es/types/View3d.d.ts

@@ -49,12 +49,16 @@ export declare class View3d {
      */
     capture(dataurlcallback: (name: string) => void): void;
     getDOMElement(): HTMLDivElement;
+    getCanvasDOMElement(): HTMLCanvasElement;
     getCameraState(): CameraState;
     setCameraState(transform: Partial<CameraState>): void;
     /**
      * Force a redraw.
+     * @param synchronous If true, the redraw will be done synchronously. If false (default), the
+     * redraw will be done asynchronously via `requestAnimationFrame`. Redraws should be done async
+     * whenever possible for the best performance.
      */
-    redraw(): void;
+    redraw(synchronous?: boolean): void;
     unsetImage(): VolumeDrawable | undefined;
     /**
      * Add a new volume image to the viewer.  (The viewer currently only supports a single image at a time - adding repeatedly, without removing in between, is a potential resource leak)
@@ -92,7 +96,7 @@ export declare class View3d {
     onVolumeChannelAdded(volume: Volume, newChannelIndex: number): void;
     onVolumeLoadError(volume: Volume, error: unknown): void;
     setLoadErrorHandler(handler: ((volume: Volume, error: unknown) => void) | undefined): void;
-    setTime(volume: Volume, time: number, onChannelLoaded?: PerChannelCallback): void;
+    setTime(volume: Volume, time: number, onChannelLoaded?: PerChannelCallback): Promise<void>;
     /**
      * Nudge the scale level loaded into this volume off the one chosen by the loader.
      * E.g. a bias of `1` will load 1 scale level lower than "ideal."

package/es/types/VolumeCache.d.ts

@@ -1,3 +1,6 @@
+import { Chunk, DataType } from "zarrita";
+export type CacheData = ArrayBuffer | Chunk<DataType>;
+export declare const isChunk: (data: CacheData) => data is Chunk<DataType>;
 export default class VolumeCache {
     private entries;
     readonly maxSize: number;
@@ -31,11 +34,11 @@ export default class VolumeCache {
      * Adds a new entry to the cache.
      * @returns {boolean} a boolean indicating whether the insertion succeeded.
      */
-    insert(key: string, data: ArrayBuffer): boolean;
+    insert(key: string, data: CacheData): boolean;
     /** Internal implementation of `get`. Returns all entry metadata, not just the raw data. */
     private getEntry;
     /** Attempts to get a single entry from the cache. */
-    get(key: string): ArrayBuffer | undefined;
+    get(key: string): CacheData | undefined;
     /** Clears all cache entries whose keys begin with the specified prefix. */
     clearWithPrefix(prefix: string): void;
     /** Clears all data from the cache. */

package/es/types/VolumeDrawable.d.ts

@@ -56,7 +56,7 @@ export default class VolumeDrawable {
     setGamma(gmin: number, glevel: number, gmax: number): void;
     setFlipAxes(flipX: -1 | 1, flipY: -1 | 1, flipZ: -1 | 1): void;
     setMaxProjectMode(isMaxProject: boolean): void;
-    onAnimate(renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | Texture): void;
+    onAnimate(renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | Texture | null): void;
     getViewMode(): Axis;
     getIsovalue(channel: number): number | undefined;
     hasIsosurface(channel: number): boolean;

package/es/types/VolumeRenderImpl.d.ts

@@ -13,7 +13,7 @@ export interface VolumeRenderImpl {
      */
     updateSettings: (settings: VolumeRenderSettings, dirtyFlags?: number | SettingsFlags) => void;
     get3dObject: () => Object3D;
-    doRender: (renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | Texture) => void;
+    doRender: (renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | Texture | null) => void;
     updateVolumeDimensions: () => void;
     cleanup: () => void;
     viewpointMoved: () => void;

package/es/types/index.d.ts

@@ -22,7 +22,7 @@ import { Light, AREA_LIGHT, SKY_LIGHT } from "./Light.js";
 export type { ImageInfo } from "./ImageInfo.js";
 export type { ControlPoint } from "./Lut.js";
 export type { CreateLoaderOptions } from "./loaders/index.js";
-export type { IVolumeLoader, PerChannelCallback } from "./loaders/IVolumeLoader.js";
+export type { IVolumeLoader, PerChannelCallback, ThreadableVolumeLoader } from "./loaders/IVolumeLoader.js";
 export type { ZarrLoaderFetchOptions } from "./loaders/OmeZarrLoader.js";
 export type { WorkerLoader } from "./workers/VolumeLoaderContext.js";
 export { Histogram, Lut, remapControlPoints, View3d, Volume, VolumeDrawable, LoadSpec, VolumeMaker, VolumeCache, RequestQueue, SubscribableRequestQueue, PrefetchDirection, OMEZarrLoader, JsonImageInfoLoader, RawArrayLoader, type RawArrayData, type RawArrayInfo, type RawArrayLoaderOptions, TiffLoader, VolumeLoaderContext, VolumeLoadError, VolumeLoadErrorType, VolumeFileFormat, createVolumeLoader, Channel, Light, ViewportCorner, AREA_LIGHT, RENDERMODE_PATHTRACE, RENDERMODE_RAYMARCH, SKY_LIGHT, type CameraState, };