Biomedical Imaging Storage Format Specification

life-sciences

biomedical-imaging

foundation

storage format spec

The storage format specification of TileDB-BioImaging.

Based on research from the TileDB team and avoiding a lot of the jargon, the following “components” in typical biomedical imaging projects exist:

Note

The number of dimensions is variable, between 2 and 5, and axis names are arbitrary.

Images with many levels of resolution
Optionally associated labels
Multiple metadata

On-disk design

TileDB enables all the above components as follows:

Images are modeled as groups of ND dense TileDB arrays with integer dimensions and one attribute of any of the supported data types (that is, one dense array per image level).
Labels are also modeled as groups of ND Dense TileDB arrays with integer dimensions and one attribute of any of the supported data types (that is, one dense array per image level).
TileDB models the arbitrary key-value metadata as TileDB group metadata.
The attribute name of the arrays is intensity.

Image data

TileDB-BioImaging stores multi-resolution images as a group of arrays, with one dense array per resolution level. For example, consider an input TIFF file with three resolution layer pages:

2132x2488
4266x4978
17068x19918

TileDB-BioImaging creates the following directory structure:

Image.tdb      # TileDB group
  |- l_0.tdb   # TileDB array, 17068x19918
  |- l_1.tdb   # TileDB array, 4266x4978
  |- l_2.tdb   # TileDB array, 2132x2488

Image metadata

TileDB stores image-level metadata as group metadata, and individual level metadata is stored within each of the corresponding resolution-level array.

Key	Value
`axes`	`YXC`
`channels`	[`"RED"`, `"GREEN"`, `"BLUE"`]
`dataset_type`	`BIOIMG`
`fmt_version`	`2`
`json_tiffwriter_kwargs`	`{ "bigtiff": false, "byteorder": "<", "append": true, "imagej": false, "ome": false }`
`levels`	`[ { "level": 0, "name": "l_0.tdb", "axes": "CYX", "shape": [3, 53760, 183808] }, { "level": 1, "name": "l_1.tdb", "axes": "CYX", "shape": [3, 26880, 91904] }, { "level": 2, "name": "l_2.tdb", "axes": "CYX", "shape": [3, 13440, 45952] }, ... ]`
`metadata`	{ "channels": { "intensity": [ { "id": "0", "name": "Channel 0", "color": {"red": 255, "green": 0, "blue": 0, "alpha": 255}, "min": 0.0, "max": 255.0 }, { "id": "1", "name": "Channel 1", "color": {"red": 0, "green": 255, "blue": 0, "alpha": 255}, "min": 0.0, "max": 255.0 }, { "id": "2", "name": "Channel 2", "color": {"red": 0, "green": 0, "blue": 255, "alpha": 255}, "min": 0.0, "max": 255.0 } ] }, "axes": [ { "originalAxes": ["Y", "X", "C"], "originalShape": [53760, 183808, 3], "storedAxes": ["C", "Y", "X"], "storedShape": [3, 53760, 183808], "axesMapping": {"Y": ["Y"], "X": ["X"], "C": ["C"]} }, { "originalAxes": ["Y", "X", "C"], "originalShape": [26880, 91904, 3], "storedAxes": ["C", "Y", "X"], "storedShape": [3, 26880, 91904], "axesMapping": {"Y": ["Y"], "X": ["X"], "C": ["C"]} }, … ] }
`original_metadata`	`{ "philips_metadata": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" ?>\\n<DataObject ObjectType=\\"DPUfsImport\\">\\n\\t<Attribute Name=\\"DICOM_ACQUISITION_DATETIME\\"...." }`
`pixel_depth`	`{ "0": 1, "1": 1, "2": 1, "3": 1, "4": 1, "5": 1, "6": 1, "7": 1, "8": 1, "9": 1 }`
`pkg_version`	`0.2.4.dev33+dirty`

Next-generation file format (NGFF) metadata

The TileDB group metadata may also have metadata keys as specified in the NGFF metadata description. Specifically, it may have the following optional metadata keys.

Key
`axes`
`bioformats2raw.layout`
`coordinateTransformations`
`multiscales`
`omero`
`labels`
`image-label`
`plate`
`well`

Level metadata

TileDB-BioImaging stores metadata coming from each of the resolutions of an image depending on its initial storage format. TileDB-BioImaging also stores some metadata like the following:

The level to which each resolution corresponds in the TileDB group.
The XML metadata, in the case where image follows the Open Microscopy Environment (OME) specification.
The axes of the image (for example, YXS).

TileDB-BioImaging also include some original format specifics metadata for the OME-TIFF and OME-Zarr formats.

Tiff

