@aics/vole-core 3.12.4

package/es/workers/VolumeLoaderContext.js

@@ -0,0 +1,271 @@
+import { deserializeError } from "serialize-error";
+import throttledQueue from "throttled-queue";
+import { VolumeFileFormat, pathToFileType } from "../loaders/index.js";
+import { ThreadableVolumeLoader } from "../loaders/IVolumeLoader.js";
+import { RawArrayLoader } from "../loaders/RawArrayLoader.js";
+import { TiffLoader } from "../loaders/TiffLoader.js";
+import { WorkerMsgType, WorkerResponseResult, WorkerEventType } from "./types.js";
+import { rebuildLoadSpec } from "./util.js";
+const throttle = throttledQueue(1, 16);
+/**
+ * A handle that holds the worker and manages requests and messages to/from it.
+ *
+ * `VolumeLoaderContext` and every `LoaderWorker` it creates all hold references to one `SharedLoadWorkerHandle`.
+ * They use it to interact with the worker via `sendMessage`, which speaks the protocol defined in ./types.ts and
+ * converts messages received from the worker into resolved `Promise`s and called callbacks.
+ *
+ * This class exists to represent that access to the worker is shared between `VolumeLoaderContext` and any
+ * `LoaderWorker`s. This is as opposed to implementing `sendMessage` directly on `VolumeLoaderContext`, where making
+ * the method public to `LoaderWorker`s would require also allowing access to users of the class.
+ */
+class SharedLoadWorkerHandle {
+  pendingRequests = [];
+  workerOpen = true;
+  throttleChannelData = false;
+  onChannelData = undefined;
+  onUpdateMetadata = undefined;
+  constructor() {
+    this.worker = new Worker(new URL("./VolumeLoadWorker", import.meta.url));
+    this.worker.onmessage = this.receiveMessage.bind(this);
+  }
+
+  /** Given a handle for settling a promise when a response is received from the worker, store it and return its ID */
+  registerMessagePromise(prom) {
+    for (const [i, pendingPromise] of this.pendingRequests.entries()) {
+      if (pendingPromise === undefined) {
+        this.pendingRequests[i] = prom;
+        return i;
+      }
+    }
+    return this.pendingRequests.push(prom) - 1;
+  }
+  get isOpen() {
+    return this.workerOpen;
+  }
+
+  /** Close the worker. */
+  close() {
+    this.worker.terminate();
+    this.workerOpen = false;
+  }
+
+  /**
+   * Send a message of type `T` to the worker.
+   * Returns a `Promise` that resolves with the worker's response, or rejects with an error message.
+   */
+  sendMessage(type, payload) {
+    let msgId = -1;
+    const promise = new Promise((resolve, reject) => {
+      msgId = this.registerMessagePromise({
+        type,
+        resolve,
+        reject
+      });
+    });
+    const msg = {
+      msgId,
+      type,
+      payload
+    };
+    this.worker.postMessage(msg);
+    return promise;
+  }
+
+  /** Receive a message from the worker. If it's an event, call a callback; otherwise, resolve/reject a promise. */
+  receiveMessage({
+    data
+  }) {
+    if (data.responseResult === WorkerResponseResult.EVENT) {
+      if (data.eventType === WorkerEventType.CHANNEL_LOAD) {
+        if (this.onChannelData) {
+          if (this.throttleChannelData) {
+            throttle(() => this.onChannelData ? this.onChannelData(data) : {});
+          } else {
+            this.onChannelData ? this.onChannelData(data) : {};
+          }
+        }
+      } else if (data.eventType === WorkerEventType.METADATA_UPDATE) {
+        this.onUpdateMetadata?.(data);
+      }
+    } else {
+      const prom = this.pendingRequests[data.msgId];
+      if (prom === undefined) {
+        throw new Error(`Received response for unknown message ID ${data.msgId}`);
+      }
+      if (prom.type !== data.type) {
+        throw new Error(`Received response of type ${data.type} for message of type ${prom.type}`);
+      }
+      if (data.responseResult === WorkerResponseResult.ERROR) {
+        prom.reject(deserializeError(data.payload));
+      } else {
+        prom.resolve(data.payload);
+      }
+      this.pendingRequests[data.msgId] = undefined;
+    }
+  }
+  setThrottleChannelData(throttle) {
+    this.throttleChannelData = throttle;
+  }
+}
+
+/**
+ * A context in which volume loaders can be run, which allows loading to run on a WebWorker (where it won't block
+ * rendering or UI updates) and loaders to share a single `VolumeCache` and `RequestQueue`.
+ *
+ * ### To use:
+ * 1. Create a `VolumeLoaderContext` with the desired cache and queue configuration.
+ * 2. Before creating a loader, await `onOpen` to ensure the worker is ready.
+ * 3. Create a loader with `createLoader`. This accepts nearly the same arguments as `createVolumeLoader`, but without
+ *    options to directly link to a cache or queue (the loader will always be linked to the context's shared instances
+ *    of these if possible).
+ *
+ * The returned `WorkerLoader` can be used like any other `IVolumeLoader` and acts as a handle to the actual loader
+ * running on the worker.
+ */
+class VolumeLoaderContext {
+  activeLoader = undefined;
+  activeLoaderId = -1;
+  constructor(maxCacheSize, maxActiveRequests, maxLowPriorityRequests) {
+    this.workerHandle = new SharedLoadWorkerHandle();
+    this.openPromise = this.workerHandle.sendMessage(WorkerMsgType.INIT, {
+      maxCacheSize,
+      maxActiveRequests,
+      maxLowPriorityRequests
+    });
+  }
+
+  /** Returns a `Promise` that resolves when the worker is ready. `await` it before trying to create a loader. */
+  onOpen() {
+    if (!this.workerHandle.isOpen) {
+      return Promise.reject("Worker is closed");
+    }
+    return this.openPromise;
+  }
+
+  /** Close this context, its worker, and any active loaders. */
+  close() {
+    this.workerHandle.close();
+    this.activeLoader?.close();
+  }
+
+  /**
+   * Create a new loader within this context. This loader will share the context's `VolumeCache` and `RequestQueue`.
+   *
+   * This works just like `createVolumeLoader`. A file format may be provided, or it may be inferred from the URL.
+   */
+  async createLoader(path, options) {
+    // Special case: TIFF loader doesn't work on a worker, has its own workers anyways, and doesn't use cache or queue.
+    const pathString = Array.isArray(path) ? path[0] : path;
+    const fileType = options?.fileType || pathToFileType(pathString);
+    if (fileType === VolumeFileFormat.TIFF) {
+      return new TiffLoader(pathString);
+    } else if (fileType === VolumeFileFormat.DATA) {
+      if (!options?.rawArrayOptions) {
+        throw new Error("Failed to create loader: Must provide RawArrayOptions for RawArrayLoader");
+      }
+      return new RawArrayLoader(options.rawArrayOptions.data, options.rawArrayOptions.metadata);
+    }
+    const success = await this.workerHandle.sendMessage(WorkerMsgType.CREATE_LOADER, {
+      path,
+      options
+    });
+    if (!success) {
+      throw new Error("Failed to create loader");
+    }
+    this.activeLoader?.close();
+    this.activeLoaderId += 1;
+    this.activeLoader = new WorkerLoader(this.activeLoaderId, this.workerHandle);
+    return this.activeLoader;
+  }
+  setThrottleChannelData(throttle) {
+    this.workerHandle.setThrottleChannelData(throttle);
+  }
+  getActiveLoader() {
+    return this.activeLoader;
+  }
+}
+
+/**
+ * A handle to an instance of `IVolumeLoader` (technically, a `ThreadableVolumeLoader`) running on a WebWorker.
+ *
+ * Created with `VolumeLoaderContext.createLoader`. See its documentation for more.
+ */
+class WorkerLoader extends ThreadableVolumeLoader {
+  isOpen = true;
+  currentLoadId = -1;
+  currentLoadCallback = undefined;
+  currentMetadataUpdateCallback = undefined;
+  constructor(loaderId, workerHandle) {
+    super();
+    this.loaderId = loaderId;
+    this.workerHandle = workerHandle;
+    workerHandle.onChannelData = this.onChannelData.bind(this);
+    workerHandle.onUpdateMetadata = this.onUpdateMetadata.bind(this);
+  }
+  checkIsOpen() {
+    if (!this.isOpen || !this.workerHandle.isOpen) {
+      throw new Error("Tried to use a closed loader");
+    }
+  }
+
+  /** Close and permanently invalidate this loader. */
+  close() {
+    this.isOpen = false;
+  }
+
+  /**
+   * Change which directions to prioritize when prefetching. All chunks will be prefetched in these directions before
+   * any chunks are prefetched in any other directions. Has no effect if this loader doesn't support prefetching.
+   */
+  setPrefetchPriority(directions) {
+    return this.workerHandle.sendMessage(WorkerMsgType.SET_PREFETCH_PRIORITY_DIRECTIONS, directions);
+  }
+  updateFetchOptions(fetchOptions) {
+    return this.workerHandle.sendMessage(WorkerMsgType.UPDATE_FETCH_OPTIONS, fetchOptions);
+  }
+  syncMultichannelLoading(sync) {
+    return this.workerHandle.sendMessage(WorkerMsgType.SYNCHRONIZE_MULTICHANNEL_LOADING, sync);
+  }
+  loadDims(loadSpec) {
+    this.checkIsOpen();
+    return this.workerHandle.sendMessage(WorkerMsgType.LOAD_DIMS, loadSpec);
+  }
+  async createImageInfo(loadSpec) {
+    this.checkIsOpen();
+    const {
+      imageInfo,
+      loadSpec: adjustedLoadSpec
+    } = await this.workerHandle.sendMessage(WorkerMsgType.CREATE_VOLUME, loadSpec);
+    return {
+      imageInfo,
+      loadSpec: rebuildLoadSpec(adjustedLoadSpec)
+    };
+  }
+  loadRawChannelData(imageInfo, loadSpec, onUpdateMetadata, onData) {
+    this.checkIsOpen();
+    this.currentLoadCallback = onData;
+    this.currentMetadataUpdateCallback = onUpdateMetadata;
+    this.currentLoadId += 1;
+    return this.workerHandle.sendMessage(WorkerMsgType.LOAD_VOLUME_DATA, {
+      imageInfo,
+      loadSpec,
+      loaderId: this.loaderId,
+      loadId: this.currentLoadId
+    });
+  }
+  onChannelData(e) {
+    if (e.loaderId !== this.loaderId || e.loadId !== this.currentLoadId) {
+      return;
+    }
+    this.currentLoadCallback?.(e.channelIndex, e.dtype, e.data, e.ranges, e.atlasDims);
+  }
+  onUpdateMetadata(e) {
+    if (e.loaderId !== this.loaderId || e.loadId !== this.currentLoadId) {
+      return;
+    }
+    const imageInfo = e.imageInfo;
+    const loadSpec = e.loadSpec && rebuildLoadSpec(e.loadSpec);
+    this.currentMetadataUpdateCallback?.(imageInfo, loadSpec);
+  }
+}
+export default VolumeLoaderContext;

