zarrextra 0.1.0 → 0.2.1

package/README.md

@@ -6,6 +6,8 @@ This package provides helper functions and types for:
 - Parsing zarr store contents into a tree structure
 - Working with consolidated metadata
 - Serializing zarr tree structures
+- Registering additional Zarrita codecs, including JP2K (`imagecodecs_jpeg2k`)
+- Loading OME-Zarr multiscales from an existing Zarrita store for Viv-compatible viewers
 - Result type for explicit error handling
 
 ## Result Type
@@ -39,3 +41,82 @@ if (result.ok) {
 ## API
 
 See the TypeScript definitions for full API documentation.
+
+## Codec registration
+
+`registerJpeg2kCodec()` registers decode support for the standard
+`imagecodecs_jpeg2k` codec id from the Zarr codecs registry. The default decoder
+uses the optional `@cornerstonejs/codec-openjpeg` package.
+
+```typescript
+import { registerJpeg2kCodec } from 'zarrextra';
+
+registerJpeg2kCodec();
+```
+
+Applications can pass a custom decoder for alternate WASM loading or tests:
+
+```typescript
+import OpenJPEGJS from '@cornerstonejs/codec-openjpeg/decode';
+import { createOpenJpegDecoder, registerJpeg2kCodec } from 'zarrextra';
+
+registerJpeg2kCodec({ decoder: createOpenJpegDecoder(OpenJPEGJS) });
+```
+
+`registerExperimentalHtj2kCodec()` registers decode for `experimental.openjph_htj2k`
+(new writes) and legacy `experimental.imagecodecs_htj2k` fixtures. Keep datasets
+using either id clearly labelled until there is community/registry alignment.
+
+```typescript
+import OpenJPHJS from '@cornerstonejs/codec-openjph';
+import { createOpenJphDecoder, registerExperimentalHtj2kCodec } from 'zarrextra';
+
+registerExperimentalHtj2kCodec({ decoder: createOpenJphDecoder(OpenJPHJS) });
+```
+
+For offline encode (fixtures, recompress), use `encodeHtj2kPlane()` or
+`createOpenJphEncoder()` from the same package. Python `spatialdata-codec-writer`
+uses vendored OpenJPH WASM with a persistent Node worker pool; new stores use
+codec id `experimental.openjph_htj2k`.
+
+```typescript
+import { encodeHtj2kPlane } from 'zarrextra';
+
+const plane = new Uint16Array(width * height);
+// ... fill plane ...
+const encoded = await encodeHtj2kPlane(plane, { width, height }, {
+  reversible: false,
+  quality: 75,
+});
+```
+
+## Worker-backed chunk decode (browser)
+
+JP2K and other codec work can block the main thread for a long time. For browser
+apps, use the optional `zarrextra/workers` entry with
+[`@fideus-labs/fizarrita`](https://www.npmjs.com/package/@fideus-labs/fizarrita)
+to offload chunk decode to a Web Worker pool:
+
+```typescript
+import { enableWorkerChunkDecode, disableWorkerChunkDecode } from 'zarrextra/workers';
+
+enableWorkerChunkDecode();
+// ... load JP2K-backed SpatialData and render tiles ...
+disableWorkerChunkDecode();
+```
+
+This uses a thin custom codec worker that registers zarrextra image codecs
+(including OpenJPEG for `imagecodecs_jpeg2k` and OpenJPH for experimental HTJ2K)
+into `zarrita.registry` inside the worker before fizarrita's codec handler runs. Built-in zarrita codecs (bytes, zstd,
+blosc, …) are also adapted to fizarrita's worker metadata shape via
+`wrapZarrRegistryForFizarritaWorker()`. Main-thread `registerJpeg2kCodec()` is not
+required for that path.
+
+| Context | Setup |
+|---------|-------|
+| Node / CI | `registerJpeg2kCodec()` / `registerExperimentalHtj2kCodec()` on the main thread |
+| Browser | `enableWorkerChunkDecode()` from `zarrextra/workers` before loading JP2K or HTJ2K data |
+
+Optional dependencies: `@fideus-labs/fizarrita`, `@fideus-labs/worker-pool`,
+`@cornerstonejs/codec-openjpeg`, and `@cornerstonejs/codec-openjph` (bundled into
+the worker script).

package/dist/chunkDecode-Dtm8HfWS.js

@@ -0,0 +1,46 @@
+import * as e from "zarrita";
+//#region src/chunkDecode.ts
+var t = { kind: "main" };
+function n() {
+	return t;
+}
+function r(e) {
+	t = e;
+}
+var i;
+function a(e) {
+	i = e;
+}
+function o(e, t) {
+	return t ? t.aborted ? Promise.reject(t.reason ?? new DOMException("Aborted", "AbortError")) : new Promise((n, r) => {
+		let i = () => {
+			r(t.reason ?? new DOMException("Aborted", "AbortError"));
+		};
+		t.addEventListener("abort", i, { once: !0 }), e.then((e) => {
+			t.removeEventListener("abort", i), n(e);
+		}, (e) => {
+			t.removeEventListener("abort", i), r(e);
+		});
+	}) : e;
+}
+async function s(t, r, a) {
+	let s = n();
+	if (s.kind === "fizarrita") {
+		if (!i) throw Error("Worker chunk decode is enabled but fizarrita getWorker is not loaded. Import from zarrextra/workers instead of setting the backend directly.");
+		let e = await o(i(t, r, {
+			pool: s.pool,
+			workerUrl: s.options?.workerUrl,
+			useSharedArrayBuffer: s.options?.useSharedArrayBuffer,
+			cache: s.options?.cache
+		}), a?.signal);
+		if (typeof e != "object" || !e || !("data" in e)) throw Error("Expected chunk object from fizarrita getWorker().");
+		return e;
+	}
+	let c = await e.get(t, r, a);
+	if (typeof c != "object" || !c || !("data" in c)) throw Error("Expected chunk object from zarr.get().");
+	return c;
+}
+//#endregion
+export { r as n, a as r, s as t };
+
+//# sourceMappingURL=chunkDecode-Dtm8HfWS.js.map

package/dist/chunkDecode-Dtm8HfWS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkDecode-Dtm8HfWS.js","names":[],"sources":["../src/chunkDecode.ts"],"sourcesContent":["import * as zarr from 'zarrita';\nimport type { WorkerPool } from '@fideus-labs/worker-pool';\nimport type { ChunkCache, GetWorkerOptions } from '@fideus-labs/fizarrita';\n\nexport type ZarrGetOptions = {\n  signal?: AbortSignal;\n};\n\nexport type FizarritaGetWorkerOptions = Pick<\n  GetWorkerOptions,\n  'workerUrl' | 'useSharedArrayBuffer' | 'cache'\n> & {\n  pool: WorkerPool;\n};\n\nexport type ChunkDecodeBackend =\n  | { kind: 'main' }\n  | {\n      kind: 'fizarrita';\n      pool: WorkerPool;\n      options?: Omit<FizarritaGetWorkerOptions, 'pool'>;\n    };\n\nlet chunkDecodeBackend: ChunkDecodeBackend = { kind: 'main' };\n\nexport function getChunkDecodeBackend(): ChunkDecodeBackend {\n  return chunkDecodeBackend;\n}\n\nexport function setChunkDecodeBackend(backend: ChunkDecodeBackend): void {\n  chunkDecodeBackend = backend;\n}\n\ntype GetWorkerFn = (\n  arr: zarr.Array<zarr.DataType>,\n  selection: Array<number | zarr.Slice | null> | null,\n  options: FizarritaGetWorkerOptions\n) => Promise<zarr.Chunk<zarr.DataType>>;\n\nlet getWorkerImpl: GetWorkerFn | undefined;\n\nexport function setFizarritaGetWorker(impl: GetWorkerFn): void {\n  getWorkerImpl = impl;\n}\n\nfunction rejectOnAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {\n  if (!signal) {\n    return promise;\n  }\n  if (signal.aborted) {\n    return Promise.reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));\n  }\n  return new Promise((resolve, reject) => {\n    const onAbort = () => {\n      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));\n    };\n    signal.addEventListener('abort', onAbort, { once: true });\n    promise.then(\n      (value) => {\n        signal.removeEventListener('abort', onAbort);\n        resolve(value);\n      },\n      (error: unknown) => {\n        signal.removeEventListener('abort', onAbort);\n        reject(error);\n      }\n    );\n  });\n}\n\nexport async function getZarrChunk<D extends zarr.DataType>(\n  arr: zarr.Array<D>,\n  selection: Array<number | zarr.Slice | null>,\n  opts?: ZarrGetOptions\n): Promise<zarr.Chunk<D>> {\n  const backend = getChunkDecodeBackend();\n  if (backend.kind === 'fizarrita') {\n    if (!getWorkerImpl) {\n      throw new Error(\n        'Worker chunk decode is enabled but fizarrita getWorker is not loaded. ' +\n          'Import from zarrextra/workers instead of setting the backend directly.'\n      );\n    }\n    const result = await rejectOnAbort(\n      getWorkerImpl(arr, selection, {\n        pool: backend.pool,\n        workerUrl: backend.options?.workerUrl,\n        useSharedArrayBuffer: backend.options?.useSharedArrayBuffer,\n        cache: backend.options?.cache,\n      }),\n      opts?.signal\n    );\n    if (typeof result !== 'object' || result === null || !('data' in result)) {\n      throw new Error('Expected chunk object from fizarrita getWorker().');\n    }\n    return result as zarr.Chunk<D>;\n  }\n\n  const result = await zarr.get(arr, selection, opts);\n  if (typeof result !== 'object' || result === null || !('data' in result)) {\n    throw new Error('Expected chunk object from zarr.get().');\n  }\n  return result as zarr.Chunk<D>;\n}\n"],"mappings":";;AAuBA,IAAI,IAAyC,EAAE,MAAM,QAAQ;AAE7D,SAAgB,IAA4C;AAC1D,QAAO;;AAGT,SAAgB,EAAsB,GAAmC;AACvE,KAAqB;;AASvB,IAAI;AAEJ,SAAgB,EAAsB,GAAyB;AAC7D,KAAgB;;AAGlB,SAAS,EAAiB,GAAqB,GAAkC;AAO/E,QANK,IAGD,EAAO,UACF,QAAQ,OAAO,EAAO,UAAU,IAAI,aAAa,WAAW,aAAa,CAAC,GAE5E,IAAI,SAAS,GAAS,MAAW;EACtC,IAAM,UAAgB;AACpB,KAAO,EAAO,UAAU,IAAI,aAAa,WAAW,aAAa,CAAC;;AAGpE,EADA,EAAO,iBAAiB,SAAS,GAAS,EAAE,MAAM,IAAM,CAAC,EACzD,EAAQ,MACL,MAAU;AAET,GADA,EAAO,oBAAoB,SAAS,EAAQ,EAC5C,EAAQ,EAAM;MAEf,MAAmB;AAElB,GADA,EAAO,oBAAoB,SAAS,EAAQ,EAC5C,EAAO,EAAM;IAEhB;GACD,GApBO;;AAuBX,eAAsB,EACpB,GACA,GACA,GACwB;CACxB,IAAM,IAAU,GAAuB;AACvC,KAAI,EAAQ,SAAS,aAAa;AAChC,MAAI,CAAC,EACH,OAAU,MACR,+IAED;EAEH,IAAM,IAAS,MAAM,EACnB,EAAc,GAAK,GAAW;GAC5B,MAAM,EAAQ;GACd,WAAW,EAAQ,SAAS;GAC5B,sBAAsB,EAAQ,SAAS;GACvC,OAAO,EAAQ,SAAS;GACzB,CAAC,EACF,GAAM,OACP;AACD,MAAI,OAAO,KAAW,aAAY,KAAmB,EAAE,UAAU,GAC/D,OAAU,MAAM,oDAAoD;AAEtE,SAAO;;CAGT,IAAM,IAAS,MAAM,EAAK,IAAI,GAAK,GAAW,EAAK;AACnD,KAAI,OAAO,KAAW,aAAY,KAAmB,EAAE,UAAU,GAC/D,OAAU,MAAM,yCAAyC;AAE3D,QAAO"}

