omezarr-tilesource 0.2.0 → 0.4.0

package/README.md

@@ -12,7 +12,7 @@ An OpenSeadragon tile source for the OME-Zarr bioimage file format
 
 ## Prerequisites
 
-OpenSeadragon 5 or newer
+OpenSeadragon 6 or newer
 
 ## Installation
 
@@ -39,9 +39,11 @@ const tileSource2 = {
     type: "ome-zarr",
     url: url,
     // zip: undefined,  // undefined = OME-Zarr ZIP auto-detection based on .ozx suffix
-    // t: undefined,
-    // c: undefined,
-    // z: undefined
+    // c: undefined,  // undefined = composite of all active channels (requires dataType "context2d")
+    // 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)
 };
 
 // direct instantiation with URL (works with any OME-Zarr storage backend)
@@ -51,9 +53,11 @@ const tileSource3 = new OMEZarrTileSource(url);
 const tileSource4 = new OMEZarrTileSource({
     url: url,
     // zip: undefined,  // undefined = OME-Zarr ZIP auto-detection based on .ozx suffix
-    // t: undefined,
-    // c: undefined,
-    // z: undefined
+    // c: undefined,  // undefined = composite of all active channels (requires dataType "context2d")
+    // 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(
@@ -67,6 +71,72 @@ const viewer = OpenSeadragon(
 );
 ```
 
+### 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
+const tileSource1 = await OMEZarrTileSource.open({ url: url, c: 0 });
+const tileSource2 = new OMEZarrTileSource(
+  { url: url, c: 1 },
+  tileSource1.image,
+);
+// or, without a first tile source: NgffImage.load(url) from ome-zarr.js
+```
+
+## 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()`.
+
 ## Example
 
 [Example](https://tissuumaps.github.io/OMEZarrTileSource)

package/dist/{__vite-browser-external-BIIyDRRX.js → __vite-browser-external-B2tgTj77.js}

@@ -1,4 +1,4 @@
-import { t as e } from "./chunk-BXES_1_E.js";
+import { t as e } from "./omezarr-tilesource.js";
 //#region __vite-browser-external
 var t = /* @__PURE__ */ e(((e, t) => {
 	t.exports = {};

package/dist/{__vite-browser-external-YbutIfMq-Cv1_GH0S.js → __vite-browser-external-YbutIfMq-DmIpWUUk.js}

@@ -1,4 +1,4 @@
-//#region node_modules/.pnpm/ome-zarr.js@0.0.19/node_modules/ome-zarr.js/dist/__vite-browser-external-YbutIfMq.js
+//#region node_modules/.pnpm/ome-zarr.js@0.0.20/node_modules/ome-zarr.js/dist/__vite-browser-external-YbutIfMq.js
 var e = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
 	__proto__: null,
 	default: {}

package/dist/dist-DXBnbeGc.js

@@ -0,0 +1,90 @@
+//#region node_modules/.pnpm/vite-plugin-node-polyfills@0.28.0_vite@8.0.14_yaml@2.9.0_/node_modules/vite-plugin-node-polyfills/shims/process/dist/index.js
+function e(e) {
+	return e && e.__esModule && Object.prototype.hasOwnProperty.call(e, "default") ? e.default : e;
+}
+var t = { exports: {} }, n = t.exports = {}, r, i;
+function a() {
+	throw Error("setTimeout has not been defined");
+}
+function o() {
+	throw Error("clearTimeout has not been defined");
+}
+(function() {
+	try {
+		r = typeof setTimeout == "function" ? setTimeout : a;
+	} catch {
+		r = a;
+	}
+	try {
+		i = typeof clearTimeout == "function" ? clearTimeout : o;
+	} catch {
+		i = o;
+	}
+})();
+function s(e) {
+	if (r === setTimeout) return setTimeout(e, 0);
+	if ((r === a || !r) && setTimeout) return r = setTimeout, setTimeout(e, 0);
+	try {
+		return r(e, 0);
+	} catch {
+		try {
+			return r.call(null, e, 0);
+		} catch {
+			return r.call(this, e, 0);
+		}
+	}
+}
+function c(e) {
+	if (i === clearTimeout) return clearTimeout(e);
+	if ((i === o || !i) && clearTimeout) return i = clearTimeout, clearTimeout(e);
+	try {
+		return i(e);
+	} catch {
+		try {
+			return i.call(null, e);
+		} catch {
+			return i.call(this, e);
+		}
+	}
+}
+var l = [], u = !1, d, f = -1;
+function p() {
+	!u || !d || (u = !1, d.length ? l = d.concat(l) : f = -1, l.length && m());
+}
+function m() {
+	if (!u) {
+		var e = s(p);
+		u = !0;
+		for (var t = l.length; t;) {
+			for (d = l, l = []; ++f < t;) d && d[f].run();
+			f = -1, t = l.length;
+		}
+		d = null, u = !1, c(e);
+	}
+}
+n.nextTick = function(e) {
+	var t = Array(arguments.length - 1);
+	if (arguments.length > 1) for (var n = 1; n < arguments.length; n++) t[n - 1] = arguments[n];
+	l.push(new h(e, t)), l.length === 1 && !u && s(m);
+};
+function h(e, t) {
+	this.fun = e, this.array = t;
+}
+h.prototype.run = function() {
+	this.fun.apply(null, this.array);
+}, n.title = "browser", n.browser = !0, n.env = {}, n.argv = [], n.version = "", n.versions = {};
+function g() {}
+n.on = g, n.addListener = g, n.once = g, n.off = g, n.removeListener = g, n.removeAllListeners = g, n.emit = g, n.prependListener = g, n.prependOnceListener = g, n.listeners = function(e) {
+	return [];
+}, n.binding = function(e) {
+	throw Error("process.binding is not supported");
+}, n.cwd = function() {
+	return "/";
+}, n.chdir = function(e) {
+	throw Error("process.chdir is not supported");
+}, n.umask = function() {
+	return 0;
+};
+var _ = t.exports, v = /* @__PURE__ */ e(_);
+//#endregion
+export { v as t };

package/dist/omezarr-tilesource.d.ts

@@ -1,24 +1,33 @@
+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 {
+    chunk: zarr.Chunk<zarr.NumberDataType | zarr.BigintDataType>;
+    channel: Channel;
+    autoBoost?: boolean;
+}
 
 export declare class OMEZarrTileSource extends default_2.TileSource {
-    static readonly DUMMY_XHR: XMLHttpRequest;
     readonly url: string;
-    width: number;
-    height: number;
-    aspectRatio: number;
-    dimensions: default_2.Point;
-    maxLevel: number;
-    ready: boolean;
     readonly zip?: boolean;
-    readonly t?: number;
     readonly c?: number;
     readonly z?: number;
-    private _omero?;
-    private _multiscale?;
-    private _axisIndices?;
+    readonly t?: number;
+    readonly dataType: "ome-zarr" | "context2d";
+    readonly autoBoost?: boolean;
+    width: number;
+    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;
@@ -31,24 +40,21 @@ export declare class OMEZarrTileSource extends default_2.TileSource {
     downloadTileStart(context: default_2.ImageJob): void;
     downloadTileAbort(context: default_2.ImageJob): void;
     static enable(os?: typeof default_2): void;
-    private static _getMultiscale;
-    private static _getAxisIndices;
+    private static _learnConverters;
+    private _getActiveChannelIndices;
+    private static _render;
+    private static _getDataTypeRange;
 }
 
-export declare type OMEZarrTileSourceClass = typeof OMEZarrTileSource;
-
 export declare interface OMEZarrTileSourceOptions {
     type?: "ome-zarr";
     url: string;
     zip?: boolean;
-    t?: number;
     c?: number;
     z?: number;
+    t?: number;
+    dataType?: "ome-zarr" | "context2d";
+    autoBoost?: boolean;
 }
 
 export { }
-
-
-declare module "openseadragon" {
-    let OMEZarrTileSource: OMEZarrTileSourceClass;
-}