package/es/workers/types.js

@@ -0,0 +1,41 @@
+/** The types of requests that can be made to the worker. Mostly corresponds to methods on `IVolumeLoader`. */
+export let WorkerMsgType = /*#__PURE__*/function (WorkerMsgType) {
+  WorkerMsgType[WorkerMsgType["INIT"] = 0] = "INIT";
+  WorkerMsgType[WorkerMsgType["CREATE_LOADER"] = 1] = "CREATE_LOADER";
+  WorkerMsgType[WorkerMsgType["CREATE_VOLUME"] = 2] = "CREATE_VOLUME";
+  WorkerMsgType[WorkerMsgType["LOAD_DIMS"] = 3] = "LOAD_DIMS";
+  WorkerMsgType[WorkerMsgType["LOAD_VOLUME_DATA"] = 4] = "LOAD_VOLUME_DATA";
+  WorkerMsgType[WorkerMsgType["SET_PREFETCH_PRIORITY_DIRECTIONS"] = 5] = "SET_PREFETCH_PRIORITY_DIRECTIONS";
+  WorkerMsgType[WorkerMsgType["SYNCHRONIZE_MULTICHANNEL_LOADING"] = 6] = "SYNCHRONIZE_MULTICHANNEL_LOADING";
+  WorkerMsgType[WorkerMsgType["UPDATE_FETCH_OPTIONS"] = 7] = "UPDATE_FETCH_OPTIONS";
+  return WorkerMsgType;
+}({});
+
+/** The kind of response a worker can return - `SUCCESS`, `ERROR`, or `EVENT`. */
+export let WorkerResponseResult = /*#__PURE__*/function (WorkerResponseResult) {
+  WorkerResponseResult[WorkerResponseResult["SUCCESS"] = 0] = "SUCCESS";
+  WorkerResponseResult[WorkerResponseResult["ERROR"] = 1] = "ERROR";
+  WorkerResponseResult[WorkerResponseResult["EVENT"] = 2] = "EVENT";
+  return WorkerResponseResult;
+}({});
+
+/** The kind of events that can occur when loading */
+export let WorkerEventType = /*#__PURE__*/function (WorkerEventType) {
+  WorkerEventType[WorkerEventType["METADATA_UPDATE"] = 0] = "METADATA_UPDATE";
+  WorkerEventType[WorkerEventType["CHANNEL_LOAD"] = 1] = "CHANNEL_LOAD";
+  return WorkerEventType;
+}({});
+
+/** All messages to/from a worker carry a `msgId`, a `type`, and a `payload` (whose type is determined by `type`). */
+
+/** Maps each `WorkerMsgType` to the type of the payload of requests of that type. */
+
+/** Maps each `WorkerMsgType` to the type of the payload of responses of that type. */
+
+/** Event for when a batch of channel data loads. */
+
+/** Event for when metadata updates. */
+
+/** All valid types of worker requests, with some `WorkerMsgType` and a matching payload type. */
+
+/** All valid types of worker responses: `SUCCESS` with a matching payload, `ERROR` with a message, or an `EVENT`. */