Key	Value
`subifds`	`9`
`metadata`	`{ "axes": "YXS" }`
`extratags`	`[]`
`photometric`	`{ "py/reduce": [ { "py/type": "tifffile.tifffile.PHOTOMETRIC" }, { "py/tuple": [ 6 ] } ] }`
`planarconfig`	`{ "py/reduce": [ { "py/type": "tifffile.tifffile.PLANARCONFIG" }, { "py/tuple": [ 1 ] } ] }`
`extrasamples`	`{ "py/tuple": [] }`
`rowsperstrip`	`0`
`bitspersample`	`8`
`compression`	`{ "py/reduce": [ { "py/type": "tifffile.tifffile.COMPRESSION" }, { "py/tuple": [ 7 ] } ] }`
`predictor`	`1`
`subsampling`	`{ "py/tuple": [ 2, 2 ] }`
`jpegtables`	`{ "py/b64": "/9j/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwk...== " }`
`colormap`	`null`
`subfiletype`	`0`
`software`	`Philips DP v1.0`
`tile`	`{ "py/tuple": [ 512, 512 ] }`
`datetime`	`null`
`resolution`	`{ "py/tuple": [ 1, 1 ] }`
`resolutionunit`	`2`

Zarr

TileDB-BioImaging stores the metadata located in the .zattr files and the multi-scale metadata as described in NGFF metadata description.

Image collections

TileDB offers the ability to organize a collection of images by using an arbitrary number of nested groups. For example a collection of N images can have the following representation on storage.

.image_dataset                  # Root folder, potentially in S3.
    |-- __group                 # TileDB group dataset directory.
    |-- __meta                  # Group metadata, contains all collection's metadata in a
                                # key-Value manner.
        image_1.tiledb              # One image (id=1) converted to a TileDB group.
        |-- __group                 # TileDB group directory.
        |-- __meta                  # Group metadata, contains all group metadata in a
                                    # key-Value manner. Metadata include all kinds of
                                    # group metadata needed based on NGFF.
        |-- l_0.tdb                 # Layer 0 modeled as a 2D-5D dense TileDB array
                                    # with integer dimensions and uint8 or uint16 attribute.
        |   |-- __commits
        |   |-- __fragments
        |   |   `-- __1661541316115_1661541316115_bd1ea43c738344fa8ce2357091a2e558_14
        |   `-- __schema
        |-- l_1.tdb                 # Layer 1 modeled as a 2D-5D dense TileDB array
                                    # with integer dimensions and one attribute of
                                    # any of the supported data types.
        |   |-- __commits
        |   |-- __fragments
        |   |   `-- __1661541316135_1661541316135_e1fadcee168f4dc585eaf39d4ea42c33_14
        |   `-- __schema
        `-- l_2.tdb                 # Layer 2 modeled as a 2D-5D dense TileDB array
                                    # with integer dimensions and one attribute of
                                    # any of the supported data types.
            |-- __commits
            |-- __fragments
            |   `-- __1661541316146_1661541316146_bb390adff7c5474e8024b76b0478abc7_14
            `-- __schema
        |-- labels                      # Labels converted to TileDB group.
            |-- __group                 # TileDB label group directory.
            |-- __meta                  # Label group metadata.
            |-- l_0.tdb                 # Layer 0 modeled as a 2D-5D dense TileDB array
                                        # with integer dimensions and one attribute of
                                        # any of the supported data types.
            |   |-- __commits
            |   |-- __fragments
            |   |   `-- __1661541316115_1661541316115_bd1ea43c738344fa8ce2357091a2e558_14
            |   `-- __schema
        ...
        image_N.tiledb              # One image (id=N) converted to a TileDB group.
        |-- __group                 # TileDB group directory
        |-- __meta                  # Group metadata
        |-- l_0.tdb                 # Layer 0 modeled as a 2D-5D dense TileDB array
                                    # with integer dimensions and one attribute of
                                    # any of the supported data types.
        |   |-- __commits
        |   |-- __fragments
        |   |   `-- __1661541316115_1661541316115_bd1ea43c738344fa8ce2357091a2e558_14
        |   `-- __schema
        |-- l_1.tdb                 # Layer 1 modeled as a 2D-5D dense TileDB array
                                    # with integer dimensions and one attribute of
                                    # any of the supported data types.
        |   |-- __commits
        |   |-- __fragments
        |   |   `-- __1661541316135_1661541316135_e1fadcee168f4dc585eaf39d4ea42c33_14
        |   `-- __schema
        ...
...

Specification versions

You can find the latest changes of the format specification in the repository’s specification markdown. The specification is under active development and, thus, subject to changes. The TileDB team is committed in offering backwards-compatibility when possible.