@aics/vole-core 3.12.4

package/es/types/constants/volumeSliceShader.d.ts

@@ -0,0 +1,109 @@
+import { Vector2, Vector3, Matrix4, Texture } from "three";
+export declare const sliceVertexShaderSrc: string;
+export declare const sliceFragmentShaderSrc: string;
+export declare const sliceShaderUniforms: () => {
+    iResolution: {
+        type: string;
+        value: Vector2;
+    };
+    CLIP_NEAR: {
+        type: string;
+        value: number;
+    };
+    CLIP_FAR: {
+        type: string;
+        value: number;
+    };
+    maskAlpha: {
+        type: string;
+        value: number;
+    };
+    BRIGHTNESS: {
+        type: string;
+        value: number;
+    };
+    DENSITY: {
+        type: string;
+        value: number;
+    };
+    GAMMA_MIN: {
+        type: string;
+        value: number;
+    };
+    GAMMA_MAX: {
+        type: string;
+        value: number;
+    };
+    GAMMA_SCALE: {
+        type: string;
+        value: number;
+    };
+    BREAK_STEPS: {
+        type: string;
+        value: number;
+    };
+    ATLAS_DIMS: {
+        type: string;
+        value: Vector2;
+    };
+    Z_SLICE: {
+        type: string;
+        value: number;
+    };
+    SLICES: {
+        type: string;
+        value: number;
+    };
+    isOrtho: {
+        type: string;
+        value: number;
+    };
+    orthoThickness: {
+        type: string;
+        value: number;
+    };
+    orthoScale: {
+        type: string;
+        value: number;
+    };
+    AABB_CLIP_MIN: {
+        type: string;
+        value: Vector3;
+    };
+    AABB_CLIP_MAX: {
+        type: string;
+        value: Vector3;
+    };
+    inverseModelViewMatrix: {
+        type: string;
+        value: Matrix4;
+    };
+    textureAtlas: {
+        type: string;
+        value: Texture;
+    };
+    textureAtlasMask: {
+        type: string;
+        value: Texture;
+    };
+    maxProject: {
+        type: string;
+        value: number;
+    };
+    interpolationEnabled: {
+        type: string;
+        value: boolean;
+    };
+    flipVolume: {
+        type: string;
+        value: Vector3;
+    };
+    volumeScale: {
+        type: string;
+        value: Vector3;
+    };
+    textureRes: {
+        type: string;
+        value: Vector2;
+    };
+};

package/es/types/index.d.ts

@@ -0,0 +1,28 @@
+import { RENDERMODE_PATHTRACE, RENDERMODE_RAYMARCH, View3d } from "./View3d.js";
+import Volume from "./Volume.js";
+import VolumeDrawable from "./VolumeDrawable.js";
+import Channel from "./Channel.js";
+import VolumeMaker from "./VolumeMaker.js";
+import VolumeCache from "./VolumeCache.js";
+import RequestQueue from "./utils/RequestQueue.js";
+import SubscribableRequestQueue from "./utils/SubscribableRequestQueue.js";
+import Histogram from "./Histogram.js";
+import { Lut, remapControlPoints } from "./Lut.js";
+import { ViewportCorner } from "./types.js";
+import { VolumeFileFormat, createVolumeLoader, PrefetchDirection } from "./loaders/index.js";
+import { LoadSpec } from "./loaders/IVolumeLoader.js";
+import { OMEZarrLoader } from "./loaders/OmeZarrLoader.js";
+import { JsonImageInfoLoader } from "./loaders/JsonImageInfoLoader.js";
+import { RawArrayLoader, type RawArrayData, type RawArrayInfo, type RawArrayLoaderOptions } from "./loaders/RawArrayLoader.js";
+import { TiffLoader } from "./loaders/TiffLoader.js";
+import VolumeLoaderContext from "./workers/VolumeLoaderContext.js";
+import { VolumeLoadError, VolumeLoadErrorType } from "./loaders/VolumeLoadError.js";
+import { type CameraState } from "./ThreeJsPanel.js";
+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 { 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, };

package/es/types/loaders/IVolumeLoader.d.ts

