omezarr-tilesource 0.5.0 → 0.6.0

package/README.md

@@ -38,33 +38,42 @@ import { OMEZarrTileSource } from "omezarr-tilesource";
 
 const url = ...;
 
-// configuration with URL (only works with zipped OME-Zarr URLs ending with .ozx)
+// register the tile source and its data type converters with OpenSeadragon
+// (required for inline configurations and URLs, see "Data pipeline" below)
+OMEZarrTileSource.enable(OpenSeadragon);
+
+// configuration with URL (only works with zipped OME-Zarr URLs, path ending in .ozx)
 const tileSource1 = url;
 
-// inline configuration with options object (requires prior enabling, see below)
-OMEZarrTileSource.enable(OpenSeadragon);
+// inline configuration with options object
 const tileSource2 = {
     type: "ome-zarr",
     url: url,
-    // zip: undefined,  // undefined = OME-Zarr ZIP auto-detection based on .ozx suffix
-    // c: undefined,  // undefined = composite of all active channels (requires dataType "context2d")
-    // z: undefined,  // undefined = omero rdefs default (middle z-slice if missing)
+    // zip: undefined,  // undefined = OME-Zarr ZIP auto-detection based on .ozx path suffix
     // t: undefined,  // undefined = omero rdefs default (middle timepoint if missing)
-    // dataType: undefined,  // "context2d" (default, rendered tiles) or "ome-zarr" (raw single-channel chunks)
+    // z: undefined,  // undefined = omero rdefs default (middle z-slice if missing)
+    // c: undefined,  // channel index or array of indices; undefined = all active channels
+    // range: undefined,  // contrast limits [min, max] or array thereof; undefined = omero windows
+    // color: undefined,  // RGB color or array of colors; undefined = omero channel colors
+    // lutOrColorMap: undefined,  // LUT/color map or array thereof; undefined = omero LUTs
+    // inverted: undefined,  // boolean or array of booleans; undefined = omero inversion
     // autoBoost: undefined  // boost brightness of dark tiles (default false)
 };
 
 // direct instantiation with URL (works with any OME-Zarr storage backend)
 const tileSource3 = new OMEZarrTileSource(url);
 
-// direct instantiation with options object (no prior enabling required)
+// direct instantiation with options object
 const tileSource4 = new OMEZarrTileSource({
     url: url,
-    // zip: undefined,  // undefined = OME-Zarr ZIP auto-detection based on .ozx suffix
-    // c: undefined,  // undefined = composite of all active channels (requires dataType "context2d")
-    // z: undefined,  // undefined = omero rdefs default (middle z-slice if missing)
+    // zip: undefined,  // undefined = OME-Zarr ZIP auto-detection based on .ozx path suffix
     // t: undefined,  // undefined = omero rdefs default (middle timepoint if missing)
-    // dataType: undefined,  // "context2d" (default, rendered tiles) or "ome-zarr" (raw single-channel chunks)
+    // z: undefined,  // undefined = omero rdefs default (middle z-slice if missing)
+    // c: undefined,  // channel index or array of indices; undefined = all active channels
+    // range: undefined,  // contrast limits [min, max] or array thereof; undefined = omero windows
+    // color: undefined,  // RGB color or array of colors; undefined = omero channel colors
+    // lutOrColorMap: undefined,  // LUT/color map or array thereof; undefined = omero LUTs
+    // inverted: undefined,  // boolean or array of booleans; undefined = omero inversion
     // autoBoost: undefined  // boost brightness of dark tiles (default false)
 });
 
@@ -79,81 +88,185 @@ const viewer = OpenSeadragon({
 });
 ```
 
+### Options
+
+| Option          | Type                                                    | Default                                                                        | Description                                                                                                                                                                             |
+| --------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`           | `string \| URL`                                         | (required)                                                                     | URL of the OME-Zarr image (group) or of a zipped OME-Zarr file, relative to the document base URL                                                                                       |
+| `zip`           | `boolean`                                               | `true` if the `url` path ends with `.ozx`                                      | Whether `url` points to a zipped OME-Zarr file                                                                                                                                          |
+| `t`             | `number`                                                | omero `rdefs.defaultT`, else middle plane                                      | Timepoint index (0-based)                                                                                                                                                               |
+| `z`             | `number`                                                | omero `rdefs.defaultZ`, else middle plane                                      | Z-slice index (0-based)                                                                                                                                                                 |
+| `c`             | `number \| number[]`                                    | all channels marked active in omero                                            | Channel index or indices (0-based) to render, composited in the given order. Arrays must be non-empty                                                                                   |
+| `range`         | `[number, number] \| ([number, number] \| undefined)[]` | omero channel windows (`window.start`, `window.end`), else the data type range | Contrast limits (`[min, max]`) to render the channels with. Ignored for channels rendered with a color map                                                                              |
+| `color`         | `Color \| (Color \| undefined)[]`                       | colors of the rendered omero channels, else white                              | RGB color or colors (`[r, g, b]`, 0-255) to render the channels with. Ignored for channels rendered with a LUT or color map                                                             |
+| `lutOrColorMap` | `LUTOrColorMap \| (LUTOrColorMap \| undefined)[]`       | omero channel LUTs and color maps, else none                                   | Color LUT (a color per scaled value) or color map (a color per raw value, `Map`) to render the channels with; colors may carry alpha. A color map also overrides `range` and `inverted` |
+| `inverted`      | `boolean \| (boolean \| undefined)[]`                   | omero channel inversion, else `false`                                          | Whether to invert the channels. Ignored for channels rendered with a color map                                                                                                          |
+| `autoBoost`     | `boolean`                                               | `false`                                                                        | Boost the brightness of dark tiles (ome-zarr.js `renderChunks` option)                                                                                                                  |
+
+`range`, `color`, `lutOrColorMap` and `inverted` take a single value, which
+applies to all rendered channels, or one entry per rendered channel. An
+`undefined` entry falls back to the omero metadata of that channel, as does the
+option as a whole. The `ranges`, `colors`, `lutsOrColorMaps` and `inverteds`
+getters return the resolved per-channel arrays.
+
+`t`, `z` and `c` are validated against the image shape when the OME-Zarr
+metadata is loaded; invalid indices fail with `open-failed`. Images without
+`c` fail if the omero metadata marks no channel as active. An invalid `c`,
+`url` or rendering setting is rejected by the constructor, which throws
+synchronously before any request is made; the length of a rendering setting
+array is only checked against `c` if that is configured too.
+
+`url` is resolved against the document base URL when the tile source is
+created; the resolved absolute URL is available as `tileSource.url` (always a
+string) and is used for loading, for the tile cache keys and for comparing tile
+sources.
+
 ### Accessing OME-Zarr metadata
 
 Directly instantiated tile sources start loading the OME-Zarr metadata
 immediately. Await `whenReady()` (or use the `OMEZarrTileSource.open` shortcut)
-to access the `NgffImage` instance (ome-zarr.js) and the opened zarrita arrays
-(one per resolution level) before adding the tile source to a viewer:
+to access the loaded image (`loaded.image`, an ome-zarr.js `NgffImage`) and the
+opened zarrita arrays (`loaded.arrays`, one per resolution level, highest
+resolution first) before adding the tile source to a viewer:
 
 ```javascript
 const tileSource = await OMEZarrTileSource.open({ url: url, c: 0 });
 // equivalent: await new OMEZarrTileSource({ url: url, c: 0 }).whenReady();
 
-console.log(tileSource.image.getAxesNames()); // e.g. ["t", "z", "c", "y", "x"]
-console.log(tileSource.image.omero?.channels); // omero channel metadata
-console.log(tileSource.arrays[0].shape); // full-resolution array shape
+console.log(tileSource.loaded.image.getAxesNames()); // e.g. ["t", "c", "z", "y", "x"]
+console.log(tileSource.loaded.image.omero?.channels); // omero channel metadata
+console.log(tileSource.loaded.arrays[0].shape); // full-resolution array shape
+
+console.log(tileSource.t, tileSource.z, tileSource.cs); // resolved indices
+console.log(tileSource.channels); // omero channels of the rendered channel indices
+console.log(tileSource.ranges, tileSource.colors); // resolved rendering settings
+console.log(tileSource.lutsOrColorMaps, tileSource.inverteds);
+console.log(tileSource.getWidth(), tileSource.getHeight()); // full resolution
+console.log(tileSource.getWidth(0), tileSource.getHeight(0)); // lowest resolution
 
 viewer.addTiledImage({ tileSource: tileSource }); // no second metadata request
 ```
 
