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

IO User Guide

user-guide/io.html

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.6.0"
  }
}

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"
}