package/dist/chunkDecode.d.ts

@@ -0,0 +1,23 @@
+import { WorkerPool } from '@fideus-labs/worker-pool';
+import { GetWorkerOptions } from '@fideus-labs/fizarrita';
+import * as zarr from 'zarrita';
+export type ZarrGetOptions = {
+    signal?: AbortSignal;
+};
+export type FizarritaGetWorkerOptions = Pick<GetWorkerOptions, 'workerUrl' | 'useSharedArrayBuffer' | 'cache'> & {
+    pool: WorkerPool;
+};
+export type ChunkDecodeBackend = {
+    kind: 'main';
+} | {
+    kind: 'fizarrita';
+    pool: WorkerPool;
+    options?: Omit<FizarritaGetWorkerOptions, 'pool'>;
+};
+export declare function getChunkDecodeBackend(): ChunkDecodeBackend;
+export declare function setChunkDecodeBackend(backend: ChunkDecodeBackend): void;
+type GetWorkerFn = (arr: zarr.Array<zarr.DataType>, selection: Array<number | zarr.Slice | null> | null, options: FizarritaGetWorkerOptions) => Promise<zarr.Chunk<zarr.DataType>>;
+export declare function setFizarritaGetWorker(impl: GetWorkerFn): void;
+export declare function getZarrChunk<D extends zarr.DataType>(arr: zarr.Array<D>, selection: Array<number | zarr.Slice | null>, opts?: ZarrGetOptions): Promise<zarr.Chunk<D>>;
+export {};
+//# sourceMappingURL=chunkDecode.d.ts.map

package/dist/chunkDecode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkDecode.d.ts","sourceRoot":"","sources":["../src/chunkDecode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3E,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,gBAAgB,EAChB,WAAW,GAAG,sBAAsB,GAAG,OAAO,CAC/C,GAAG;IACF,IAAI,EAAE,UAAU,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;CACnD,CAAC;AAIN,wBAAgB,qBAAqB,IAAI,kBAAkB,CAE1D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAEvE;AAED,KAAK,WAAW,GAAG,CACjB,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAC9B,SAAS,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,EACnD,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AAIxC,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAE7D;AA2BD,wBAAsB,YAAY,CAAC,CAAC,SAAS,IAAI,CAAC,QAAQ,EACxD,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAClB,SAAS,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,EAC5C,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CA6BxB"}