@@ -0,0 +1,113 @@
+import { Box3 } from "three";
+import Volume from "../Volume.js";
+import type { VolumeDims } from "../VolumeDims.js";
+import { type ImageInfo } from "../ImageInfo.js";
+import { TypedArray, NumberType } from "../types.js";
+import { PrefetchDirection } from "./zarr_utils/types.js";
+import { ZarrLoaderFetchOptions } from "./OmeZarrLoader.js";
+export declare class LoadSpec {
+    time: number;
+    /** The max size of a volume atlas that may be produced by a load. Used to pick the appropriate multiscale level. */
+    maxAtlasEdge?: number;
+    /** An optional bias added to the scale level index after the optimal level is picked based on `maxAtlasEdge`. */
+    scaleLevelBias?: number;
+    /**
+     * The max scale level to load. Even when this is specified, the loader may pick a *lower* scale level based on
+     * limits imposed by `scaleLevelBias` and `maxAtlasEdge` (or their defaults if unspecified).
+     */
+    multiscaleLevel?: number;
+    /** Subregion of volume to load. If not specified, the entire volume is loaded. Specify as floats between 0-1. */
+    subregion: Box3;
+    channels?: number[];
+    /** Treat multiscaleLevel literally and don't use other constraints to change it.
+     * By default we will try to load the best level based on the maxAtlasEdge and scaleLevelBias,
+     * so this is false.
+     */
+    useExplicitLevel: boolean;
+}
+export declare function loadSpecToString(spec: LoadSpec): string;
+export type LoadedVolumeInfo = {
+    imageInfo: ImageInfo;
+    loadSpec: LoadSpec;
+};
+/**
+ * @callback PerChannelCallback
+ * @param {string} imageurl
+ * @param {Volume} volume
+ * @param {number} channelindex
+ */
+export type PerChannelCallback = (volume: Volume, channelIndex: number) => void;
+/**
+ * @callback RawChannelDataCallback - allow lists of channel indices and data arrays to be passed to the callback
+ * @param {number[]} channelIndex - The indices of the channels that were loaded
+ * @param {NumberType[]} dtype - The data type of the data arrays
+ * @param {TypedArray<NumberType>[]} data - The raw data for each channel
+ * @param {[number, number][]} ranges - The min and max values for each channel in their original range
+ * @param {[number, number]} atlasDims - The dimensions of the atlas, if the data is in an atlas format
+ */
+export type RawChannelDataCallback = (channelIndex: number[], dtype: NumberType[], data: TypedArray<NumberType>[], ranges: [number, number][], atlasDims?: [number, number]) => void;
+/**
+ * Loads volume data from a source specified by a `LoadSpec`.
+ *
+ * Loaders may keep state for reuse between volume creation and volume loading, and should be kept alive until volume
+ * loading is complete. (See `createVolume`)
+ */
+export interface IVolumeLoader {
+    /** Use VolumeDims to further refine a `LoadSpec` for use in `createVolume` */
+    loadDims(loadSpec: LoadSpec): Promise<VolumeDims[]>;
+    /**
+     * Create an empty `Volume` from a `LoadSpec`, which must be passed to `loadVolumeData` to begin loading.
+     * Optionally pass a callback to respond whenever new channel data is loaded into the volume.
+     */
+    createVolume(loadSpec: LoadSpec, onChannelLoaded?: PerChannelCallback): Promise<Volume>;
+    /**
+     * Begin loading a volume's data, as specified in its `LoadSpec`.
+     *
+     * Pass a callback to respond when this request loads a new channel. This callback will execute after the one
+     * assigned in `createVolume`, if any.
+     *
+     * The returned `Promise` resolves once all channels load, or rejects with any error that occurs during loading.
+     */
+    loadVolumeData(volume: Volume, loadSpec?: LoadSpec, onChannelLoaded?: PerChannelCallback): Promise<void>;
+    /** Change which directions to prioritize when prefetching. Currently only implemented on `OMEZarrLoader`. */
+    setPrefetchPriority(directions: PrefetchDirection[]): void;
+    /**
+     * By default channel data can arrive out of order and at different times.
+     * This can cause the rendering to update in a way that is not visually appealing.
+     * In particular, during time series playback or Z slice playback, we would like
+     * to see all channels update at the same time.
+     * @param sync Set true to force all requested channels to load at the same time
+     */
+    syncMultichannelLoading(sync: boolean): void;
+}
+/** Abstract class which allows loaders to accept and return types that are easier to transfer to/from a worker. */
+export declare abstract class ThreadableVolumeLoader implements IVolumeLoader {
+    /** Unchanged from `IVolumeLoader`. See that interface for details. */
+    abstract loadDims(loadSpec: LoadSpec): Promise<VolumeDims[]>;
+    /**
+     * Creates an `ImageInfo` object from a `LoadSpec`, which may be passed to the `Volume` constructor to create an
+     * empty volume that can accept data loaded with the given `LoadSpec`.
+     *
+     * Also returns a new `LoadSpec` that may have been modified from the input `LoadSpec` to reflect the constraints or
+     * abilities of the loader. This new `LoadSpec` should be used when constructing the `Volume`, _not_ the original.
+     */
+    abstract createImageInfo(loadSpec: LoadSpec): Promise<LoadedVolumeInfo>;
+    /**
+     * Begins loading per-channel data for the volume specified by `imageInfo` and `loadSpec`.
+     *
+     * This function accepts two required callbacks. The first, `onUpdateVolumeMetadata`, should be called at most once
+     * to modify the `Volume`'s `imageInfo` and/or `loadSpec` properties based on changes made by this load. Actual
+     * loaded channel data is passed to `onData` as it is loaded.
+     *
+     * Depending on the loader, the array passed to `onData` may be in simple 3d dimension order or reflect a 2d atlas.
+     * If the latter, the dimensions of the atlas are passed as the third argument to `onData`.
+     *
+     * The returned promise should resolve when all data has been loaded, or reject if any error occurs while loading.
+     */
+    abstract loadRawChannelData(imageInfo: ImageInfo, loadSpec: LoadSpec, onUpdateVolumeMetadata: (imageInfo?: ImageInfo, loadSpec?: LoadSpec) => void, onData: RawChannelDataCallback): Promise<void>;
+    setPrefetchPriority(_directions: PrefetchDirection[]): void;
+    syncMultichannelLoading(_sync: boolean): void;
+    updateFetchOptions(_options: Partial<ZarrLoaderFetchOptions>): void;
+    createVolume(loadSpec: LoadSpec, onChannelLoaded?: PerChannelCallback): Promise<Volume>;
+    loadVolumeData(volume: Volume, loadSpecOverride?: LoadSpec, onChannelLoaded?: PerChannelCallback): Promise<void>;
+}

