SciTiff#
Scientific tiff format for imaging experiments.SciTiff format inherits HyperStacks
and define metadata on top of the HyperStacks
.
scitiff
project hosts both metadata schema and io
helpers to save/load scitiff images.
Supported IO Languages |
Metadata Schema Format |
---|---|
python |
json |
Currently there is only
python
io modules.
Why SciTiff?#
HyperStacks
has been a standard format for high energy imaging experiments.
It defines dimensions of image stack (t
, z
, c
, y
, x
).
However, it does not guarantee the order of dimensions.
Also, there is no standard way of storing the coordinate of each dimension.
For example, if there are 1_000 tiff images along the t
dimension, it is not clear if it is time of flight, or wall clock time or if it is every 1 ns or every 1 Å or if the interval is non-uniform or etc…
Therefore scitiff
project aims to define a consistent way of storing the physical properties of a tiff image stack as metadata.
Quick Links#
Scitiff Metadata Schema#
Metadata is stored as a plain text json
so the schema is defined as a json schema
.
Here is an example of the scitiff metadata of a tiff file.
{
"scitiffmeta": {
"image": {
"data": {
"dims": ["t", "z", "c", "y", "x"],
"shape": [1, 1, 1, 1, 1],
"unit": "counts",
"dtype": "float32"
},
"coords": {
"t": {"dims": ["t"], "shape": [1], "unit": "s", "dtype": "int", "values": [0.0]},
"z": {"dims": ["z"], "shape": [1], "unit": "m", "dtype": "int", "values": [0.0]},
"y": {"dims": ["y"], "shape": [1], "unit": "m", "dtype": "int", "values": [0.0]},
"x": {"dims": ["x"], "shape": [1], "unit": "m", "dtype": "int", "values": [0.0]}
}
},
"schema_version": "25.5.1.dev5+g5845ca0"
}
}
Warning
Currently it is not allowed to have multi-dimensional coordinates in the metadata.
All coordinate should be a single
or zero
dimensional data.
For example, if you want to store event_id
, which is folded into (x, y)
, it is not possible.
It is because we don’t want to store huge coordinate values as a plain text,
which can make a tiff file size unnecessarily large and make image loading slow.
SciTiff Metadata Schema is written based on the scipp.DataArray
data structure.
You can (almost) directly turn the image
field of the metadata into a scipp.DataArray
.
But the values
of the image
is supposedly stored as tiff stack.
Note
The metadata schema is defined as a pydantic.Model
and exported as a plain text json so that any platform can use the schema.
See source code of the ScitiffMetadataContainer
to see the pydantic model definition.
Download Scitiff Metadata Schema#
Scitiff Metadata Schema Json File
Here is the full metadata schema as a plain text.
{
"$defs": {
"ImageDataArrayMetadata": {
"description": "Image DataArray Metadata without values(image).",
"properties": {
"data": {"$ref": "#/$defs/ImageVariableMetadata"},
"masks": {
"additionalProperties": {"$ref": "#/$defs/ScippVariable"},
"title": "Masks",
"type": "object"
},
"coords": {
"additionalProperties": {"$ref": "#/$defs/ScippVariable"},
"title": "Coords",
"type": "object"
},
"name": {
"anyOf": [{ "type": "string" }, { "type": "null" }],
"default": null,
"title": "Name"
}
},
"required": ["data"],
"title": "ImageDataArrayMetadata",
"type": "object"
},
"ImageVariableMetadata": {
"description": "Image Metadata.",
"properties": {
"dims": {
"maxItems": 5,
"minItems": 5,
"prefixItems": [{ "const": "t", "type": "string" }, { "const": "z", "type": "string" }, { "const": "c", "type": "string" }, { "const": "y", "type": "string" }, { "const": "x", "type": "string" }],
"title": "Dims",
"type": "array"
},
"shape": {
"maxItems": 5,
"minItems": 5,
"prefixItems": [{ "type": "integer" }, { "type": "integer" }, { "type": "integer" }, { "type": "integer" }, { "type": "integer" }],
"title": "Shape",
"type": "array"
},
"unit": {
"anyOf": [{ "type": "string" }, { "type": "null" }],
"title": "Unit"
},
"dtype": {"title": "Dtype", "type": "string"}
},
"required": ["dims", "shape", "unit", "dtype"],
"title": "ImageVariableMetadata",
"type": "object"
},
"SciTiffMetadata": {
"description": "SCITIFF Metadata.",
"properties": {
"image": {"$ref": "#/$defs/ImageDataArrayMetadata"},
"schema_version": {
"default": "{VERSION_PLACEHOLDER}",
"title": "Schema Version",
"type": "string"
}
},
"required": ["image"],
"title": "SciTiffMetadata",
"type": "object"
},
"ScippVariable": {
"description": "Scipp Variable Metadata with the values.\n\nOnly 1D variable is allowed for metadata.",
"properties": {
"dims": {
"items": {"type": "string"},
"title": "Dims",
"type": "array"
},
"shape": {
"items": {"type": "integer"},
"title": "Shape",
"type": "array"
},
"unit": {
"anyOf": [{ "type": "string" }, { "type": "null" }],
"title": "Unit"
},
"dtype": {"title": "Dtype", "type": "string"},
"values": {
"anyOf": [{ "type": "number" }, { "type": "string" }, { "items": { "type": "number" }, "type": "array" }, { "items": { "type": "string" }, "type": "array" }],
"title": "Values"
}
},
"required": ["dims", "shape", "unit", "dtype", "values"],
"title": "ScippVariable",
"type": "object"
}
},
"additionalProperties": true,
"description": "SCITIFF Compatible Metadata.",
"properties": {
"scitiffmeta": {"$ref": "#/$defs/SciTiffMetadata"}
},
"required": ["scitiffmeta"],
"title": "SciTiffMetadataContainer",
"type": "object"
}