6D, 7D and 8D storage
=====================
.. topic:: 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.
::
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:
::
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
B
C
D
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
Sample files
------------
Sample files are available in the :ref:`modulo-datasets` section of the OME-TIFF
sample data.