package/es/workers/util.js

@@ -0,0 +1,8 @@
+import { Box3, Vector3 } from "three";
+/** Recreates a `LoadSpec` that has just been sent to/from a worker to restore three.js object prototypes */
+export function rebuildLoadSpec(spec) {
+  return {
+    ...spec,
+    subregion: new Box3(new Vector3().copy(spec.subregion.min), new Vector3().copy(spec.subregion.max))
+  };
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@aics/vole-core",
+  "version": "3.12.4",
+  "description": "volume renderer for 3d, 4d, or 5d imaging data with OME-Zarr support",
+  "main": "es/index.js",
+  "type": "module",
+  "module": "es/index.js",
+  "types": "es/types/index.d.ts",
+  "files": [
+    "es",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build-docs": "node node_modules/documentation/bin/documentation.js build src/Histogram.ts src/View3d.ts src/Volume.ts src/VolumeMaker.ts src/VolumeLoader.ts -f html -o docs --shallow",
+    "build": "npm run transpileES && npm run build-types",
+    "build-types": "tsc -p tsconfig.types.json",
+    "build-demo": "webpack --config webpack.demo.js",
+    "clean": "rimraf es/",
+    "format": "prettier --write src/**/*.js",
+    "gh-build": "webpack --config webpack.dev.js",
+    "dev": "webpack serve --config webpack.dev.js",
+    "start": "webpack serve --config webpack.dev.js",
+    "lint": "eslint --config ./.eslintrc.json --ignore-path ./.eslintignore --ext .js --ext .ts ./src",
+    "test": "cross-env NODE_OPTIONS=\"--loader ts-node/esm\" mocha --require ts-node/register --es-module-specifier-resolution=node src/**/test/*.[jt]s",
+    "transpileES": "babel src --out-dir es --extensions .js,.ts --ignore **/*.test.js",
+    "typeCheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "author": "Daniel Toloudis",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.25.6",
+    "geotiff": "^2.0.5",
+    "serialize-error": "^11.0.3",
+    "three": "^0.171.0",
+    "throttled-queue": "^2.1.4",
+    "tweakpane": "^3.1.9",
+    "zarrita": "^0.3.2"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.25.6",
+    "@babel/core": "^7.25.2",
+    "@babel/plugin-transform-runtime": "^7.25.4",
+    "@babel/preset-typescript": "^7.24.7",
+    "@babel/register": "^7.24.6",
+    "@tweakpane/core": "^1.1.9",
+    "@types/chai": "^4.3.12",
+    "@types/mocha": "^9.1.1",
+    "@types/three": "^0.144.0",
+    "@typescript-eslint/eslint-plugin": "^5.30.5",
+    "@typescript-eslint/parser": "^5.30.5",
+    "acorn": "^8.7.0",
+    "babel-loader": "^8.2.2",
+    "babel-plugin-inline-import": "^3.0.0",
+    "babel-plugin-inline-import-data-uri": "^1.0.1",
+    "chai": "^5.1.0",
+    "clean-webpack-plugin": "^4.0.0-alpha.0",
+    "copy-webpack-plugin": "^9.0.1",
+    "cross-env": "^7.0.3",
+    "documentation": "^14.0.0",
+    "eslint": "^8.19.0",
+    "eslint-config-prettier": "^8.5.0",
+    "file-loader": "^6.2.0",
+    "html-webpack-plugin": "^5.3.2",
+    "husky": "^7.0.1",
+    "lil-gui": "^0.19.2",
+    "lint-staged": "^13.2.1",
+    "mocha": "^10.3.0",
+    "prettier": "^2.3.2",
+    "raw-loader": "^4.0.2",
+    "rimraf": "^3.0.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^4.3.5",
+    "url-loader": "^4.1.1",
+    "webpack": "^5.69.1",
+    "webpack-cli": "^4.9.2",
+    "webpack-dev-server": "^4.7.4"
+  }
+}