6D, 7D and 8D storage

Overview

This outlines an interim storage solution for storing 6D, 7D and 8D data in our 5D structure using Z, T and C.

This has been produced as part of our transition to N-dimensional support. It will take a large amount of work throughout the OME specifications and OME software to move to a fully N-dimensional approach to data storage. Given the scale and impact of the change, this will take some time to schedule and complete.

This proposal is designed to allow people wishing to write data with 6, 7 or 8 dimensions into our model today, in a way that can be upgraded in the future once N-dimensional support is available.

The key addition is a new XML Annotation to the Image element.

This was originally added to the pixels element but in use Image has proved to be a better location. We recommend Image is used from now on, but our code will also work with attachment to Pixels for backward compatibility.

This annotation will use namespace

"openmicroscopy.org/omero/dimension/modulo"

and store information on the additional dimensions embedded in the Z, T or C data. This annotation is optional and, if absent the model works as it currently does in the 5D case. Also, if an application does not understand the Modulo addition, then it can treat the data as 5D, though the displayed results would need some interpretation.

<SA:StructuredAnnotations>
    <SA:XMLAnnotation ID="Annotation:3" Namespace="openmicroscopy.org/omero/dimension/modulo">
        <SA:Value>
            <Modulo namespace="http://www.openmicroscopy.org/Schemas/Additions/2011-09">
                <ModuloAlongZ Type="angle" Unit="degree">
                    <Label>45</Label>
                    <Label>90</Label>
                </ModuloAlongZ>
                <ModuloAlongT Type="lifetime" TypeDescription="TCSPC" Start="0" Step="2" End="128"/>
                <ModuloAlongC Type="phase" Start="0" Step="1" End="255"/>
            </Modulo>
        </SA:Value>
    </SA:XMLAnnotation>
</SA:StructuredAnnotations>

The three dimensions ModuloAlongZ, ModuloAlongT and ModuloAlongC each can be specified in two ways:

  • either using a specific number of labels (see ModuloAlongZ example above)
  • or using a Start, Step and End (see ModuloAlongT or ModuloAlongC example above).

The attribute Type is Required and is drawn from the following enumeration:

  • angle
  • phase
  • tile
  • lifetime
  • lambda
  • other

The OMERO clients cannot display dimensions of type other but the OMERO server can store this data.

The attribute TypeDescription is optional. It is a simple text description of the Type used to indicate to an application or user how the data should be interpreted.

The attribute Unit is optional. It is a simple text description.

If you are going to specify Label elements inside the dimension then you do not need any other attributes.

If you are not using Label elements then you MUST specify the Start and End of the range the dimension covers. The dimension will be assumed to have values covering Start to End INCLUSIVE. The values will be assumed to go up in steps of 1 unless the optional Step is set to another value.

e.g. a collection of planes taken at the same timepoint but from different angle might use:

<SA:StructuredAnnotations>
    <SA:XMLAnnotation ID="Annotation:3" Namespace="openmicroscopy.org/omero/dimension/modulo">
        <SA:Value>
            <Modulo namespace="http://www.openmicroscopy.org/Schemas/Additions/2011-09">
                <ModuloAlongZ Type="angle" Unit="degree">
                    <Label>45</Label>
                    <Label>90</Label>
                </ModuloAlongZ>
            </Modulo>
        </SA:Value>
    </SA:XMLAnnotation>
</SA:StructuredAnnotations>

The number of Label elements (if present) is used to devise the number of planes in the extra dimension. This is the equivalent of the value stored in TheX, TheY, TheZ, TheT, TheC in the 5D OME Model. If there are 2 Label``s in ``ModuloAlongZ then the dimension stores two planes for each Z. If there are no Label elements then Start, Step and End attributes are used to devise the number of planes in the extra dimension. So with Start 100, End 150 and Step 2 in ModuloAlongT then the dimension stores 26 planes for each T.

To find the true value of Z, T or C for a plane, you need to take the 5D value and divide it appropriately by the number of planes in the extra dimension.

e.g. if 3 extra planes are stored for each Z plane

| Number of Z Plane 5D view | True Z Plane | ModuleZ Plane |
|            0              |       0      |       0       |
|            1              |       0      |       1       |
|            2              |       0      |       2       |
|            3              |       1      |       0       |
|            4              |       1      |       1       |
|            5              |       1      |       2       |
|            6              |       2      |       0       |
|            7              |       2      |       1       |
… and so on

e.g. if you have 2 extra Angle(A) planes stored for each Z plane and 3 extra Phase(P) for each T then

       Stored | Real
C1 , Z1 , T1  | C1 , Z1 , A1, T1 , P1
C2 , Z1 , T1  | C2 , Z1 , A1, T1 , P1
C1 , Z2 , T1  | C1 , Z1 , A2, T1 , P1
C2 , Z2 , T1  | C2 , Z1 , A2, T1 , P1
C1 , Z3 , T1  | C1 , Z2 , A1, T1 , P1
C2 , Z3 , T1  | C2 , Z2 , A1, T1 , P1
C1 , Z4 , T1  | C1 , Z2 , A2, T1 , P1
C2 , Z4 , T1  | C2 , Z2 , A2, T1 , P1
C1 , Z1 , T2  | C1 , Z1 , A1, T1 , P2
…
C2 , Z4 , T2  | C2 , Z2 , A2, T1 , P2
C1 , Z1 , T3  | C1 , Z1 , A1, T1 , P3
…
C2 , Z4 , T3  | C2 , Z2 , A2, T1 , P3
C1 , Z1 , T4  | C1 , Z1 , A1, T2 , P1
…
C2 , Z4 , T4  | C2 , Z2 , A2, T2 , P1
C1 , Z1 , T5  | C1 , Z1 , A1, T2 , P2
…
C2 , Z4 , T5  | C2 , Z2 , A2, T2 , P2
C1 , Z1 , T6  | C1 , Z1 , A1, T2 , P3
…
C1 , Z4 , T6  | C1 , Z2 , A2, T2 , P3
C2 , Z4 , T6  | C2 , Z2 , A2, T2 , P3

How to order the plane data

The order of the plane data is defined by the BinData or TiffData block, and is interleaved as it would be for the 5D view of the Z plane i.e. it is governed by the value of DimensionOrder on the Pixels element.

How to represent tiles

The Plane element stores the location of each tile.

e.g. Define four tiles 160 by 220 laid out as

---------
| A | B |
---------
| C | D |
---------

A   <Plane TheC="0" TheT="8"  TheZ="0" PositionX="0"   PositionY="0"   PositionZ="0.1"/>
B   <Plane TheC="0" TheT="9"  TheZ="0" PositionX="160" PositionY="0"   PositionZ="0.1"/>
C   <Plane TheC="0" TheT="10" TheZ="0" PositionX="0"   PositionY="220" PositionZ="0.1"/>
D   <Plane TheC="0" TheT="11" TheZ="0" PositionX="160" PositionY="220" PositionZ="0.1"/>

Specifying the position of each plane allows tiles to either form a mosaic as above or to overlap e.g.

---------
| A | B |
---[E]---
| C | D |
---------

E   <Plane TheC="0" TheT="12" TheZ="0" PositionX="80" PositionY="110" PositionZ="0.1"/>

Sample files

Sample files are available in the Modulo datasets section of the OME-TIFF sample data.