omezarr-tilesource 0.4.0 → 0.6.0

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 { }