Skip to content

N5 Metadata Dialects

Jump to bottom
Stephan Saalfeld edited this page Feb 1, 2024 · 11 revisions

N5 Metadata Dialects

This page contains a list and description of known n5 metadata dialects.

N5-viewer

The n5-viewer metadata style is briefly described here.

Hierarchy properties

Datasets (arrays) MUST be named s# with an immediate parent group called c#, where # is a non-negative integer 0,1,2,.... The s# refer to levels of a multiscale pyramid, and the c# refer to channels of a multi-channel or multi-color image. The channel groups (c#) MUST NOT contain arrays not matching s#.

Valid example hierarchies

A prototypical single-channel image

<pre>
.                             
│
└── c0
    ├── s0
    ├── s1
    └── s2

A prototypical multi-channel image

<pre>
.                             
│
├── c0
│   ├── s0
│   ├── s1
│   └── s2
└── c1
    ├── s0
    ├── s1
    └── s2

Scale levels need to be "sequential," i.e. scale levels MAY be "missing."

<pre>
.                             
│
└── c0
    ├── s0
    └── s5

Channels may be children of some other group

<pre>
.                             
│
├── image
|    ├── c0
|    │   ├── s0
|    │   └── s2
|    └── c1
|        ├── s0
|        ├── s1
|        └── s3
|
└── segmentation
     └── c0
         ├── s0
         ├── s1
         └── s2
Invalid example hierarchies

Datasets (scale levels) MUST be direct children of a channel group:

<pre>
.                             
│
└── s0

<pre>
.                             
│
└── Othello
    ├── s0
    └── s1

Channels MUST NOT contain arrays that are NOT named s#:

<pre>
.                             
│
└── c0
    ├── s0
    ├── Iago
    └── s2

Dataset-level attributes

Arrays MUST be 2, 3, or 4 dimensional. Datasets may contain a pixelResolution field that is either

"pixelResolution": {
   "unit": "um",
   "dimensions": []
}

or

"pixelResolution": []

Datasets may contain a downsamplingFactors field.

  • pixelResolution: number[] or object
    • physical scale factors and units (see Physical space)
  • downsamplingFactors: number[]
    • factors by which the image is downsampled (see Downsampling)

BigCat

This legacy metadata specification is used by BigCat, the predecessor to Paintera. The Fiji plugin can open this meta-data standard, but it is not supported for Export, so nobody feels encouraged to use it again:

Example

{
    "resolution": [ ],
    "offset": [ ],
    "downsamplingFactors": [ ]
}
  • resolution: number[]
    • physical scale factors (see Physical space)
    • is optional. If not present, the value of resolution at the highest level should be assumed.
    • specifies the resolution of the highest resolution (i.e., if present, its value should be identical for all scale levels)
  • offset: number[]
    • physical translation (see Physical space)
  • downsamplingFactors: (Optional) number[]
    • factors by which the image is downsampled (see Downsampling)

COSEM

The COSEM metadata style is described here.

Dataset-level attributes

Datasets shall contain a transform field that describes how the discrete pixel grid should be arranged in physical space.

"transform": {
    "axes": [ ], 
    "units": [ ],
    "scale": [ ],
    "translate": [ ]
}

All fields below must have lengths equal to the dimensionality of the n5 dataset they describe.

  • axes: String[]
    • gives a label to axis indexes
    • examples: ["x","y","z"], ["z","y","x"]
  • units: String[]
    • the physical
    • examples ["nm","nm","nm"], ["microns","microns","microns"]
  • scale: number[]
    • physical scale factors (see physical space)
  • translate: number[]
    • physical translation (see physical space)

ImageJ

The ImageJ metadata dialect mirrors the metadata stored in ImageJ's ImagePlus class. Images of up to five dimensions are supported, i.e. 3D, multi-channel, time-series can be described with this dialect. This standard does not support multiscale datasets.

Dataset-level attributes

OME-NGFF

This information refers to Version 0.3 of the ome-ngff specification.o

Multiscale metadata example

Example:

{
    "multiscales": [
        {
            "axes": [ "z", "y", "x" ],
            "datasets": [
                { "path": "s0" },
                { "path": "s1" },
                { "path": "s2" }
            ],
            "metadata": {
                "order": 0,
                "preserve_range": true,
                "scale": [ 0.5, 0.5, 0.5 ]
            },
            "name": "zyx",
            "type": "skimage.transform._warps.rescale",
            "version": "0.3"
        }
    ]
}

In this example the dataset pixel scales are:

  • s0 : [1.0, 1.0, 1.0]
  • s1 : [2.0, 2.0, 2.0]
  • s2 : [4.0, 4.0, 4.0]

All of these scales are at arbitrary (pixel) units.

Concepts

Physical space

Call the 0th, 1st, and 2nd dimensions of the dataset i, j, and k, respectively. Then if axis: ["x","y","z"], then The discrete point at (i,j,k), should be mapped to the physical point (x,y,z) as follows:

x = (scale[0] * i) + translate[0]
y = (scale[1] * j) + translate[1]
z = (scale[2] * k) + translate[2]

Downsampling

The N5-viewer and BigCat dialects assume downsampling is done in a particular way such that it affects both the scale and translation of the physical space. Given a scale and downsamplingFactors discrete coordinates are mapped to physical space with:

x = (scale[0] * downsamplingFactors[0] * i) + (scale[0] * (downsamplingFactors[0] - 1))
y = (scale[1] * downsamplingFactors[1] * j) + (scale[1] * (downsamplingFactors[1] - 1))
z = (scale[2] * downsamplingFactors[2] * k) + (scale[2] * (downsamplingFactors[2] - 1))

similar to the above.

Clone this wiki locally