package/es/types/loaders/JsonImageInfoLoader.d.ts

@@ -0,0 +1,80 @@
+import { ThreadableVolumeLoader, type LoadSpec, type RawChannelDataCallback, type LoadedVolumeInfo } from "./IVolumeLoader.js";
+import { type ImageInfo } from "../ImageInfo.js";
+import type { VolumeDims } from "../VolumeDims.js";
+import VolumeCache from "../VolumeCache.js";
+interface PackedChannelsImage {
+    name: string;
+    channels: number[];
+}
+type JsonImageInfo = {
+    name: string;
+    version?: string;
+    images: PackedChannelsImage[];
+    /** X size of the *original* (not downsampled) volume, in pixels */
+    width: number;
+    /** Y size of the *original* (not downsampled) volume, in pixels */
+    height: number;
+    /** Number of rows of z-slice tiles (not pixels) in the texture atlas */
+    rows: number;
+    /** Number of columns of z-slice tiles (not pixels) in the texture atlas */
+    cols: number;
+    /** Width of a single atlas tile in pixels */
+    tile_width: number;
+    /** Height of a single atlas tile in pixels */
+    tile_height: number;
+    /** Width of the texture atlas in pixels; equivalent to `tile_width * cols` */
+    atlas_width: number;
+    /** Height of the texture atlas in pixels; equivalent to `tile_height * rows` */
+    atlas_height: number;
+    /** Number of tiles in the texture atlas (or number of z-slices in the volume segment) */
+    tiles: number;
+    /** Physical x size of a single *original* (not downsampled) pixel */
+    pixel_size_x: number;
+    /** Physical y size of a single *original* (not downsampled) pixel */
+    pixel_size_y: number;
+    /** Physical z size of a single pixel */
+    pixel_size_z: number;
+    /** Symbol of physical unit used by `pixel_size_(x|y|z)` fields */
+    pixel_size_unit?: string;
+    channels: number;
+    channel_names: string[];
+    channel_colors?: [number, number, number][];
+    times?: number;
+    time_scale?: number;
+    time_unit?: string;
+    transform: {
+        translation: [number, number, number];
+        rotation: [number, number, number];
+    };
+    userData?: Record<string, unknown>;
+};
+declare class JsonImageInfoLoader extends ThreadableVolumeLoader {
+    urls: string[];
+    jsonInfo: (JsonImageInfo | undefined)[];
+    syncChannels: boolean;
+    cache?: VolumeCache;
+    constructor(urls: string | string[], cache?: VolumeCache);
+    private getJsonImageInfo;
+    syncMultichannelLoading(sync: boolean): void;
+    loadDims(loadSpec: LoadSpec): Promise<VolumeDims[]>;
+    createImageInfo(loadSpec: LoadSpec): Promise<LoadedVolumeInfo>;
+    loadRawChannelData(imageInfo: ImageInfo, loadSpec: LoadSpec, onUpdateMetadata: (imageInfo: undefined, loadSpec?: LoadSpec) => void, onData: RawChannelDataCallback): Promise<void>;
+    /**
+     * load per-channel volume data from a batch of image files containing the volume slices tiled across the images
+     * @param {Array.<{name:string, channels:Array.<number>}>} imageArray
+     * @param {RawChannelDataCallback} onData Per-channel callback. Called when each channel's atlased volume data is loaded
+     * @param {VolumeCache} cache
+     * @example loadVolumeAtlasData([{
+     *     "name": "AICS-10_5_5.ome.tif_atlas_0.png",
+     *     "channels": [0, 1, 2]
+     * }, {
+     *     "name": "AICS-10_5_5.ome.tif_atlas_1.png",
+     *     "channels": [3, 4, 5]
+     * }, {
+     *     "name": "AICS-10_5_5.ome.tif_atlas_2.png",
+     *     "channels": [6, 7, 8]
+     * }], mycallback);
+     */
+    static loadVolumeAtlasData(imageArray: PackedChannelsImage[], onData: RawChannelDataCallback, cache?: VolumeCache, syncChannels?: boolean): Promise<void>;
+}
+export { JsonImageInfoLoader };