-The metadata is loaded once per tile source instance: OpenSeadragon reuses a
-tile source instance passed to it as-is (waiting for it to become ready if
-necessary), whereas a URL or an inline configuration object makes OpenSeadragon
-create (and load) a new instance. `whenReady()` rejects (and `image`/`arrays`
-throw) if loading fails.
+`OMEZarrTileSource.open` accepts an `AbortSignal` as `signal` in its third
+argument to cancel loading. The metadata is loaded once per tile source
+instance: OpenSeadragon reuses a tile source instance passed to it as-is
+(waiting for it to become ready if necessary), whereas a URL or an inline
+configuration object makes OpenSeadragon create (and load) a new instance.
+`whenReady()` rejects (and `loaded` throws) if loading or validation fails.
+
+The `t`, `z` and `cs` getters return the resolved values (the omero defaults or
+active channels if the option was not given); `cs` is always an array (the
+`c` option may be a single index), and `channels` returns the omero channel
+objects for `cs`. Before the tile source is ready, they return the configured
+options. The `ranges`, `colors`, `lutsOrColorMaps` and `inverteds` getters
+return the resolved rendering settings of the rendered channels, merging the
+configured values with the omero metadata per channel: `undefined` before the
+tile source is ready or if the image has no omero metadata, like `channels`.
+Entries that are still `undefined` fall back at render time to the data type
+range, white, no LUT and not inverted.
 
 ### Sharing OME-Zarr metadata between tile sources
 
-A loaded `NgffImage` can be reused by other directly instantiated tile sources
-for the same URL (e.g. one tile source per channel) by passing it as the second
-constructor argument (also supported by `OMEZarrTileSource.open`). This skips
-loading the OME-Zarr metadata (the `zip` option is ignored) and reuses the
-opened zarrita arrays, which ome-zarr.js caches on the `NgffImage` instance.
-The tile source never modifies the `NgffImage`, so sharing is safe:
+The loaded image and arrays (`OMEZarr`) can be reused by other directly
+instantiated tile sources for the same URL (e.g. one tile source per channel)
+by passing them as the second constructor argument (also supported by
+`OMEZarrTileSource.open`). This skips loading the OME-Zarr metadata (the `zip`
+option is ignored) and reuses the opened zarrita arrays. The tile source never
+modifies the loaded image, so sharing is safe:
 
 ```javascript
-import { NgffImage } from "ome-zarr.js";
+// load once with the tile source's loader ...
+const loaded = await OMEZarrTileSource.loadOMEZarr(url);
+const tileSources = loaded.image.omero.channels.map(
+  (_, c) => new OMEZarrTileSource({ url: url, c: c }, loaded),
+);
 
-// reuse the image loaded by a first tile source
+// ... or reuse what a first tile source has loaded
 const tileSource1 = await OMEZarrTileSource.open({ url: url, c: 0 });
 const tileSource2 = new OMEZarrTileSource(
   { url: url, c: 1 },
-  tileSource1.image,
+  tileSource1.loaded,
 );
+```
 
-// or load the image with the app's own ome-zarr.js import
-const image = await NgffImage.load(url);
-const tileSource3 = new OMEZarrTileSource({ url: url, c: 2 }, image);
+`loadOMEZarr(url, zip?, { signal })` loads the metadata with ome-zarr.js and
+opens the arrays of all resolution levels. An `OMEZarr` can also be assembled
+from an `NgffImage` loaded by the app, as long as `arrays` lists the
+opened arrays of `image.paths` in order. It is not checked against the URL of
+the tile source it is passed to.
+
+### Loading chunks directly
+
+`loadChunks(level, tile, { signal })` returns the (y, x) zarrita chunks of the
+rendered channels at the rendered timepoint and z-slice, either for one tile
+(`{ x, y }` tile coordinates, as passed to OpenSeadragon) or for the whole
+level plane (`tile` `undefined`):
+
+```javascript
+const chunks = await tileSource.loadChunks(tileSource.maxLevel, { x: 0, y: 0 });
+const plane = await tileSource.loadChunks(0, undefined); // lowest resolution
+```
+
+`OMEZarrTileSource.render(tileData)` composites such chunks into a 2D canvas
+context, the same way the `ome-zarr` to `context2d` converter does:
+
+```javascript
+import { getDataTypeRange } from "omezarr-tilesource";
+
+const ctx = OMEZarrTileSource.render({
+  chunks: plane,
+  // the tile data holds the renderChunks arguments, one per chunk, with the
+  // defaults of the tile source getters applied
+  ranges: plane.map(
+    (chunk, c) => tileSource.ranges?.[c] ?? getDataTypeRange(chunk),
+  ),
+  colors: plane.map((_, c) => tileSource.colors?.[c] ?? [255, 255, 255]),
+  lutsOrColorMaps: plane.map((_, c) => tileSource.lutsOrColorMaps?.[c]),
+  inverteds: plane.map((_, c) => tileSource.inverteds?.[c] ?? false),
+  autoBoost: tileSource.autoBoost,
+});
 ```
 
 ## Data pipeline
 
-By default (`dataType: "context2d"`), tiles are rendered by the tile source and
-passed to OpenSeadragon as 2D canvas contexts, using the rendering settings
-(color, color LUT/map, contrast limits, inversion) from the omero metadata. For
-multi-channel images without `c`, all active channels are rendered into a
-composite image.
-
-Contrast limits are taken from the omero channel windows (`window.start`,
-`window.end`). Channels without them are rendered using the data type range
-for integer types (e.g. `[0, 65535]` for `uint16`) and `[0, 1]` for floating
-point types.
-
-With `dataType: "ome-zarr"`, tiles are instead downloaded as raw single-channel
-zarrita chunks and passed to OpenSeadragon with the data type `ome-zarr` (see
-the `OMEZarrTileData` type). Multi-channel images therefore require the `c`
-option. A converter from `ome-zarr` to `context2d` is registered on
-`OpenSeadragon.converter` when the module is imported (and by
-`OMEZarrTileSource.enable`). It reads the rendering settings at conversion time
-from the omero channel referenced by the tile data (`OMEZarrTileData.channel`).
-The channel object is shared by all tiles of a tile source, so advanced users
-may modify it (e.g. from a `tile-invalidated` handler) and re-render the cached
-tiles using `viewer.requestInvalidate()`.
+Tiles are downloaded as raw zarrita chunks, one per rendered channel, together
+with the rendering settings resolved for that tile, and passed to OpenSeadragon
+with the data type `ome-zarr` (see the `OMEZarrTileData` type: `chunks`,
+`ranges`, `colors`, `lutsOrColorMaps`, `inverteds` and `autoBoost` — the
+arguments of ome-zarr.js `renderChunks`, one entry per chunk). A converter from
+`ome-zarr` to `context2d` calls `OMEZarrTileSource.render` on demand, which
+composites them into a 2D canvas context. Because the raw chunks stay in the
+tile cache, tiles can be re-rendered without re-downloading them.
+
+Settings that are neither configured nor in the omero metadata are resolved
+when the tile is downloaded: to the data type range for integer types (e.g.
+`[0, 65535]` for `uint16`) and `[0, 1]` for floating point types, to white, to
+no LUT and to not inverted — so an image without omero metadata is rendered in
+white over its full data type range.
+
+The converters are registered on `OpenSeadragon.converter` when the module is
+imported (for the OpenSeadragon instance it imports, and for a global
+`OpenSeadragon` if present) and by `OMEZarrTileSource.enable`. Tiles cannot be
+rendered without them, so call `enable` if the app uses a different
+OpenSeadragon instance than the one resolved by this module (e.g. a separately
+bundled copy).
+
+All rendering settings in `OMEZarrTileData` are plain values, resolved from the
+tile source configuration and the omero metadata when the tile is downloaded.
+Editing the omero channels of a loaded image therefore does not affect tiles
+that are already cached, with or without `viewer.requestInvalidate()`; render
+them differently by creating a tile source with the corresponding options
+instead. Tile sources that configure rendering settings do not share cached
+tiles with tile sources that configure different ones.
 
 ## Example
 
