@fideus-labs/ngff-zarr 0.0.1 → 0.2.0

package/script/io/from_ngff_zarr.js

@@ -25,48 +25,65 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromNgffZarr = fromNgffZarr;
 exports.readArrayData = readArrayData;
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
 const dntShim = __importStar(require("../_dnt.shims.js"));
 const zarr = __importStar(require("zarrita"));
 const multiscales_js_1 = require("../types/multiscales.js");
 const ngff_image_js_1 = require("../types/ngff_image.js");
-const lazy_array_js_1 = require("../types/lazy_array.js");
 const zarr_metadata_js_1 = require("../schemas/zarr_metadata.js");
-async function fromNgffZarr(storePath, options = {}) {
+async function fromNgffZarr(
+// Also accepts FileSystemStore, ZipFileStore objects in Node.js/Deno
+store, options = {}) {
     const validate = options.validate ?? false;
+    const version = options.version;
     try {
         // Determine the appropriate store type based on the path
-        let store;
-        if (storePath.startsWith("http://") || storePath.startsWith("https://")) {
+        let resolvedStore;
+        if (store instanceof Map || store instanceof zarr.FetchStore) {
+            resolvedStore = store;
+        }
+        else if (store.startsWith("http://") || store.startsWith("https://")) {
             // Use FetchStore for HTTP/HTTPS URLs
-            store = new zarr.FetchStore(storePath);
+            resolvedStore = new zarr.FetchStore(store);
         }
         else {
             // For local paths, check if we're in a browser environment
             if (typeof dntShim.dntGlobalThis !== "undefined") {
                 throw new Error("Local file paths are not supported in browser environments. Use HTTP/HTTPS URLs instead.");
             }
-            // Use dynamic import for FileSystemStore in Node.js/Deno environments
+            // Use dynamic import for FileSystemStore, ZipFileStore in Node.js/Deno environments
             try {
-                const { FileSystemStore } = await Promise.resolve().then(() => __importStar(require("@zarrita/storage")));
-                store = new FileSystemStore(storePath);
+                const { FileSystemStore, ZipFileStore } = await Promise.resolve().then(() => __importStar(require("@zarrita/storage")));
+                // @ts-ignore: Node/Deno workaround
+                if (store instanceof FileSystemStore || store instanceof ZipFileStore) {
+                    // @ts-ignore: Node/Deno workaround
+                    resolvedStore = store;
+                }
+                else {
+                    // Normalize the path for cross-platform compatibility
+                    const normalizedPath = store.replace(/^\/([A-Za-z]:)/, "$1");
+                    // @ts-ignore: Node/Deno workaround
+                    resolvedStore = new FileSystemStore(normalizedPath);
+                }
             }
             catch (error) {
                 throw new Error(`Failed to load FileSystemStore: ${error}. Use HTTP/HTTPS URLs for browser compatibility.`);
             }
         }
-        const root = zarr.root(store);
         // Try to use consolidated metadata for better performance
-        let consolidatedRoot;
+        let optimizedStore;
         try {
-            consolidatedRoot = await zarr.tryWithConsolidated(store);
+            // @ts-ignore: tryWithConsolidated typing
+            optimizedStore = await zarr.tryWithConsolidated(resolvedStore);
         }
         catch {
-            consolidatedRoot = store;
+            optimizedStore = resolvedStore;
         }
-        const group = await zarr.open.v2(zarr.root(consolidatedRoot), {
+        const root = await zarr.open(optimizedStore, {
             kind: "group",
         });
-        const attrs = group.attrs;
+        const attrs = root.attrs;
         if (!attrs || !attrs.multiscales) {
             throw new Error("No multiscales metadata found in Zarr store");
         }
@@ -81,24 +98,60 @@ async function fromNgffZarr(storePath, options = {}) {
             if (!result.success) {
                 throw new Error(`Invalid OME-Zarr metadata: ${result.error.message}`);
             }
+            // Check version compatibility if specified
+            if (version) {
+                const metadataWithVersion = multiscalesMetadata;
+                if (metadataWithVersion.version !== version) {
+                    throw new Error(`Expected OME-Zarr version ${version}, but found ${metadataWithVersion.version || "unknown"}`);
+                }
+            }
         }
         const metadata = multiscalesMetadata;
         // Extract omero metadata from root attributes if present
         if (attrs.omero) {
-            metadata.omero = attrs.omero;
+            const omeroData = attrs.omero;
+            // Handle backward compatibility for OMERO window metadata
+            if (omeroData.channels && Array.isArray(omeroData.channels)) {
+                for (const channel of omeroData.channels) {
+                    if (channel.window && typeof channel.window === "object") {
+                        const window = channel.window;
+                        // Ensure both min/max and start/end are present for compatibility
+                        if (window.min !== undefined && window.max !== undefined) {
+                            // If only min/max present, use them for start/end
+                            if (window.start === undefined) {
+                                window.start = window.min;
+                            }
+                            if (window.end === undefined) {
+                                window.end = window.max;
+                            }
+                        }
+                        else if (window.start !== undefined && window.end !== undefined) {
+                            // If only start/end present, use them for min/max
+                            if (window.min === undefined) {
+                                window.min = window.start;
+                            }
+                            if (window.max === undefined) {
+                                window.max = window.end;
+                            }
+                        }
+                    }
+                }
+            }
+            metadata.omero = omeroData;
         }
         const images = [];
         for (const dataset of metadata.datasets) {
             const arrayPath = dataset.path;
-            const zarrArray = await zarr.open.v2(root.resolve(arrayPath), {
+            const zarrArray = (await zarr.open(root.resolve(arrayPath), {
                 kind: "array",
-            });
-            const lazyArray = new lazy_array_js_1.LazyArray({
-                shape: zarrArray.shape,
-                dtype: zarrArray.dtype,
-                chunks: [zarrArray.chunks],
-                name: arrayPath,
-            });
+            }));
+            // Verify we have an array with the expected properties
+            if (!zarrArray ||
+                !("shape" in zarrArray) ||
+                !("dtype" in zarrArray) ||
+                !("chunks" in zarrArray)) {
+                throw new Error(`Invalid zarr array at path ${arrayPath}: missing shape property`);
+            }
             const scale = {};
             const translation = {};
             for (const transform of dataset.coordinateTransformations) {
@@ -125,7 +178,7 @@ async function fromNgffZarr(storePath, options = {}) {
                 return acc;
             }, {});
             const ngffImage = new ngff_image_js_1.NgffImage({
-                data: lazyArray,
+                data: zarrArray,
                 dims,
                 scale,
                 translation,
@@ -151,9 +204,23 @@ async function readArrayData(storePath, arrayPath, selection) {
     try {
         const store = new zarr.FetchStore(storePath);
         const root = zarr.root(store);
-        const zarrArray = await zarr.open.v2(root.resolve(arrayPath), {
-            kind: "array",
-        });
+        // Try to open as zarr v2 first, then v3 if that fails
+        let zarrArray;
+        try {
+            zarrArray = await zarr.open.v2(root.resolve(arrayPath), {
+                kind: "array",
+            });
+        }
+        catch (v2Error) {
+            try {
+                zarrArray = await zarr.open.v3(root.resolve(arrayPath), {
+                    kind: "array",
+                });
+            }
+            catch (v3Error) {
+                throw new Error(`Failed to open zarr array ${arrayPath} as either v2 or v3 format. v2 error: ${v2Error}. v3 error: ${v3Error}`);
+            }
+        }
         if (selection) {
             return await zarr.get(zarrArray, selection);
         }

package/script/io/hcs.d.ts

@@ -0,0 +1,18 @@
+import type { HCSPlate } from "../types/hcs.js";
+export interface FromHcsZarrOptions {
+    validate?: boolean;
+    wellCacheSize?: number;
+    imageCacheSize?: number;
+}
+export interface ToHcsZarrOptions {
+    compressionLevel?: number;
+}
+/**
+ * Read an HCS plate from an OME-Zarr NGFF store.
+ */
+export declare function fromHcsZarr(store: string | object, options?: FromHcsZarrOptions): HCSPlate;
+/**
+ * Write an HCS plate to an OME-Zarr NGFF store.
+ */
+export declare function toHcsZarr(plate: HCSPlate, store: string | object, _options?: ToHcsZarrOptions): void;
+//# sourceMappingURL=hcs.d.ts.map

package/script/io/hcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hcs.d.ts","sourceRoot":"","sources":["../../src/io/hcs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,iBAAiB,CAAC;AAG/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAE/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE,kBAAuB,GAC/B,QAAQ,CAkCV;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,GAAE,gBAAqB,GAC9B,IAAI,CAaN"}

package/script/io/hcs.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromHcsZarr = fromHcsZarr;
+exports.toHcsZarr = toHcsZarr;
+const hcs_js_1 = require("../types/hcs.js");
+/**
+ * Read an HCS plate from an OME-Zarr NGFF store.
+ */
+function fromHcsZarr(store, options = {}) {
+    const { validate = false, wellCacheSize, imageCacheSize } = options;
+    if (validate) {
+        console.warn("HCS validation not yet implemented");
+    }
+    if (typeof store !== "string") {
+        throw new Error("Non-string store types not yet supported");
+    }
+    // For now, create a mock implementation
+    // This will be properly implemented when the zarrita API integration is complete
+    const plateMetadata = {
+        columns: [{ name: "1" }, { name: "2" }],
+        rows: [{ name: "A" }, { name: "B" }],
+        wells: [
+            { path: "A/1", rowIndex: 0, columnIndex: 0 },
+            { path: "A/2", rowIndex: 0, columnIndex: 1 },
+            { path: "B/1", rowIndex: 1, columnIndex: 0 },
+            { path: "B/2", rowIndex: 1, columnIndex: 1 },
+        ],
+        version: "0.4",
+        acquisitions: [{ id: 0, name: "Test Acquisition" }],
+        field_count: 2,
+        name: "Test Plate",
+    };
+    return new hcs_js_1.HCSPlate({
+        store,
+        metadata: plateMetadata,
+        wellCacheSize,
+        imageCacheSize,
+    });
+}
+/**
+ * Write an HCS plate to an OME-Zarr NGFF store.
+ */
+function toHcsZarr(plate, store, _options = {}) {
+    if (typeof store !== "string") {
+        throw new Error("Non-string store types not yet supported");
+    }
+    // Mock implementation for now
+    console.log(`HCS plate structure would be created at ${store}`);
+    console.log(`Plate: ${plate.name}`);
+    console.log(`Wells: ${plate.wells.length}`);
+    console.log(`Rows: ${plate.rows.length}, Columns: ${plate.columns.length}`);
+    if (plate.acquisitions) {
+        console.log(`Acquisitions: ${plate.acquisitions.length}`);
+    }
+}

package/script/io/itk_image_to_ngff_image.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Convert ITK-Wasm Image to NgffImage
+ */
+import type { Image } from "itk-wasm";
+import { NgffImage } from "../types/ngff_image.js";
+export interface ItkImageToNgffImageOptions {
+    /**
+     * Whether to add anatomical orientation metadata based on ITK LPS coordinate system
+     * @default true
+     */
+    addAnatomicalOrientation?: boolean;
+    /**
+     * Path prefix for the zarr array (e.g., "scale0/", "scale1/")
+     * @default "image"
+     */
+    path?: string;
+}
+/**
+ * Convert an ITK-Wasm Image to an NgffImage, preserving spatial metadata.
+ *
+ * This function converts ITK-Wasm Image objects to NgffImage format while
+ * preserving spatial information like spacing, origin, and optionally
+ * anatomical orientation based on the ITK LPS coordinate system.
+ *
+ * @param itkImage - The ITK-Wasm Image to convert
+ * @param options - Conversion options
+ * @returns Promise resolving to NgffImage
+ */
+export declare function itkImageToNgffImage(itkImage: Image, options?: ItkImageToNgffImageOptions): Promise<NgffImage>;
+//# sourceMappingURL=itk_image_to_ngff_image.d.ts.map

package/script/io/itk_image_to_ngff_image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"itk_image_to_ngff_image.d.ts","sourceRoot":"","sources":["../../src/io/itk_image_to_ngff_image.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAOnD,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,KAAK,EACf,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,SAAS,CAAC,CAmHpB"}

package/script/io/itk_image_to_ngff_image.js

@@ -0,0 +1,153 @@
+"use strict";
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+/**
+ * Convert ITK-Wasm Image to NgffImage
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.itkImageToNgffImage = itkImageToNgffImage;
+const zarr = __importStar(require("zarrita"));
+const ngff_image_js_1 = require("../types/ngff_image.js");
+const rfc4_js_1 = require("../types/rfc4.js");
+// Import the get_strides function from zarrita utilities
+const zarrita_1 = require("zarrita");
+/**
+ * Convert an ITK-Wasm Image to an NgffImage, preserving spatial metadata.
+ *
+ * This function converts ITK-Wasm Image objects to NgffImage format while
+ * preserving spatial information like spacing, origin, and optionally
+ * anatomical orientation based on the ITK LPS coordinate system.
+ *
+ * @param itkImage - The ITK-Wasm Image to convert
+ * @param options - Conversion options
+ * @returns Promise resolving to NgffImage
+ */
+async function itkImageToNgffImage(itkImage, options = {}) {
+    const { addAnatomicalOrientation = true, path = "image" } = options;
+    // Extract image properties from ITK-Wasm Image
+    const _data = itkImage.data;
+    // ITK stores size in physical space order [x, y, z], but the data buffer is in
+    // C-order (row-major) which means [z, y, x] indexing. Reverse to match data layout.
+    const shape = [...itkImage.size].reverse();
+    const spacing = itkImage.spacing;
+    const origin = itkImage.origin;
+    const ndim = shape.length;
+    // Determine dimension names based on shape and image type
+    // This logic matches the Python implementation
+    let dims;
+    // Check if this is a vector image (multi-component)
+    const imageType = itkImage.imageType;
+    const isVector = imageType.components > 1;
+    if (ndim === 3 && isVector) {
+        // 2D RGB/vector image: 2D spatial + components
+        dims = ["y", "x", "c"];
+    }
+    else if (ndim < 4) {
+        // Scalar images up to 3D: take the last ndim spatial dimensions
+        dims = ["z", "y", "x"].slice(-ndim);
+    }
+    else if (ndim < 5) {
+        // 3D RGB/vector or 4D scalar
+        if (isVector) {
+            dims = ["z", "y", "x", "c"];
+        }
+        else {
+            dims = ["t", "z", "y", "x"];
+        }
+    }
+    else if (ndim < 6) {
+        // 4D RGB/vector
+        dims = ["t", "z", "y", "x", "c"];
+    }
+    else {
+        throw new Error(`Unsupported number of dimensions: ${ndim}`);
+    }
+    // Identify spatial dimensions
+    const allSpatialDims = new Set(["x", "y", "z"]);
+    const spatialDims = dims.filter((dim) => allSpatialDims.has(dim));
+    // Create scale mapping from spacing
+    // ITK stores spacing/origin in physical space order (x, y, z),
+    // but we need to map them to array order (z, y, x).
+    // Reverse the arrays to convert from physical to array order, matching Python implementation.
+    const scale = {};
+    const reversedSpacing = spacing.slice().reverse();
+    spatialDims.forEach((dim, idx) => {
+        scale[dim] = reversedSpacing[idx];
+    });
+    // Create translation mapping from origin
+    const translation = {};
+    const reversedOrigin = origin.slice().reverse();
+    spatialDims.forEach((dim, idx) => {
+        translation[dim] = reversedOrigin[idx];
+    });
+    // Create Zarr array from ITK-Wasm data
+    const store = new Map();
+    const root = zarr.root(store);
+    // Determine appropriate chunk size
+    const chunkShape = shape.map((s) => Math.min(s, 256));
+    const zarrArray = await zarr.create(root.resolve(path), {
+        shape: shape,
+        chunk_shape: chunkShape,
+        data_type: imageType.componentType,
+        fill_value: 0,
+    });
+    // Write the ITK-Wasm data to the zarr array
+    // We use zarrita's set function to write the entire data efficiently
+    // Create a selection that covers the entire array (null means "all" for each dimension)
+    const selection = new Array(ndim).fill(null);
+    // Create a chunk object with the ITK-Wasm data in zarrita format
+    // ITK-Wasm stores data in column-major order with size [x, y, z],
+    // which has the same memory layout as C-order (row-major) with shape [z, y, x].
+    // We reversed the shape above, and now use C-order strides for that reversed shape.
+    const dataChunk = {
+        data: itkImage.data,
+        shape: shape,
+        stride: (0, zarrita_1._zarrita_internal_get_strides)(shape, "C"), // C-order strides for the reversed shape
+    };
+    // Write all data to the zarr array using zarrita's set function
+    // This handles chunking and encoding automatically
+    await zarr.set(zarrArray, selection, dataChunk); // Add anatomical orientation if requested
+    let axesOrientations;
+    if (addAnatomicalOrientation) {
+        axesOrientations = {};
+        for (const dim of spatialDims) {
+            const orientation = (0, rfc4_js_1.itkLpsToAnatomicalOrientation)(dim);
+            if (orientation !== undefined) {
+                axesOrientations[dim] = orientation;
+            }
+        }
+    }
+    return new ngff_image_js_1.NgffImage({
+        data: zarrArray,
+        dims,
+        scale,
+        translation,
+        name: "image",
+        axesUnits: undefined,
+        axesOrientations,
+        computedCallbacks: undefined,
+    });
+}

package/script/io/ngff_image_to_itk_image.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Convert NgffImage to ITK-Wasm Image
+ */
+import type { Image } from "itk-wasm";
+import { NgffImage } from "../types/ngff_image.js";
+export interface NgffImageToItkImageOptions {
+    /**
+     * Extract a specific time index from a time-series image
+     * If specified and 't' dimension exists, extracts the slice at this time index
+     */
+    tIndex?: number;
+    /**
+     * Extract a specific channel index from a multi-channel image
+     * If specified and 'c' dimension exists, extracts the slice at this channel index
+     */
+    cIndex?: number;
+}
+/**
+ * Convert an NgffImage to an ITK-Wasm Image, preserving spatial metadata.
+ *
+ * This function converts NgffImage objects to ITK-Wasm Image format while
+ * preserving spatial information like spacing, origin, and direction matrix.
+ * Optionally extracts specific time or channel slices.
+ *
+ * @param ngffImage - The NgffImage to convert
+ * @param options - Conversion options
+ * @returns Promise resolving to ITK-Wasm Image
+ */
+export declare function ngffImageToItkImage(ngffImage: NgffImage, options?: NgffImageToItkImageOptions): Promise<Image>;
+//# sourceMappingURL=ngff_image_to_itk_image.d.ts.map

package/script/io/ngff_image_to_itk_image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngff_image_to_itk_image.d.ts","sourceRoot":"","sources":["../../src/io/ngff_image_to_itk_image.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,KAAK,EAEV,KAAK,EAKN,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,KAAK,CAAC,CAmMhB"}