package/es/types/loaders/OmeZarrLoader.d.ts

@@ -0,0 +1,87 @@
+import type { ImageInfo } from "../ImageInfo.js";
+import type { VolumeDims } from "../VolumeDims.js";
+import VolumeCache from "../VolumeCache.js";
+import SubscribableRequestQueue from "../utils/SubscribableRequestQueue.js";
+import { ThreadableVolumeLoader, LoadSpec, type RawChannelDataCallback, type LoadedVolumeInfo } from "./IVolumeLoader.js";
+import type { PrefetchDirection } from "./zarr_utils/types.js";
+export type ZarrLoaderFetchOptions = {
+    /** The max. number of requests the loader can issue at a time. Ignored if the constructor also receives a queue. */
+    concurrencyLimit?: number;
+    /**
+     * The max. number of *prefetch* requests the loader can issue at a time. Set lower than `concurrencyLimit` to ensure
+     * that prefetching leaves room in the queue for actual loads. Ignored if the constructor also receives a queue.
+     */
+    prefetchConcurrencyLimit?: number;
+    /**
+     * The max. number of chunks to prefetch outward in either direction. E.g. if a load requests chunks with z coords 3
+     * and 4 and `maxPrefetchDistance` in z is 2, the loader will prefetch similar chunks with z coords 1, 2, 5, and 6
+     * (or until it hits `maxPrefetchChunks`). Ordered TZYX.
+     */
+    maxPrefetchDistance: [number, number, number, number];
+    /** The max. number of total chunks that can be prefetched after any load. */
+    maxPrefetchChunks: number;
+    /** The initial directions to prioritize when prefetching */
+    priorityDirections?: PrefetchDirection[];
+    /** only use priority directions */
+    onlyPriorityDirections?: boolean;
+};
+declare class OMEZarrLoader extends ThreadableVolumeLoader {
+    /**
+     * 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.
+     */
+    private sources;
+    /** Handle to a `SubscribableRequestQueue` for smart concurrency management and request cancelling/reissuing. */
+    private requestQueue;
+    /** Options to configure (pre)fetching behavior. */
+    private fetchOptions;
+    /** Direction(s) to prioritize when prefetching. Stored separate from `fetchOptions` since it may be mutated. */
+    private priorityDirections;
+    /** The ID of the subscriber responsible for "actual loads" (non-prefetch requests) */
+    private loadSubscriber;
+    /** The ID of the subscriber responsible for prefetches, so that requests can be cancelled and reissued */
+    private prefetchSubscriber;
+    private maxExtent?;
+    private syncChannels;
+    private constructor();
+    /**
+     * 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 createLoader(urls: string | string[], scenes?: number | number[], cache?: VolumeCache, queue?: SubscribableRequestQueue, fetchOptions?: ZarrLoaderFetchOptions): Promise<OMEZarrLoader>;
+    private getUnitSymbols;
+    private getLevelShapesZYX;
+    private getScale;
+    private orderByDimension;
+    private orderByTCZYX;
+    /**
+     * 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).
+     */
+    private matchChannelToSource;
+    /**
+     * 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: PrefetchDirection[]): void;
+    syncMultichannelLoading(sync: boolean): void;
+    updateFetchOptions(options: Partial<ZarrLoaderFetchOptions>): void;
+    loadDims(loadSpec: LoadSpec): Promise<VolumeDims[]>;
+    createImageInfo(loadSpec: LoadSpec): Promise<LoadedVolumeInfo>;
+    private prefetchChunk;
+    /** Reads a list of chunk keys requested by a `loadVolumeData` call and sets up appropriate prefetch requests. */
+    private beginPrefetch;
+    private updateImageInfoForLoad;
+    loadRawChannelData(imageInfo: ImageInfo, loadSpec: LoadSpec, onUpdateMetadata: (imageInfo: ImageInfo) => void, onData: RawChannelDataCallback): Promise<void>;
+}
+export { OMEZarrLoader };