-[Example](https://tissuumaps.github.io/OMEZarrTileSource)
+[https://tissuumaps.github.io/OMEZarrTileSource?url=https://livingobjects.ebi.ac.uk/idr/zarr/v0.5/idr0062A/6001240_labels.zarr](https://tissuumaps.github.io/OMEZarrTileSource?url=https%3A%2F%2Flivingobjects.ebi.ac.uk%2Fidr%2Fzarr%2Fv0.5%2Fidr0062A%2F6001240_labels.zarr)
+
+The example page takes the URL of the OME-Zarr image from the mandatory `url`
+query parameter, and the timepoint index, the z-slice index and the channel
+indices from the optional `t`, `z` and `c` query parameters (repeat `c` for
+multiple channels).
 
 [Source code](index.html)
 

package/dist/omezarr-tilesource.d.ts

@@ -3,58 +3,540 @@ import { default as default_2 } from 'openseadragon';
 import { NgffImage } from 'ome-zarr.js';
 import * as zarr from 'zarrita';
 
+/** An RGB color, each component in the range 0-255. */
+export declare type Color = [number, number, number];
+
+/**
+ * 32-bit FNV-1a hash of a string, over its UTF-16 code units.
+ *
+ * @param text - Text to hash
+ * @returns The hash, as an unsigned 32-bit integer
+ */
+export declare function fnv1a(text: string): number;
+
+/**
+ * Value range of a chunk's data type, used when a channel has no window.
+ *
+ * @param chunk - Chunk to get the data type range of
+ * @returns The minimum and maximum value of the data type (`[0, 1]` for
+ *   floating point and boolean data)
+ */
+export declare function getDataTypeRange(chunk: zarr.Chunk<zarr.NumberDataType | zarr.BigintDataType>): [number, number];
+
+/**
+ * Whether a URL points to a zipped OME-Zarr file (`.ozx` path suffix, ignoring
+ * any query and fragment).
+ *
+ * @param url - URL to check, as a string or a `URL`
+ * @returns Whether the URL path ends in `.ozx`
+ */
+export declare function isOZX(url: string | URL): boolean;
+
+/**
+ * A color LUT (a color per scaled value, e.g. 256 entries) or a color map (a
+ * color per raw pixel value), as used by the omero channels.
+ *
+ * Unlike {@link Color}, the colors may carry an alpha component, e.g. to render
+ * unmapped label values transparently.
+ */
+export declare type LUTOrColorMap = (Color | [number, number, number, number])[] | Map<number, Color | [number, number, number, number]>;
+
+/**
+ * A loaded OME-Zarr image: the ome-zarr.js {@link NgffImage} holding the
+ * metadata and the opened zarrita arrays of its multiscale pyramid.
+ *
+ * Created by {@link OMEZarrTileSource.loadOMEZarr} and exposed by
+ * {@link OMEZarrTileSource.loaded}. Can be passed to the constructor or to
+ * {@link OMEZarrTileSource.open} to share one metadata load across several
+ * tile sources for the same URL. The tile source never modifies it.
+ */
+export declare type OMEZarr = {
+    /** OME-Zarr metadata (multiscales, axes, omero) */
+    image: NgffImage;
+    /** One array per resolution level, highest resolution first */
+    arrays: zarr.Array<zarr.NumberDataType | zarr.BigintDataType>[];
+};
+
+/**
+ * Tile data of the OpenSeadragon data type `ome-zarr`.
+ *
+ * Every tile is finished with this raw data type; the converter registered by
+ * {@link OMEZarrTileSource.enable} (and on import) renders it to `context2d`
+ * on demand, so cached tiles can be re-rendered without re-downloading them.
+ *
+ * The rendering settings are the arguments of ome-zarr.js `renderChunks`, one
+ * entry per chunk, fully resolved from the tile source configuration and the
+ * omero metadata when the tile was downloaded — so changing either requires
+ * re-downloading the tiles.
+ */
 export declare interface OMEZarrTileData {
-    chunk: zarr.Chunk<zarr.NumberDataType | zarr.BigintDataType>;
-    channel: Channel;
-    autoBoost?: boolean;
+    /** One (y, x) chunk per rendered channel, in {@link OMEZarrTileSource.cs} order */
+    chunks: zarr.Chunk<zarr.NumberDataType | zarr.BigintDataType>[];
+    /**
+     * The contrast limits (`[min, max]`) of each chunk
+     * ({@link OMEZarrTileSource.ranges}), falling back to the data type range of
+     * the chunk. `min` is always less than `max`.
+     */
+    ranges: [number, number][];
+    /**
+     * The RGB color of each chunk ({@link OMEZarrTileSource.colors}), falling
+     * back to white. Unused for chunks with a LUT or a color map.
+     */
+    colors: Color[];
+    /**
+     * The color LUT or color map of each chunk
+     * ({@link OMEZarrTileSource.lutsOrColorMaps}). `undefined` entries are
+     * rendered with their {@link colors} entry instead.
+     */
+    lutsOrColorMaps: (LUTOrColorMap | undefined)[];
+    /**
+     * Whether to invert each chunk ({@link OMEZarrTileSource.inverteds}), falling
+     * back to `false`.
+     */
+    inverteds: boolean[];
+    /** Boost the brightness of dark tiles (ome-zarr.js `renderChunks` option) */
+    autoBoost: boolean;
 }
 
+/**
+ * OpenSeadragon tile source for the OME-Zarr bioimage file format.
+ *
+ * Tiles correspond to the chunks of the multiscale pyramid stored in the
+ * OME-Zarr image; OpenSeadragon level 0 is the lowest resolution and
+ * `maxLevel` the highest. Tiles are delivered as raw `ome-zarr` data (see
+ * {@link OMEZarrTileData}) and rendered by a registered converter.
+ *
+ * Constructing a tile source starts loading the OME-Zarr metadata
+ * asynchronously (unless an {@link OMEZarr} is passed). Await
+ * {@link OMEZarrTileSource.whenReady} or use {@link OMEZarrTileSource.open}
+ * before accessing {@link OMEZarrTileSource.loaded} and the resolved
+ * {@link OMEZarrTileSource.t}, {@link OMEZarrTileSource.z},
+ * {@link OMEZarrTileSource.cs}, {@link OMEZarrTileSource.channels},
+ * {@link OMEZarrTileSource.ranges}, {@link OMEZarrTileSource.colors},
+ * {@link OMEZarrTileSource.lutsOrColorMaps} and
+ * {@link OMEZarrTileSource.inverteds}.
+ *
+ * Importing this module registers the `ome-zarr` converters on the imported
+ * OpenSeadragon instance (and on a global `OpenSeadragon`, if present). Call
+ * {@link OMEZarrTileSource.enable} for any other OpenSeadragon instance, and to
+ * register the tile source for inline configurations.
+ */
 export declare class OMEZarrTileSource extends default_2.TileSource {
     readonly url: string;
-    readonly zip?: boolean;
-    readonly c?: number;
-    readonly z?: number;
-    readonly t?: number;
-    readonly dataType: "ome-zarr" | "context2d";
-    readonly autoBoost?: boolean;
+    readonly zip: boolean;
+    private readonly _t?;
+    private readonly _z?;
+    private readonly _c?;
+    private readonly _renderSettings;
+    private readonly _renderSettingsHash;
     width: number;
     height: number;
-    private _image?;
-    private _arrays?;
+    private _loaded?;
     private readonly _readyPromise;
-    static open(config: string | OMEZarrTileSourceOptions, image?: NgffImage): Promise<OMEZarrTileSource>;
-    constructor(url: string, image?: NgffImage);
-    constructor(options: OMEZarrTileSourceOptions, image?: NgffImage);
-    get image(): NgffImage;
-    get arrays(): zarr.Array<zarr.NumberDataType | zarr.BigintDataType>[];
+    /**
+     * Registers the tile source and its `ome-zarr` data type converters with an
+     * OpenSeadragon instance.
+     *
+     * Required for inline configurations (`{ type: "ome-zarr", ... }`) and for
+     * rendering tiles with an OpenSeadragon instance other than the one imported
+     * by this module.
+     *
+     * @param os - The OpenSeadragon module to register with
+     */
+    static enable(os?: typeof default_2): void;
+    /**
+     * Loads the OME-Zarr metadata and opens the arrays of all resolution levels.
+     *
+     * The result can be passed to the constructor or to {@link open} to share one
+     * metadata load across several tile sources for the same URL.
+     *
+     * @param url - URL of the OME-Zarr image or zipped OME-Zarr file, as a string
+     *   or a `URL`; relative URLs are resolved against the document base URL
+     * @param zip - Whether the URL points to a zipped OME-Zarr file; defaults to
+     *   `true` for URLs whose path ends in `.ozx`
+     * @param options - `signal` aborts the load
+     * @returns The loaded image and its arrays, highest resolution first
+     * @throws If the URL is relative and there is no document base URL
+     */
+    static loadOMEZarr(url: string | URL, zip?: boolean, options?: {
+        signal?: AbortSignal;
+    }): Promise<OMEZarr>;
+    /**
+     * Constructs a tile source and waits until its OME-Zarr metadata is loaded.
+     *
+     * Equivalent to `new OMEZarrTileSource(config, loaded).whenReady()`, except
+     * that loading the metadata can be aborted with `signal`.
+     *
+     * @param config - URL or {@link OMEZarrTileSourceOptions}
+     * @param loaded - Previously loaded image of the same URL to reuse instead of
+     *   loading it
+     * @param options - `signal` aborts the load
+     * @returns The ready tile source; rejects if loading or validation fails
+     */
+    static open(config: string | URL | OMEZarrTileSourceOptions, loaded?: OMEZarr, options?: {
+        signal?: AbortSignal;
+    }): Promise<OMEZarrTileSource>;
+    /**
+     * Renders `ome-zarr` tile data into a composite 2D canvas context.
+     *
+     * Called by the `ome-zarr` to `context2d` converter registered by
+     * {@link enable} (and on import), and usable directly for rendering chunks
+     * loaded with {@link loadChunks} outside of OpenSeadragon.
+     *
+     * The tile data holds the rendering settings exactly as passed to ome-zarr.js
+     * `renderChunks`: each chunk is scaled to its {@link OMEZarrTileData.ranges}
+     * entry, colorized with its {@link OMEZarrTileData.colors} entry or with its
+     * {@link OMEZarrTileData.lutsOrColorMaps} entry, inverted if its
+     * {@link OMEZarrTileData.inverteds} entry is set, and the results are blended
+     * additively. Color maps ignore the range and the inversion.
+     *
+     * @param tileData - Chunks and rendering settings of one tile
+     * @returns A 2D canvas context of the chunk size holding the composite
+     * @throws If the chunks are empty or no 2D canvas context is available
+     */
+    static render(tileData: OMEZarrTileData): CanvasRenderingContext2D;
+    /**
+     * Creates a tile source and starts loading the OME-Zarr metadata (unless
+     * `loaded` is given), raising `ready` or `open-failed` asynchronously.
+     *
+     * @param url - URL of the OME-Zarr image, as a string or a `URL`, resolved
+     *   against the document base URL; zipped files are detected by the `.ozx`
+     *   path suffix
+     * @param loaded - Previously loaded image of the same URL to reuse instead of
+     *   loading it
+     * @throws If the URL cannot be resolved
+     */
+    constructor(url: string | URL, loaded?: OMEZarr);
+    /**
+     * Creates a tile source and starts loading the OME-Zarr metadata (unless
+     * `loaded` is given), raising `ready` or `open-failed` asynchronously.
+     *
+     * @param options - Tile source configuration
+     * @param loaded - Previously loaded image of the same URL to reuse instead of
+     *   loading it
+     * @throws If the configuration is invalid or the URL cannot be resolved */
+    constructor(options: OMEZarrTileSourceOptions, loaded?: OMEZarr);
+    /**
+     * The loaded OME-Zarr image and arrays.
+     *
+     * @throws If the tile source is not ready yet (or failed to load)
+     */
+    get loaded(): OMEZarr;
+    /**
+     * The rendered timepoint index: the configured `t`, otherwise the omero
+     * `rdefs.defaultT` once loaded, otherwise `undefined` (middle timepoint).
+     */
+    get t(): number | undefined;
+    /**
+     * The rendered z-slice index: the configured `z`, otherwise the omero
+     * `rdefs.defaultZ` once loaded, otherwise `undefined` (middle z-slice).
+     */
+    get z(): number | undefined;
+    /**
+     * The rendered channel indices: the configured `c` option (as an array, even if a
+     * single index was configured), otherwise the indices of all channels marked
+     * active in the omero metadata once loaded, otherwise `undefined` (all
+     * channels).
+     */
+    get cs(): number[] | undefined;
+    /**
+     * The omero channels of the rendered channels ({@link cs}): one entry per
+     * rendered channel, `undefined` for channels that the omero metadata does
+     * not cover.
+     *
+     * `undefined` instead of the whole array if `c` was not configured and the
+     * tile source is not ready or the image has no omero metadata.
+     */
+    get channels(): (Channel | undefined)[] | undefined;
+    /**
+     * The contrast limits (`[min, max]`) of the rendered channels ({@link cs}):
+     * the configured `ranges` (as an array, even if a single range was
+     * configured), otherwise the windows of the corresponding omero
+     * {@link channels}, and `undefined` wherever those are.
+     *
+     * Channels without contrast limits (`undefined` entries, or `undefined`
+     * instead of the whole array) are rendered with their data type range.
+     */
+    get ranges(): ([number, number] | undefined)[] | undefined;
+    /**
+     * The RGB colors of the rendered channels ({@link cs}): the configured
+     * `colors` (as an array, even if a single color was configured), otherwise
+     * the colors of the corresponding omero {@link channels}, and `undefined`
+     * wherever those are.
+     *
+     * Channels without a color (`undefined` entries, or `undefined` instead of
+     * the whole array) are rendered in white.
+     */
+    get colors(): (Color | undefined)[] | undefined;
+    /**
+     * The color LUTs and color maps of the rendered channels ({@link cs}): the
+     * configured `lutsOrColorMaps` (as an array, even if a single LUT or color
+     * map was configured), otherwise those of the corresponding omero
+     * {@link channels}, and `undefined` wherever those are.
+     *
+     * Channels without a LUT or color map (`undefined` entries, or `undefined`
+     * instead of the whole array) are rendered with their {@link colors} entry.
+     */
+    get lutsOrColorMaps(): (LUTOrColorMap | undefined)[] | undefined;
+    /**
+     * Whether the rendered channels ({@link cs}) are inverted: the configured
+     * `inverteds` (as an array, even if a single value was configured),
+     * otherwise the inversion of the corresponding omero {@link channels}, and
+     * `undefined` wherever those are.
+     *
+     * Channels without an inversion (`undefined` entries, or `undefined` instead
+     * of the whole array) are not inverted.
+     */
+    get inverteds(): (boolean | undefined)[] | undefined;
+    /** Whether the brightness of dark tiles is boosted (the configured `autoBoost`) */
+    get autoBoost(): boolean;
+    /**
+     * Waits until the OME-Zarr metadata is loaded and validated.
+     *
+     * @returns The tile source once `ready` has been raised; rejects with the
+     *   `open-failed` message otherwise
+     */
     whenReady(): Promise<this>;
+    /**
+     * Width in pixels of a resolution level.
+     *
+     * @param level - OpenSeadragon level (0 = lowest resolution); defaults to
+     *   `maxLevel` (full resolution)
+     * @throws If the tile source is not ready or the level is out of bounds
+     */
+    getWidth(level?: number): number;
+    /**
+     * Height in pixels of a resolution level.
+     *
+     * @param level - OpenSeadragon level (0 = lowest resolution); defaults to
+     *   `maxLevel` (full resolution)
+     * @throws If the tile source is not ready or the level is out of bounds
+     */
+    getHeight(level?: number): number;
+    /**
+     * Loads the (y, x) chunks of the rendered channels ({@link cs}) at the rendered
+     * timepoint and z-slice ({@link t}, {@link z}).
+     *
+     * @param level - OpenSeadragon level (0 = lowest resolution)
+     * @param tile - Tile coordinates within the level, or `undefined` to load the
+     *   whole level plane
+     * @param options - `signal` aborts the chunk requests
+     * @returns One chunk per rendered channel, in {@link cs} order
+     * @throws If the tile source is not ready or the level or tile is out of
+     *   bounds
+     */
+    loadChunks(level: number, tile: {
+        x: number;
+        y: number;
+    } | undefined, options?: {
+        signal?: AbortSignal;
+    }): Promise<zarr.Chunk<zarr.NumberDataType | zarr.BigintDataType>[]>;
+    /**
+     * Whether OpenSeadragon should use this tile source for a configuration:
+     * URLs whose path ends in `.ozx` and objects with `type: "ome-zarr"`.
+     */
     supports(data: string | object | object[] | Document): boolean;
+    /**
+     * Normalizes an OpenSeadragon configuration into
+     * {@link OMEZarrTileSourceOptions}.
+     *
+     * @throws For array, XML document and POST data configurations
+     */
     configure(data: string | object | object[] | Document, _url: string, postData?: string | null): OMEZarrTileSourceOptions;
+    /**
+     * Whether another tile source renders the same data: the URL, `zip`, the
+     * resolved {@link t}, {@link z} and {@link cs}, and the hash of the
+     * configured rendering settings.
+     *
+     * These are the components of {@link getTileHashKey}, so tile sources compare
+     * equal exactly when they share cached tiles. The resolved indices depend on
+     * the loaded metadata, so tile sources that are not ready yet compare by
+     * their configured indices.
+     */
     equals(other: default_2.TileSource): boolean;
+    /**
+     * Loads (or reuses) the OME-Zarr metadata, validates it against the
+     * configuration and raises `ready`, or raises `open-failed` on error.
+     *
+     * Called asynchronously by the OpenSeadragon `TileSource` constructor.
+     */
     getImageInfo(url: string): void;
+    /** Chunk width of a resolution level in pixels. */
     getTileWidth(level: number): number;
+    /** Chunk height of a resolution level in pixels. */
     getTileHeight(level: number): number;
+    /** Width of a resolution level relative to the full resolution. */
     getLevelScale(level: number): number;
+    /** Number of tiles (chunks) per axis of a resolution level. */
+    getNumTiles(level: number): default_2.Point;
+    /**
+     * Encodes the tile coordinates as `level=…&x=…&y=…` for
+     * {@link downloadTileStart}; no network URL is involved.
+     */
     getTileUrl(level: number, x: number, y: number): string;
+    /**
+     * Cache key of a tile: the image URL plus the resolved data parameters
+     * (`zip`, {@link t}, {@link z}, {@link cs}) and tile coordinates, and an
+     * FNV-1a hash of the rendering settings (the configured `ranges`, `colors`,
+     * `lutsOrColorMaps` and `inverteds`, and `autoBoost`), so that tile sources
+     * rendering the same data share cached tiles.
+     *
+     * Rendering settings that are not configured are omitted from the hash, as
+     * they resolve to the same omero values for the same image.
+     */
     getTileHashKey(level: number, x: number, y: number): string;
+    /**
+     * Loads the chunks of a tile and finishes the job with `ome-zarr` data
+     * ({@link OMEZarrTileData}); fails the job if loading fails.
+     */
     downloadTileStart(context: default_2.ImageJob): void;
+    /** Aborts the chunk requests of a pending tile download. */
     downloadTileAbort(context: default_2.ImageJob): void;
-    static enable(os?: typeof default_2): void;
+    /**
+     * Normalizes a configured rendering setting into one entry per rendered
+     * channel.
+     *
+     * @param options - The tile source configuration
+     * @param name - Name of the rendering setting to normalize
+     * @param isValue - Whether a value is a single value rather than an array of
+     *   values
+     * @param c - The normalized `c` option, to validate the length against and to
+     *   repeat a single value for
+     * @returns One entry per rendered channel (`undefined` entries fall back to
+     *   the omero metadata), or `undefined` if the setting is not configured; a
+     *   single value is repeated for every channel in `c`, or kept as the only
+     *   entry if `c` is not configured, in which case the getters repeat it
+     * @throws If the setting is neither a value nor a non-empty array of values,
+     *   or if its length does not match `c`
+     */
+    private static _normalize;
+    /**
+     * Spreads a normalized rendering setting over the rendered channels.
+     *
+     * @param values - The normalized rendering setting, if configured
+     * @param channels - The omero channels of the rendered channels, if known
+     * @returns One entry per rendered channel: the configured entries, a single
+     *   configured entry repeated for every rendered channel, or one `undefined`
+     *   entry per rendered channel if the setting is not configured
+     */
+    private static _repeat;
+    /** Registers the `ome-zarr` → `context2d` and copy converters (once). */
     private static _learnConverters;
-    private _getActiveChannelIndices;
-    private static _render;
-    private static _getDataTypeRange;
+    /** Size of a named axis at a resolution level (`1` if the axis is absent). */
+    private static _getAxisSize;
 }
 
+/**
+ * Configuration of an {@link OMEZarrTileSource}.
+ *
+ * Also accepted by OpenSeadragon as an inline tile source configuration
+ * (`tileSources: { type: "ome-zarr", url, ... }`) once the tile source has been
+ * registered with {@link OMEZarrTileSource.enable}.
+ */
 export declare interface OMEZarrTileSourceOptions {
+    /** Tile source type for inline OpenSeadragon configurations */
     type?: "ome-zarr";
-    url: string;
+    /**
+     * URL of the OME-Zarr image (group) or of a zipped OME-Zarr file, as a
+     * string or a `URL`.
+     *
+     * Relative URLs are resolved against the document base URL.
+     */
+    url: string | URL;
+    /**
+     * Whether the URL points to a zipped OME-Zarr file.
+     *
+     * Defaults to `true` for URLs whose path ends in `.ozx` (ignoring any query
+     * and fragment) and `false` otherwise.
+     */
     zip?: boolean;
-    c?: number;
-    z?: number;
+    /**
+     * Timepoint index (0-based) to render.
+     *
+     * Defaults to the omero `rdefs.defaultT`, or to the middle timepoint if the
+     * metadata has none. Validated against the image shape when the image is
+     * loaded.
+     */
     t?: number;
-    dataType?: "ome-zarr" | "context2d";
+    /**
+     * Z-slice index (0-based) to render.
+     *
+     * Defaults to the omero `rdefs.defaultZ`, or to the middle z-slice if the
+     * metadata has none. Validated against the image shape when the image is
+     * loaded.
+     */
+    z?: number;
+    /**
+     * Channel index or indices (0-based) to render, composited in the given
+     * order.
+     *
+     * A single index is equivalent to an array with one element; arrays must be
+     * non-empty. Defaults to all channels marked active in the omero metadata
+     * (or to all channels if the metadata has no omero section). Validated
+     * against the image shape when the image is loaded.
+     */
+    c?: number | number[];
+    /**
+     * Contrast limits (`[min, max]`) to render the channels ({@link c}) with,
+     * overriding the omero channel windows.
+     *
+     * A single range applies to all rendered channels; arrays must have one
+     * entry per rendered channel, which is only checked against {@link c} if
+     * that is configured too. `undefined` entries fall back to the omero channel
+     * window (`window.start`, `window.end`), as does the default, and to the
+     * data type range if the metadata has none. Ignored for channels rendered
+     * with a color map.
+     */
+    range?: [number, number] | ([number, number] | undefined)[];
+    /**
+     * RGB color to render the channels ({@link c}) with, overriding the omero
+     * channel colors.
+     *
+     * A single color applies to all rendered channels; arrays must have one
+     * color per rendered channel, which is only checked against {@link c} if
+     * that is configured too. `undefined` entries fall back to the omero channel
+     * color, as does the default, and to white if the metadata has none. Ignored
+     * for channels rendered with a LUT or color map.
+     */
+    color?: Color | (Color | undefined)[];
+    /**
+     * Color LUT or color map to render the channels ({@link c}) with, overriding
+     * the omero channel LUTs and color maps.
+     *
+     * A single LUT or color map applies to all rendered channels; arrays must
+     * have one entry per rendered channel, which is only checked against
+     * {@link c} if that is configured too. `undefined` entries fall back to the
+     * omero channel LUT or color map, as does the default, and to rendering with
+     * {@link color} if the metadata has none. A color map also overrides
+     * {@link range} and {@link inverted}.
+     */
+    lutOrColorMap?: LUTOrColorMap | (LUTOrColorMap | undefined)[];
+    /**
+     * Whether to invert the channels ({@link c}), overriding the omero channel
+     * inversion.
+     *
+     * A single value applies to all rendered channels; arrays must have one
+     * entry per rendered channel, which is only checked against {@link c} if
+     * that is configured too. `undefined` entries fall back to the omero channel
+     * inversion, as does the default, and to `false` if the metadata has none.
+     * Ignored for channels rendered with a color map.
+     */
+    inverted?: boolean | (boolean | undefined)[];
+    /**
+     * Boost the brightness of dark tiles (ome-zarr.js `renderChunks` option).
+     *
+     * Defaults to `false`.
+     */
     autoBoost?: boolean;
 }
 
+/**
+ * Resolves a URL against the document base URL.
+ *
+ * @param url - URL of the OME-Zarr image, as a string or a `URL`
+ * @returns The absolute URL
+ * @throws If the URL is relative and there is no document base URL
+ */
+export declare function resolveUrl(url: string | URL): URL;
+
 export { }

package/dist/omezarr-tilesource.js

@@ -2,43 +2,158 @@ import e from "@zarrita/storage/zip";
 import { NgffImage as t, getSlices as n, renderChunks as r } from "ome-zarr.js";
 import i from "openseadragon";
 import * as a from "zarrita";
+//#region src/utils.ts
+function o(e) {
+	let t = 2166136261;
+	for (let n = 0; n < e.length; n++) t = Math.imul(t ^ e.charCodeAt(n), 16777619);
+	return t >>> 0;
+}
+function s(e) {
+	return new URL(e, globalThis.document?.baseURI);
+}
+function c(e) {
+	try {
+		return s(e).pathname.endsWith(".ozx");
+	} catch {
+		return e.toString().endsWith(".ozx");
+	}
+}
+function l(e) {
+	let { data: t } = e;
+	return t instanceof Int8Array ? [-128, 127] : t instanceof Uint8Array ? [0, 255] : t instanceof Int16Array ? [-32768, 32767] : t instanceof Uint16Array ? [0, 65535] : t instanceof Int32Array ? [-2147483648, 2147483647] : t instanceof Uint32Array ? [0, 4294967295] : t instanceof BigInt64Array ? [-(2 ** 63), 2 ** 63 - 1] : t instanceof BigUint64Array ? [0, 2 ** 64 - 1] : [0, 1];
+}
+//#endregion
 //#region src/OMEZarrTileSource.ts
-var o = class o extends i.TileSource {
-	zip;
-	c;
-	z;
-	t;
-	dataType;
-	autoBoost;
+var u = class u extends i.TileSource {
+	zip = !1;
+	_t;
+	_z;
+	_c;
+	_renderSettings;
+	_renderSettingsHash;
 	width = 10;
 	height = 10;
-	_image;
-	_arrays;
+	_loaded;
 	_readyPromise = new Promise((e, t) => {
 		this.addOnceHandler("ready", () => e(this)), this.addOnceHandler("open-failed", (e) => t(Error(e.message)));
 	});
 	static {
-		o._learnConverters(i);
+		u._learnConverters(i);
+	}
+	static enable(e = i) {
+		Object.assign(e, { OMEZarrTileSource: u }), u._learnConverters(e);
+	}
+	static async loadOMEZarr(n, r, i) {
+		let { signal: a } = i ?? {};
+		a?.throwIfAborted(), n = s(n), r ??= c(n);
+		let o = await t.load(r ? e.fromUrl(n) : n.toString(), { signal: a });
+		return {
+			image: o,
+			arrays: await Promise.all(o.paths.map((e) => o.openArray(e, { signal: a })))
+		};
 	}
-	static open(e, t) {
-		return new o(e, t).whenReady();
+	static async open(e, t, n) {
+		let { signal: r } = n ?? {};
+		return r?.throwIfAborted(), t ??= typeof e == "string" || e instanceof URL ? await u.loadOMEZarr(e, void 0, { signal: r }) : await u.loadOMEZarr(e.url, e.zip, { signal: r }), new u(e, t).whenReady();
+	}
+	static render(e) {
+		let { chunks: t, ranges: n, colors: i, lutsOrColorMaps: a, inverteds: o, autoBoost: s } = e, c = t[0].shape[1], l = t[0].shape[0], u = document.createElement("canvas");
+		u.width = c, u.height = l;
+		let d = u.getContext("2d");
+		if (d === null) throw Error("failed to get 2D canvas context");
+		let f = r(t, n, i, a.map((e) => Array.isArray(e) ? [...e] : e), o, s), p = new ImageData(f, c, l);
+		return d.putImageData(p, 0, 0), d;
 	}
 	constructor(e, t) {
-		typeof e == "string" ? (super(e), this.url = e, this.dataType = "context2d") : (super(e.url), this.url = e.url, this.zip = e.zip, this.c = e.c, this.z = e.z, this.t = e.t, this.dataType = e.dataType ?? "context2d", this.autoBoost = e.autoBoost), this._image = t, this._readyPromise.catch(() => {});
+		let n = typeof e == "string" || e instanceof URL ? { url: e } : e, r = s(n.url), i;
+		if (n.c !== void 0) if (Array.isArray(n.c)) {
+			if (n.c.length === 0) throw Error("c array must be non-empty");
+			i = n.c;
+		} else i = [n.c];
+		let a = u._normalize(n, "range", (e) => Array.isArray(e) && e.length === 2 && e.every((e) => typeof e == "number"), i), l = u._normalize(n, "color", (e) => Array.isArray(e) && e.length === 3 && e.every((e) => typeof e == "number"), i), d = u._normalize(n, "lutOrColorMap", (e) => e instanceof Map || Array.isArray(e) && e.length > 0 && e.every((e) => Array.isArray(e) && (e.length === 3 || e.length === 4) && e.every((e) => typeof e == "number")), i), f = u._normalize(n, "inverted", (e) => typeof e == "boolean", i);
+		super(r.toString()), this.url = r.toString(), this.zip = n.zip ?? c(r), this._t = n.t, this._z = n.z, this._c = i, this._renderSettings = {
+			ranges: a,
+			colors: l,
+			lutsOrColorMaps: d,
+			inverteds: f,
+			autoBoost: n.autoBoost ?? !1
+		}, this._renderSettingsHash = o(JSON.stringify({
+			...this._renderSettings,
+			lutsOrColorMaps: d?.map((e) => e instanceof Map ? [...e].sort(([e], [t]) => e - t) : e)
+		})), this._loaded = t, this._readyPromise.catch(() => {});
+	}
+	get loaded() {
+		if (this._loaded === void 0) throw Error("tile source not ready");
+		return this._loaded;
+	}
+	get t() {
+		return this._t === void 0 ? this._loaded?.image.omero?.rdefs?.defaultT : this._t;
+	}
+	get z() {
+		return this._z === void 0 ? this._loaded?.image.omero?.rdefs?.defaultZ : this._z;
+	}
+	get cs() {
+		return this._c === void 0 ? this._loaded?.image.omero?.channels?.flatMap((e, t) => e.active === !1 ? [] : [t]) : this._c;
+	}
+	get channels() {
+		return this._c === void 0 ? this._loaded?.image.omero?.channels?.filter((e) => e.active !== !1) : this._c.map((e) => this._loaded?.image.omero?.channels?.[e]);
+	}
+	get ranges() {
+		let e = this.channels, t = (e) => {
+			if (e?.window.start !== void 0 && e.window.end !== void 0) return [e.window.start, e.window.end];
+		};
+		return u._repeat(this._renderSettings.ranges, e)?.map((n, r) => n ?? t(e?.[r]));
+	}
+	get colors() {
+		let e = this.channels, t = (e) => {
+			if (e === void 0) return;
+			let t = e.color.replace(/^#/, "");
+			return [
+				parseInt(t.slice(0, 2), 16),
+				parseInt(t.slice(2, 4), 16),
+				parseInt(t.slice(4, 6), 16)
+			];
+		};
+		return u._repeat(this._renderSettings.colors, e)?.map((n, r) => n ?? t(e?.[r]));
+	}
+	get lutsOrColorMaps() {
+		let e = this.channels, t = (e) => e?.lut ?? e?.colorMap;
+		return u._repeat(this._renderSettings.lutsOrColorMaps, e)?.map((n, r) => n ?? t(e?.[r]));
 	}
-	get image() {
-		if (this._image === void 0) throw Error("tile source not ready");
-		return this._image;
+	get inverteds() {
+		let e = this.channels;
+		return u._repeat(this._renderSettings.inverteds, e)?.map((t, n) => t ?? e?.[n]?.inverted);
 	}
-	get arrays() {
-		if (this._arrays === void 0) throw Error("tile source not ready");
-		return this._arrays;
+	get autoBoost() {
+		return this._renderSettings.autoBoost;
 	}
 	whenReady() {
 		return this._readyPromise;
 	}
+	getWidth(e = this.maxLevel) {
+		if (e < 0 || e > this.maxLevel) throw Error("level out of bounds");
+		return u._getAxisSize(this.loaded, "x", this.maxLevel - e);
+	}
+	getHeight(e = this.maxLevel) {
+		if (e < 0 || e > this.maxLevel) throw Error("level out of bounds");
+		return u._getAxisSize(this.loaded, "y", this.maxLevel - e);
+	}
+	loadChunks(e, t, r) {
+		let i = {
+			t: this.t,
+			z: this.z
+		};
+		if (t !== void 0) {
+			let { x: n, y: r } = this.getNumTiles(e);
+			if (t.x < 0 || t.x >= n || t.y < 0 || t.y >= r) throw Error("tile out of bounds");
+			let a = this.getTileWidth(e), o = this.getTileHeight(e);
+			i.x = [t.x * a, (t.x + 1) * a], i.y = [t.y * o, (t.y + 1) * o];
+		}
+		let o = u._getAxisSize(this.loaded, "c"), s = n(this.cs ?? Array.from({ length: o }, (e, t) => t), this.loaded.arrays[this.maxLevel - e].shape, this.loaded.image.getAxesNames(), i);
+		return Promise.all(s.map((t) => a.get(this.loaded.arrays[this.maxLevel - e], t, r)));
+	}
 	supports(e) {
-		return Array.isArray(e) || e instanceof Document ? !1 : typeof e == "string" ? e.endsWith(".ozx") : "type" in e && e.type === "ome-zarr";
+		return Array.isArray(e) || e instanceof Document ? !1 : typeof e == "string" ? c(e) : "type" in e && e.type === "ome-zarr";
 	}
 	configure(e, t, n = null) {
 		if (Array.isArray(e)) throw Error("configuration from array is not supported");
@@ -53,11 +168,11 @@ var o = class o extends i.TileSource {
 		};
 	}
 	equals(e) {
-		return e instanceof o && this.url === e.url && this.zip === e.zip && this.c === e.c && this.z === e.z && this.t === e.t && this.dataType === e.dataType && this.autoBoost === e.autoBoost;
+		return e instanceof u && this.url === e.url && this.zip === e.zip && this.t === e.t && this.z === e.z && this.cs?.join(",") === e.cs?.join(",") && this._renderSettingsHash === e._renderSettingsHash;
 	}
-	getImageInfo(n) {
-		Promise.resolve(this._image ?? t.load(this.zip || this.zip === void 0 && n.endsWith(".ozx") ? e.fromUrl(n) : n)).then(async (e) => {
-			let t = e.getAxesNames();
+	getImageInfo(e) {
+		Promise.resolve(this._loaded ?? u.loadOMEZarr(e, this.zip)).then((e) => {
+			let t = e.image.getAxesNames();
 			for (let e of t) if (![
 				"t",
 				"c",
@@ -67,38 +182,39 @@ var o = class o extends i.TileSource {
 			].includes(e)) throw Error(`unsupported axis: ${e}`);
 			if (!t.includes("x") || !t.includes("y")) throw Error("missing X or Y axis");
 			if (t.indexOf("y") > t.indexOf("x")) throw Error("X axis must come after Y axis");
-			let n = await Promise.all(e.paths.map((t) => e.openArray(t))), r = t.indexOf("t"), i = r >= 0 ? n[0].shape[r] : 1;
-			if (this.t !== void 0 && (this.t < 0 || this.t >= i)) throw Error(`Invalid t index ${this.t} for image with ${i} timepoints`);
-			let a = t.indexOf("z"), o = a >= 0 ? n[0].shape[a] : 1;
-			if (this.z !== void 0 && (this.z < 0 || this.z >= o)) throw Error(`Invalid z index ${this.z} for image with ${o} z-slices`);
-			let s = t.indexOf("c"), c = s >= 0 ? n[0].shape[s] : 1;
-			if (this.c !== void 0 && (this.c < 0 || this.c >= c)) throw Error(`Invalid c index ${this.c} for image with ${c} channels`);
-			if (this.dataType !== "context2d" && this.c === void 0 && c > 1) throw Error(`Multi-channel image with ${c} channels; specify c or render as "context2d"`);
-			let l = e.checkChannelIndex(this.c ?? 0);
-			if (l.channels.length !== c) throw Error(`OME-Zarr metadata lists ${l.channels.length} channels, but the image has ${c}`);
-			if (this._getActiveChannelIndices(l).length === 0) throw Error("No active channels; specify c or activate channels in the OME-Zarr metadata");
-			this._image = e, this._arrays = n, this.width = n[0].shape[t.indexOf("x")], this.height = n[0].shape[t.indexOf("y")], this.maxLevel = n.length - 1, this.raiseEvent("ready", { tileSource: this });
-		}).catch((e) => {
-			this._image = void 0, this._arrays = void 0, this.width = 10, this.height = 10, this.maxLevel = 0, this.raiseEvent("open-failed", {
-				message: `failed to get image info for ${n}: ${e}`,
-				source: n
+			let n = u._getAxisSize(e, "t");
+			if (this._t !== void 0 && (this._t < 0 || this._t >= n)) throw Error(`Invalid t index ${this._t} for image with ${n} timepoints`);
+			let r = u._getAxisSize(e, "z");
+			if (this._z !== void 0 && (this._z < 0 || this._z >= r)) throw Error(`Invalid z index ${this._z} for image with ${r} z-slices`);
+			let i = u._getAxisSize(e, "c");
+			if (this._c !== void 0 && this._c.some((e) => e < 0 || e >= i)) throw Error(`Invalid c indices [${this._c?.join(", ")}] for image with ${i} channels`);
+			if (e.image.omero !== void 0 && e.image.omero.channels !== void 0 && e.image.omero.channels.length !== i) throw Error(`OME-Zarr metadata lists ${e.image.omero.channels.length} channels, but the image has ${i}`);
+			if (this._c === void 0 && e.image.omero !== void 0 && e.image.omero.channels !== void 0 && !e.image.omero.channels.some((e) => e.active !== !1)) throw Error("No active channels; specify c or activate channels in the OME-Zarr metadata");
+			this._loaded = e, this.width = e.arrays[0].shape[t.indexOf("x")], this.height = e.arrays[0].shape[t.indexOf("y")], this.maxLevel = e.arrays.length - 1, this.raiseEvent("ready", { tileSource: this });
+		}).catch((t) => {
+			this._loaded = void 0, this.width = 10, this.height = 10, this.maxLevel = 0, this.raiseEvent("open-failed", {
+				message: `failed to get image info for ${e}: ${t}`,
+				source: e
 			});
 		});
 	}
 	getTileWidth(e) {
-		if (this._image === void 0 || this._arrays === void 0) throw Error("tile source not ready");
+		let { image: t, arrays: n } = this.loaded;
 		if (e < 0 || e > this.maxLevel) throw Error("level out of bounds");
-		return this._arrays[this.maxLevel - e].chunks[this._image.getAxesNames().indexOf("x")];
+		return n[this.maxLevel - e].chunks[t.getAxesNames().indexOf("x")];
 	}
 	getTileHeight(e) {
-		if (this._image === void 0 || this._arrays === void 0) throw Error("tile source not ready");
+		let { image: t, arrays: n } = this.loaded;
 		if (e < 0 || e > this.maxLevel) throw Error("level out of bounds");
-		return this._arrays[this.maxLevel - e].chunks[this._image.getAxesNames().indexOf("y")];
+		return n[this.maxLevel - e].chunks[t.getAxesNames().indexOf("y")];
 	}
 	getLevelScale(e) {
-		if (this._image === void 0 || this._arrays === void 0) throw Error("tile source not ready");
 		if (e < 0 || e > this.maxLevel) throw Error("level out of bounds");
-		return this._arrays[this.maxLevel - e].shape[this._image.getAxesNames().indexOf("x")] / this.width;
+		return this.getWidth(e) / this.width;
+	}
+	getNumTiles(e) {
+		if (e < 0 || e > this.maxLevel) throw Error("level out of bounds");
+		return new i.Point(Math.ceil(this.getWidth(e) / this.getTileWidth(e)), Math.ceil(this.getHeight(e) / this.getTileHeight(e)));
 	}
 	getTileUrl(e, t, n) {
 		let r = new URLSearchParams();
@@ -106,84 +222,77 @@ var o = class o extends i.TileSource {
 	}
 	getTileHashKey(e, t, n) {
 		let r = new URL(this.url);
-		return r.searchParams.append("level", e.toString()), r.searchParams.append("x", t.toString()), r.searchParams.append("y", n.toString()), this.zip !== void 0 && r.searchParams.append("zip", this.zip.toString()), this.c !== void 0 && r.searchParams.append("c", this.c.toString()), this.z !== void 0 && r.searchParams.append("z", this.z.toString()), this.t !== void 0 && r.searchParams.append("t", this.t.toString()), r.searchParams.append("dataType", this.dataType), this.autoBoost !== void 0 && r.searchParams.append("autoBoost", this.autoBoost.toString()), r.toString();
+		return r.searchParams.append("zip", this.zip.toString()), this.t !== void 0 && r.searchParams.append("t", this.t.toString()), this.z !== void 0 && r.searchParams.append("z", this.z.toString()), this.cs !== void 0 && r.searchParams.append("c", this.cs.join(",")), r.searchParams.append("y", n.toString()), r.searchParams.append("x", t.toString()), r.searchParams.append("level", e.toString()), r.searchParams.append("render", this._renderSettingsHash.toString(16)), r.toString();
 	}
 	downloadTileStart(e) {
-		let t = e.userData, r = new AbortController();
-		t.abortController = r;
-		let i = new URLSearchParams(e.src), s = +i.get("level"), c = +i.get("x"), l = +i.get("y");
+		let t = e.userData, n = new AbortController();
+		t.abortController = n;
+		let r = new URLSearchParams(e.src), i = +r.get("level"), a = +r.get("x"), o = +r.get("y");
 		try {
-			if (this._image === void 0 || this._arrays === void 0) throw Error("tile source not ready");
-			let t = this._arrays[this.maxLevel - s], i = this._image.checkChannelIndex(this.c ?? 0), u = this._getActiveChannelIndices(i), d = u.map((e) => i.channels[e]), f = this.getTileWidth(s), p = this.getTileHeight(s), m = n(u, t.shape, this._image.getAxesNames(), {
-				x: [c * f, (c + 1) * f],
-				y: [l * p, (l + 1) * p],
-				z: this.z ?? i.rdefs?.defaultZ,
-				t: this.t ?? i.rdefs?.defaultT
-			});
-			Promise.all(m.map((e) => a.get(t, e, { signal: r.signal }))).then((t) => {
-				if (this.dataType === "context2d") {
-					let n = o._render(t, d, this.autoBoost);
-					e.finish(n, null, "context2d");
-				} else {
-					let n = {
-						chunk: t[0],
-						channel: d[0],
-						autoBoost: this.autoBoost
-					};
-					e.finish(n, null, "ome-zarr");
-				}
-			}).catch((t) => {
-				let n = r.signal.aborted;
-				r.abort(), n || e.fail(`failed to render tile for level=${s}, x=${c}, y=${l}: ${String(t)}`, null);
+			this.loadChunks(i, {
+				x: a,
+				y: o
+			}, { signal: n.signal }).then((n) => {
+				let r = this.ranges, i = this.colors, a = this.inverteds, o = this.lutsOrColorMaps, s = this.autoBoost, c = {
+					chunks: n,
+					ranges: n.map((e, t) => {
+						let [n, i] = r?.[t] ?? l(e);
+						return n < i ? [n, i] : [n, n + 1];
+					}),
+					colors: n.map((e, t) => i?.[t] ?? [
+						255,
+						255,
+						255
+					]),
+					lutsOrColorMaps: n.map((e, t) => o?.[t]),
+					inverteds: n.map((e, t) => a?.[t] ?? !1),
+					autoBoost: s
+				};
+				t.abortController = void 0, e.finish(c, null, "ome-zarr");
+			}, (t) => {
+				let r = n.signal.aborted;
+				n.abort(), r || e.fail(`failed to load chunks for level=${i}, x=${a}, y=${o}: ${String(t)}`, null);
 			});
 		} catch (t) {
-			e.fail(`failed to download tile for level=${s}, x=${c}, y=${l}: ${String(t)}`, null);
+			e.fail(`failed to download tile for level=${i}, x=${a}, y=${o}: ${String(t)}`, null);
 		}
 	}
 	downloadTileAbort(e) {
 		let t = e.userData;
 		t.abortController !== void 0 && (t.abortController.abort(), t.abortController = void 0);
 	}
-	static enable(e = i) {
-		Object.assign(e, { OMEZarrTileSource: o }), o._learnConverters(e);
+	static _normalize(e, t, n, r) {
+		let i = e[t];
+		if (i !== void 0) {
+			if (n(i)) {
+				let e = i;
+				return r === void 0 ? [e] : r.map(() => e);
+			}
+			if (!Array.isArray(i) || !i.every((e) => e === void 0 || n(e))) throw Error(`${t} must be a value or an array of values`);
+			if (i.length === 0) throw Error(`${t} array must be non-empty`);
+			if (r !== void 0 && i.length !== r.length) throw Error(`${t} array length ${i.length} does not match number of channels ${r.length} in c`);
+			return i;
+		}
+	}
+	static _repeat(e, t) {
+		return e === void 0 ? t?.map(() => void 0) : e.length === 1 && t !== void 0 ? t.map(() => e[0]) : e;
 	}
 	static _learnConverters(e) {
-		e.converter.existsType("ome-zarr") || (e.converter.learn("ome-zarr", "context2d", (e, { chunk: t, channel: n, autoBoost: r }) => o._render([t], [n], r), 1, 1), e.converter.learn("ome-zarr", "ome-zarr", (e, t) => ({
+		e.converter.existsType("ome-zarr") || (e.converter.learn("ome-zarr", "context2d", (e, t) => u.render(t), 1, 1), e.converter.learn("ome-zarr", "ome-zarr", (e, t) => ({
 			...t,
-			chunk: {
-				...t.chunk,
-				data: t.chunk.data.slice()
-			}
+			chunks: t.chunks.map((e) => ({
+				...e,
+				data: e.data.slice()
+			}))
 		})));
 	}
-	_getActiveChannelIndices(e) {
-		return this.c !== void 0 || this.dataType !== "context2d" ? [this.c ?? 0] : e.channels.flatMap((e, t) => e.active === !1 ? [] : [t]);
-	}
-	static _render(e, t, n) {
-		let i = t.map((e) => {
-			let t = e.color.replace(/^#/, "");
-			return [
-				parseInt(t.slice(0, 2), 16),
-				parseInt(t.slice(2, 4), 16),
-				parseInt(t.slice(4, 6), 16)
-			];
-		}), a = r(e, t.map((t, n) => {
-			let [r, i] = t.window.start !== void 0 && t.window.end !== void 0 ? [t.window.start, t.window.end] : o._getDataTypeRange(e[n]);
-			return r < i ? [r, i] : [r, r + 1];
-		}), i, t.map((e) => e.lut ?? e.colorMap), t.map((e) => e.inverted === !0), n), s = e[0].shape[1], c = e[0].shape[0], l = document.createElement("canvas");
-		l.width = s, l.height = c;
-		let u = l.getContext("2d");
-		if (u === null) throw Error("failed to get 2D canvas context");
-		let d = new ImageData(a, s, c);
-		return u.putImageData(d, 0, 0), u;
-	}
-	static _getDataTypeRange(e) {
-		let { data: t } = e;
-		return t instanceof Int8Array ? [-128, 127] : t instanceof Uint8Array ? [0, 255] : t instanceof Int16Array ? [-32768, 32767] : t instanceof Uint16Array ? [0, 65535] : t instanceof Int32Array ? [-2147483648, 2147483647] : t instanceof Uint32Array ? [0, 4294967295] : t instanceof BigInt64Array ? [-(2 ** 63), 2 ** 63 - 1] : t instanceof BigUint64Array ? [0, 2 ** 64 - 1] : [0, 1];
+	static _getAxisSize(e, t, n = 0) {
+		let r = e.image.getAxesNames().indexOf(t);
+		return r >= 0 ? e.arrays[n].shape[r] : 1;
 	}
 };
 //#endregion
 //#region src/main.ts
-globalThis.OpenSeadragon && o.enable(globalThis.OpenSeadragon);
+globalThis.OpenSeadragon && u.enable(globalThis.OpenSeadragon);
 //#endregion
-export { o as OMEZarrTileSource };
+export { u as OMEZarrTileSource, o as fnv1a, l as getDataTypeRange, c as isOZX, s as resolveUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omezarr-tilesource",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "An OpenSeadragon tile source for the OME-Zarr bioimage file format",
   "homepage": "https://github.com/TissUUmaps/OMEZarrTileSource#readme",
   "bugs": "https://github.com/TissUUmaps/OMEZarrTileSource/issues",