omezarr-tilesource 0.3.0 → 0.5.0

package/README.md

@@ -22,6 +22,14 @@ Using pnpm:
 pnpm add omezarr-tilesource
 ```
 
+The package is distributed as an ES module for use with a bundler (e.g. Vite).
+[zarrita](https://github.com/manzt/zarrita.js),
+[@zarrita/storage](https://github.com/manzt/zarrita.js) and
+[ome-zarr.js](https://github.com/BioNGFF/ome-zarr.js) are peer dependencies
+(installed automatically by pnpm and npm 7 or newer) and are not bundled, so
+the app and the tile source share a single copy, e.g. for passing `NgffImage`
+instances loaded by the app.
+
 ## Usage
 
 ```javascript
@@ -40,8 +48,8 @@ const tileSource2 = {
     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 metadata default
-    // t: undefined,  // undefined = omero metadata default
+    // z: undefined,  // undefined = omero rdefs default (middle z-slice if missing)
+    // t: undefined,  // undefined = omero rdefs default (middle timepoint if missing)
     // dataType: undefined,  // "context2d" (default, rendered tiles) or "ome-zarr" (raw single-channel chunks)
     // autoBoost: undefined  // boost brightness of dark tiles (default false)
 };
@@ -54,13 +62,13 @@ 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 metadata default
-    // t: undefined,  // undefined = omero metadata default
+    // z: undefined,  // undefined = omero rdefs default (middle z-slice if missing)
+    // t: undefined,  // undefined = omero rdefs default (middle timepoint if missing)
     // dataType: undefined,  // "context2d" (default, rendered tiles) or "ome-zarr" (raw single-channel chunks)
     // autoBoost: undefined  // boost brightness of dark tiles (default false)
 });
 
-const viewer = OpenSeadragon(
+const viewer = OpenSeadragon({
     ...
     tileSources: [
         tileSource1,
@@ -68,7 +76,55 @@ const viewer = OpenSeadragon(
         tileSource3,
         tileSource4
     ]
+});
+```
+
+### 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:
+
+```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
+
+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.
+
+### 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:
+
+```javascript
+import { NgffImage } from "ome-zarr.js";
+
+// reuse the image loaded by a first tile source
+const tileSource1 = await OMEZarrTileSource.open({ url: url, c: 0 });
+const tileSource2 = new OMEZarrTileSource(
+  { url: url, c: 1 },
+  tileSource1.image,
 );
+
+// 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);
 ```
 
 ## Data pipeline
@@ -79,6 +135,11 @@ passed to OpenSeadragon as 2D canvas contexts, using the rendering settings
 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`

package/dist/omezarr-tilesource.d.ts

@@ -1,5 +1,6 @@
 import { Channel } from 'ome-zarr.js';
 import { default as default_2 } from 'openseadragon';
+import { NgffImage } from 'ome-zarr.js';
 import * as zarr from 'zarrita';
 
 export declare interface OMEZarrTileData {
@@ -20,8 +21,13 @@ export declare class OMEZarrTileSource extends default_2.TileSource {
     height: number;
     private _image?;
     private _arrays?;
-    constructor(url: string);
-    constructor(options: OMEZarrTileSourceOptions);
+    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>[];
+    whenReady(): Promise<this>;
     supports(data: string | object | object[] | Document): boolean;
     configure(data: string | object | object[] | Document, _url: string, postData?: string | null): OMEZarrTileSourceOptions;
     equals(other: default_2.TileSource): boolean;
@@ -37,6 +43,7 @@ export declare class OMEZarrTileSource extends default_2.TileSource {
     private static _learnConverters;
     private _getActiveChannelIndices;
     private static _render;
+    private static _getDataTypeRange;
 }
 
 export declare interface OMEZarrTileSourceOptions {