package/es/types/loaders/OpenCellLoader.d.ts

@@ -0,0 +1,9 @@
+import { ThreadableVolumeLoader, LoadSpec, RawChannelDataCallback, LoadedVolumeInfo } from "./IVolumeLoader.js";
+import { type ImageInfo } from "../ImageInfo.js";
+import type { VolumeDims } from "../VolumeDims.js";
+declare class OpenCellLoader extends ThreadableVolumeLoader {
+    loadDims(_: LoadSpec): Promise<VolumeDims[]>;
+    createImageInfo(_loadSpec: LoadSpec): Promise<LoadedVolumeInfo>;
+    loadRawChannelData(imageInfo: ImageInfo, _loadSpec: LoadSpec, _onUpdateMetadata: () => void, onData: RawChannelDataCallback): Promise<void>;
+}
+export { OpenCellLoader };

package/es/types/loaders/RawArrayLoader.d.ts

@@ -0,0 +1,33 @@
+import { ThreadableVolumeLoader, type LoadSpec, type RawChannelDataCallback, type LoadedVolumeInfo } from "./IVolumeLoader.js";
+import type { ImageInfo } from "../ImageInfo.js";
+import type { VolumeDims } from "../VolumeDims.js";
+import { Uint8 } from "../types.js";
+export type RawArrayData = {
+    dtype: Uint8;
+    shape: [number, number, number, number];
+    buffer: DataView;
+};
+export type RawArrayInfo = {
+    name: string;
+    sizeX: number;
+    sizeY: number;
+    sizeZ: number;
+    sizeC: number;
+    physicalPixelSize: [number, number, number];
+    spatialUnit: string;
+    channelNames: string[];
+    userData?: Record<string, unknown>;
+};
+export interface RawArrayLoaderOptions {
+    data: RawArrayData;
+    metadata: RawArrayInfo;
+}
+declare class RawArrayLoader extends ThreadableVolumeLoader {
+    data: RawArrayData;
+    jsonInfo: RawArrayInfo;
+    constructor(rawData: RawArrayData, rawDataInfo: RawArrayInfo);
+    loadDims(_loadSpec: LoadSpec): Promise<VolumeDims[]>;
+    createImageInfo(loadSpec: LoadSpec): Promise<LoadedVolumeInfo>;
+    loadRawChannelData(imageInfo: ImageInfo, loadSpec: LoadSpec, onUpdateMetadata: (imageInfo: undefined, loadSpec: LoadSpec) => void, onData: RawChannelDataCallback): Promise<void>;
+}
+export { RawArrayLoader };

