Introduction to OME-Zarr

OME-Zarr is a chunked file format represented in nested directories and supporting multiple resolution layers.

This structure offers faster access to data that is remotely stored. It also allows faster parallel writing to remote storage.

What would the simplest OME-Zarr look like?

Folder structure of a simple OME-Zarr with one chunk and one resolution layer:

📂 filament-single-chunk.zarr (Zarr group with .zattrs (multiscales) metadata)
└── 📁 0 (Resolution level index, Zarr array with .zarray (storage) metadata)
    └── 📁 0 (Time chunk index)
        └── 📁 0 (Channel chunk index)
            └── 📁 0 (Z chunk index)
                └── 📁 0 (Y chunk index)
                    └── 📁 0 (X chunk index)

Content of the .zattrs metadata file:

{
    "multiscales": [
        {
            "name": "filament-single-chunk.zarr",
            "version": "0.4",
            "axes": [
                { "name": "t", "type": "time", "unit": "s" },
                { "name": "c", "type": "channel", "unit": "Channel" },
                { "name": "z", "type": "space", "unit": "μm" },
                { "name": "y", "type": "space", "unit": "μm" },
                { "name": "x", "type": "space", "unit": "μm" }
            ],
            "datasets": [
                {
                    "path": "0",
                    "coordinateTransformations": [
                        {
                            "type": "scale",
                            "scale": [1.0, 1, 0.23985, 0.021462, 0.021462]
                        }
                    ]
                }
            ]
        }
    ]
}

Content of the .zarray metadata file:

{
    "chunks": [1, 1, 29, 253, 246],
    "shape": [1, 1, 29, 253, 246],
    "dtype": "|u1",
    "order": "C",
    "dimension_separator": "/",
    "fill_value": 0,
    "filters": null,
    "compressor": {
        "id": "blosc",
        "cname": "lz4",
        "clevel": 5,
        "shuffle": 1,
        "blocksize": 0
    },
    "zarr_format": 2
}

What if it had multiple chunks?

📂 filament-three-z-chunks.zarr(Zarr group with .zattrs (multiscales) metadata)
└── 📁 0 (Resolution level index, Zarr array with .zarray (storage) metadata)
    └── 📁 0 (Time chunk index)
        └── 📁 0 (Channel chunk index)
            ├── 📁 0 (z chunk index 0)
            │    └── 📁 0 (y chunk index)
            │        └── 📁 0 (x chunk index)
            ├── 📁 1 (z chunk index 1)
            │    └── 📁 0 (y chunk index)
            │        └── 📁 0 (x chunk index)
            └── 📁 2 (z chunk index 2)
                └── 📁 0 (y chunk index)
                    └── 📁 0 (x chunk index)

Content of the .zattrs metadata file:

{
    "multiscales": [
        {
            "name": "filament-single-chunk.zarr",
            "version": "0.4",
            "axes": [
                { "name": "t", "type": "time", "unit": "s" },
                { "name": "c", "type": "channel", "unit": "Channel" },
                { "name": "z", "type": "space", "unit": "μm" },
                { "name": "y", "type": "space", "unit": "μm" },
                { "name": "x", "type": "space", "unit": "μm" }
            ],
            "datasets": [
                {
                    "path": "0",
                    "coordinateTransformations": [
                        {
                            "type": "scale",
                            "scale": [1.0, 1, 0.23985, 0.021462, 0.021462]
                        }
                    ]
                }
            ]
        }
    ]
}

Content of the .zarray metadata file:

{
    "chunks": [1, 1, 10, 253, 246],
    "shape": [1, 1, 29, 253, 246],
    "dtype": "|u1",
    "order": "C",
    "dimension_separator": "/",
    "fill_value": 0,
    "filters": null,
    "compressor": {
        "id": "blosc",
        "cname": "lz4",
        "clevel": 5,
        "shuffle": 1,
        "blocksize": 0
    },
    "zarr_format": 2
}

What if it had multiple resolution levels?

📂 filament-two-layers-single-chunk.zarr
├── 📁 0 (Resolution level 0, Zarr array with .zarray (storage) metadata))
│    └── 📁 0 (Time chunk index)
│        └── 📁 0 (Channel chunk index)
│            └── 📁 0 (z chunk index)
│                └── 📁 0 (y chunk index)
│                    └── 📁 0 (x chunk index)
└── 📁 1 (Resolution level 1, Zarr array with .zarray (storage) metadata))
    └── 📁 0 (Time chunk index)
        └── 📁 0 (Channel chunk index)
            └── 📁 0 (z chunk index)
                └── 📁 0 (y chunk index)
                    └── 📁 0 (x chunk index)

Content of the .zattrs metadata file:

{
    "multiscales": [
        {
            "name": "filament.zarr",
            "version": "0.4",
            "axes": [
                { "name": "t", "type": "time", "unit": "s" },
                { "name": "c", "type": "channel", "unit": "Channel" },
                { "name": "z", "type": "space", "unit": "μm" },
                { "name": "y", "type": "space", "unit": "μm" },
                { "name": "x", "type": "space", "unit": "μm" }
            ],
            "datasets": [
                {
                    "path": "0",
                    "coordinateTransformations": [
                        { 
                            "type": "scale", 
                            "scale": [1.0, 1, 0.23985, 0.021462000487230338, 0.021462000487230338] 
                        }
                    ]
                },
                {
                    "path": "1",
                    "coordinateTransformations": [
                        { 
                            "type": "scale", 
                            "scale": [1.0, 1.0, 0.49683214285714294, 0.04309433431166092, 0.042924000974460676] 
                        }
                    ]
                }
            ]
        }
    ]
}

Content of the .zarray metadata files corresponding to levels 0 and 1:

{
    "chunks": [1, 1, 29, 253, 246],
    "shape": [1, 1, 29, 253, 246],
    "dtype": "|u1",
    "order": "C",
    "dimension_separator": "/",
    "fill_value": 0,
    "filters": null,
    "compressor": {
        "id": "blosc",
        "cname": "lz4",
        "clevel": 5,
        "shuffle": 1,
        "blocksize": 0
    },
    "zarr_format": 2
}

{
    "chunks": [1, 1, 15, 127, 123],
    "shape": [1, 1, 15, 127, 123],
    "dtype": "|u1",
    "order": "C",
    "dimension_separator": "/",
    "fill_value": 0,
    "filters": null,
    "compressor": {
        "id": "blosc",
        "cname": "lz4",
        "clevel": 5,
        "shuffle": 1,
        "blocksize": 0
    },
    "zarr_format": 2
}