package/es/types/loaders/TiffLoader.d.ts

@@ -0,0 +1,45 @@
+import { ThreadableVolumeLoader, LoadSpec, type RawChannelDataCallback, type LoadedVolumeInfo } from "./IVolumeLoader.js";
+import { type ImageInfo } from "../ImageInfo.js";
+import type { VolumeDims } from "../VolumeDims.js";
+import { TypedArray, NumberType } from "../types.js";
+declare class OMEDims {
+    sizex: number;
+    sizey: number;
+    sizez: number;
+    sizec: number;
+    sizet: number;
+    unit: string;
+    pixeltype: string;
+    dimensionorder: string;
+    pixelsizex: number;
+    pixelsizey: number;
+    pixelsizez: number;
+    channelnames: string[];
+}
+export type TiffWorkerParams = {
+    channel: number;
+    tilesizex: number;
+    tilesizey: number;
+    sizec: number;
+    sizez: number;
+    dimensionOrder: string;
+    bytesPerSample: number;
+    url: string;
+};
+export type TiffLoadResult = {
+    isError: false;
+    data: TypedArray<NumberType>;
+    dtype: NumberType;
+    channel: number;
+    range: [number, number];
+};
+declare class TiffLoader extends ThreadableVolumeLoader {
+    url: string;
+    dims?: OMEDims;
+    constructor(url: string);
+    private loadOmeDims;
+    loadDims(_loadSpec: LoadSpec): Promise<VolumeDims[]>;
+    createImageInfo(_loadSpec: LoadSpec): Promise<LoadedVolumeInfo>;
+    loadRawChannelData(imageInfo: ImageInfo, _loadSpec: LoadSpec, _onUpdateMetadata: () => void, onData: RawChannelDataCallback): Promise<void>;
+}
+export { TiffLoader };

package/es/types/loaders/VolumeLoadError.d.ts

@@ -0,0 +1,18 @@
+/** Groups possible load errors into a few broad categories which we can give similar guidance to the user about. */
+export declare const enum VolumeLoadErrorType {
+    UNKNOWN = "unknown",
+    NOT_FOUND = "not_found",
+    TOO_LARGE = "too_large",
+    LOAD_DATA_FAILED = "load_data_failed",
+    INVALID_METADATA = "invalid_metadata",
+    INVALID_MULTI_SOURCE_ZARR = "invalid_multi_source_zarr"
+}
+export declare class VolumeLoadError extends Error {
+    type: VolumeLoadErrorType;
+    constructor(message?: string, options?: {
+        cause?: unknown;
+        type?: VolumeLoadErrorType;
+    });
+}
+/** Curried function to re-throw an error wrapped in a `VolumeLoadError` with the given `message` and `type`. */
+export declare function wrapVolumeLoadError<T>(message?: string, type?: VolumeLoadErrorType, ignore?: unknown): (e: T) => T;

package/es/types/loaders/VolumeLoaderUtils.d.ts

@@ -0,0 +1,38 @@
+import { Box3, Vector2, Vector3 } from "three";
+import { type ImageInfo } from "../ImageInfo.js";
+import { LoadSpec } from "./IVolumeLoader.js";
+export declare const MAX_ATLAS_EDGE = 4096;
+/** Converts a full spatial or temporal unit name supported by OME-Zarr to its unit symbol */
+export declare function unitNameToSymbol(unitName?: string): string | null;
+export declare function computePackedAtlasDims(z: number, tw: number, th: number): Vector2;
+/** Picks the largest scale level that can fit into a texture atlas with edges no longer than `maxAtlasEdge`. */
+export declare function estimateLevelForAtlas(spatialDimsZYX: [number, number, number][], maxAtlasEdge?: number): number | undefined;
+type ZYX = [number, number, number];
+export declare function scaleDimsToSubregion(subregion: Box3, dims: ZYX): ZYX;
+export declare function scaleMultipleDimsToSubregion(subregion: Box3, dims: ZYX[]): ZYX[];
+/**
+ * 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 declare function pickLevelToLoadUnscaled(loadSpec: LoadSpec, spatialDimsZYX: ZYX[]): number;
+/**
+ * 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 declare function pickLevelToLoad(loadSpec: LoadSpec, spatialDimsZYX: ZYX[]): number;
+/** Given the size of a volume in pixels, convert a `Box3` in the 0-1 range to pixels */
+export declare function convertSubregionToPixels(region: Box3, size: Vector3): Box3;
+/**
+ * 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 declare function composeSubregion(region: Box3, container: Box3): Box3;
+export declare function buildDefaultMetadata(rawImageInfo: ImageInfo): Record<string, unknown>;
+export {};

package/es/types/loaders/index.d.ts

@@ -0,0 +1,22 @@
+import { ThreadableVolumeLoader } from "./IVolumeLoader.js";
+import { type ZarrLoaderFetchOptions } from "./OmeZarrLoader.js";
+import { RawArrayLoaderOptions } from "./RawArrayLoader.js";
+import VolumeCache from "../VolumeCache.js";
+import SubscribableRequestQueue from "../utils/SubscribableRequestQueue.js";
+export { PrefetchDirection } from "./zarr_utils/types.js";
+export declare const enum VolumeFileFormat {
+    ZARR = "zarr",
+    JSON = "json",
+    TIFF = "tiff",
+    DATA = "data"
+}
+export type CreateLoaderOptions = {
+    fileType?: VolumeFileFormat;
+    cache?: VolumeCache;
+    queue?: SubscribableRequestQueue;
+    scene?: number;
+    fetchOptions?: ZarrLoaderFetchOptions;
+    rawArrayOptions?: RawArrayLoaderOptions;
+};
+export declare function pathToFileType(path: string): VolumeFileFormat;
+export declare function createVolumeLoader(path: string | string[], options?: CreateLoaderOptions): Promise<ThreadableVolumeLoader>;

package/es/types/loaders/zarr_utils/ChunkPrefetchIterator.d.ts

@@ -0,0 +1,22 @@
+import { PrefetchDirection, TCZYX } from "./types";
+type TZYX = [number, number, number, number];
+type PrefetchDirectionState = {
+    direction: PrefetchDirection;
+    chunks: TCZYX<number>[];
+    start: number;
+    /** May be either a number for all channels or an array of ends per-channels */
+    end: number | number[];
+};
+/**
+ * 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.
+ */
+export default class ChunkPrefetchIterator {
+    directionStates: PrefetchDirectionState[];
+    priorityDirectionStates: PrefetchDirectionState[];
+    constructor(chunks: TCZYX<number>[], tzyxMaxPrefetchOffset: TZYX, tczyxChunksPerSource: TCZYX<number>[], priorityDirections?: PrefetchDirection[], onlyPriorityDirections?: boolean);
+    private static iterateDirections;
+    [Symbol.iterator](): Iterator<TCZYX<number>>;
+}
+export {};

package/es/types/loaders/zarr_utils/WrappedStore.d.ts

@@ -0,0 +1,24 @@
+import { AbsolutePath, AsyncMutable, Readable } from "@zarrita/storage";
+import SubscribableRequestQueue from "../../utils/SubscribableRequestQueue";
+import VolumeCache from "../../VolumeCache";
+import { SubscriberId } from "./types";
+type WrappedStoreOpts<Opts> = {
+    options?: Opts;
+    subscriber: SubscriberId;
+    reportKey?: (key: string, subscriber: SubscriberId) => void;
+    isPrefetch?: boolean;
+};
+/**
+ * `Readable` is zarrita's minimal abstraction for any source of data.
+ * `WrappedStore` wraps another `Readable` and adds (optional) connections to `VolumeCache` and `RequestQueue`.
+ */
+declare class WrappedStore<Opts, S extends Readable<Opts> = Readable<Opts>> implements AsyncMutable<WrappedStoreOpts<Opts>> {
+    private baseStore;
+    private cache?;
+    private queue?;
+    constructor(baseStore: S, cache?: VolumeCache | undefined, queue?: SubscribableRequestQueue | undefined);
+    set(_key: AbsolutePath, _value: Uint8Array): Promise<void>;
+    private getAndCache;
+    get(key: AbsolutePath, opts?: WrappedStoreOpts<Opts> | undefined): Promise<Uint8Array | undefined>;
+}
+export default WrappedStore;