table of contents
LIPSIA The Lipsia data format
The Lipsia data format
This Lipsia data format originates from
the Vista data format which
was developed by Art Pope and David Lowe at the
University of British Columbia.
Lipsia employs a data file format that allows any collection of images to be stored in a single file.
This allows, for example, to keep anatomical and functional images in one file.
Each file is divided into two parts. The first part, which contains
descriptions of the objects in the file, is represented entirely in
ASCII so that it can be easily viewed and even edited using a text
editor. For example, one can add a comment annotating an image by simply editing this part of the file. The second part of the file holds the image pixel values.
The Lipsia (Vista) file names should always have the extension
'.v'. Anatomical and functional data can be viewed using the program 'vsview' which is only a simple
viewer for Vista files, however. A more sophisticated and flexible way
of visualizing Lipsia
data is using the viewers 'vlv'
and 'vlview'.
Display the ASCII header
Using our example data file 'structural.v', the ASCII header can be shown doing
more structural.v
Then, the following ASCII header appears on the screen:
V-data 2 {
image: image {
data: 0
length: 7180800
nbands: 170
nframes: 170
nrows: 240
ncolumns: 176
bandtype: spatial
repn: ubyte
voxel: "1.000000 1.000000 1.500000"
convention: natural
orientation: axial
}
The ASCII header contains the attributes of all images which are stored in the file. In our example 'structural.v', the file contains only 1 image. The image attributes shown in this example (data, length, nbands, nframes, nrows, ncolumns, bandtype, repn, voxel, convention, and orientation) are required for all images in Lipsia.
The attributes nbands, nrows, and ncolumns show the number of slices, rows, and columns of the image, respectively. The attribute bandtype shows if the bands contain slices (e.g. in structural images) or timesteps (e.g. in functional images). The attribute repn denotes the image data representation. Possible image representations are 'bit' (1-bit), 'ubyte' (8-bit integer), 'short' (16-bit integer), 'float' (32 bit floating point), and 'double' (64 bit floating point). In our example above, we have the representation 'ubyte', i.e., the image has integer values between 0 and 255.
The attribute voxel denotes the voxel size in mm (row, column, slice). In our example, we have a voxel size of 1x1x1.5mm. The attribute convention denotes the image convention. Possible values are 'natural' (L=L and R=R) and 'radiological' (L=R and R=L). Note that for Lipsia processing, all data must be stored in natural convention. The last attribute is the slice orientation which can be 'axial', 'sagittal', or 'coronal'. In our example, we have a set of 170 axial slices.
Changing the ASCII header
The ASCII header can easily be changed using a text editor.
One can add, edit, and delete optional attributes or comments
annotating an image by simply editing this part of the file,
e.g. using the editor 'joe'. However, a safer way of changing the
image attributes is to use the Lipsia program 'vattredit'. In our example, we could do the following:
vattredit -in structural.v -out outfile.v
-name "patient" -value "Paul Miller"
With this command we edit (or add) the attribute 'patient' and
give it the value 'Paul Miller'. Note that this is usually done for
all objects in the input file, unless an individual object is specified by
the option '-obj' when calling 'vattredit'. However, in our
example data the input file contains only 1 image. The resulting
header of 'outfile.v' thus looks as follows:
V-data 2 {
history: {
vattredit: "1.3; -obj -1 -name patient -value Paul Miller"
}
image: image {
data: 0
length: 7180800
nbands: 170
nframes: 170
nrows: 240
ncolumns: 176
bandtype: spatial
repn: ubyte
voxel: "1.000000 1.000000 1.500000"
convention: natural
orientation: axial
patient: "Paul Miller"
}
The changes in the header are marked in blue. After using Lipsia programs, the first part of the ASCII header shows the history of the processing steps. In our example,
the file 'outfile.v' is obtained after using the program 'vattredit'. The header shows the program version and all command-line options.
Anatomical MRI data
The Lipsia data format is able to store different images in a single file.
These images are 'objects' of the Lipsia data file. In our example
data set, the anatomical data file 'structural.v' contains only one image,
i.e., the file contains only one 'object'. This can be seen as
follows:
vsview -in structural.v
In anatomical data sets, bands correspond to image slices, whereas
rows and columns correspond to within-slice position. The anatomical
data set can also be viewed with
vlv -in structural.v
Important: Structural data must have the
orientation as shown in the figures above: Bands must be ordered
from dorsal to ventral, rows must be ordered from anterior to
posterior, and columns must be ordered from left to right. The latter
corresponds to the natural convention (L=L and R=R).
Functional MRI data
In Lipsia, (4D-) functional MRI data are organized slightly
different from structural data. This enables a particularly fast data
processing.
Functional MRI data are stored as a set of
several 'objects'. Each object represents an image slice,
where bands correspond to time steps and rows and columns again
correspond to within-slice position.
Our example data contains six functional slices, i.e., the file
'data.v' contains six 'objects' called "Image". Calling
'vsview -in data.v', the six
functional slices appear as images in the object list (see Figure
below).
Individual time steps of a functional data set can also be viewed like
this:
vtimestep -in data.v -out tmp.v -step 0
vlview -in tmp.v
Note that in the coronal and sagittal views only the six slices
are seen.
Important: Before preprocessing, functional data must have the
orientation as shown in the figures above: Objects must be ordered
from ventral to dorsal (i.e. upside down). When importing (unpreprocessed) raw functional volumes
using anatov or niftov, specify '-zflip true' in order to flip the slices.
In general, rows must be ordered
from anterior to posterior, and columns must be ordered from left to
right. The latter corresponds to the natural convention (L=L and R=R).
As described above, the header of the image file can be shown using the command 'more'.
In our example, the ASCII header of 'data.v' contains information of
all images, i.e., of all six axial slices.
V-data 2 {
image: image {
data: 0
length: 983040
nbands: 120
nframes: 120
nrows: 64
ncolumns: 64
bandtype: temporal
repn: short
voxel: "3.000000 3.000000 4.500000"
convention: natural
orientation: axial
MPIL_vista_0: " repetition_time=2000 packed_data=1 120 "
ntimesteps: 120
repetition_time: 2000
slice_time: 600
}
image: image {
data: 983040
length: 983040
nbands: 120
nframes: 120
nrows: 64
ncolumns: 64
bandtype: temporal
repn: short
voxel: "3.000000 3.000000 4.500000"
convention: natural
orientation: axial
MPIL_vista_0: " repetition_time=2000 packed_data=1 120 "
ntimesteps: 120
repetition_time: 2000
slice_time: 800
}
image: image {
data: 1966080
length: 983040
...
Because this dataset containes functional images, the attribute 'bandtype' has the value 'temporal' in all images.In addition to the required attributes described above, functional images must also contain the attributes 'MPIL_vista_0', 'ntimesteps', 'repetition_time', and 'slice_time'. The
attribute 'MPIL_vista_0' contains the repetition time (in our example 2000 ms) and the
number of functional scans (i.e. timesteps). In our example, we have 120 timesteps.
The image attributes 'repetition_time' and 'ntimesteps'
show also those numbers, i.e. the repetition time of 2000 ms and the number of 120 timesteps.
The attribute 'slice_time' shows the exact slice acquisition time after the trigger.
In our example, the first (most ventral) slice was acquired 600 ms
after the trigger. The second slice was acquired 800 ms after the
trigger, and so on.
List of image attributes
The following table gives a set of image attributes which are used in the Lipsia data format.
data | number | required | position of the image in the binary data |
length | number | required | length of the binary image data |
nbands | number | required | number of bands (anatomical image: slices,
functional image: scans) |
nframes | number | required | number of frames (anatomical image: slices,
functional image: scans) |
nrows | number | required | number of rows |
ncolumns | number | required | number of columns |
bandtype | spatial, temporal | required | type of bands,
e.g. 'spatial' in structural images, 'temporal' in functional images |
repn | bit, ubyte, short, long, float, double | required | image
representation, i.e. ubyte (8bit) has gray values between 0 and 255 |
voxel | 3 numbers | required | image
voxel size (row, column, and slice thickness) |
convention | natural, radiological | required | image
convention ('natural' convention is required by many Lipsia programs) |
orientation | axial, sagittal, coronal | required | slice
orientation |
MPIL_vista_0 | text | required in functional data | text containing
repetition time and the number of scans |
ntimesteps | number | required in functional data | number of functional scans
(timesteps) |
repetition_time | number | required in functional data | repetition time in ms |
slice_time | number | required in functional data | slice acquisition time in ms
(after trigger) |
ca | 3 numbers | required in Talairach space | position of commissura anterior
in voxels |
cp | 3 numbers | required in Talairach space | position of
commissura posterior in voxels |
extent | 3 numbers | required in Talairach space | extent (size)
of the brain in mm |
fixpoint | 3 numbers | required in Talairach space | fixpoint of
the image in voxels |
talairach | atlas, neurological | required in Talairach space |
type of ca/cp image orientation ('atlas' is required by many Lipsia programs) |
name | text | required by some programs |
name of the image |
modality | text | required by some programs |
image modality, e.g. zmap |
patient | text | optional |
name or description of the subject/patient |
birth | DD.MM.YYYY | optional |
birth date of the subject/patient |
sex | male, female | optional |
gender of the subject/patient |
device | text | optional |
name of acquisition device, e.g. Siemens Trio |
protocol | text | optional |
type of acquisition protocol, e.g. t1_mpr_axial_standard |
sequence | text | optional |
type of acquisition sequence |
CoilID | text | optional |
name or id of coil |
date | DD.MM.YYYY | optional |
date of image acquisition |
time | HH:MM:SS | optional |
time of image acquisition |
boundingBox | special format | optional |
image bounding box |
ori_nrows | number | optional |
number of rows in the original data set |
ori_ncolumns | number | optional |
number of columns in the original data set |
acquisitionOrientation | axial, sagittal, coronal | optional |
original orientation after image acquisition |
Max Planck Institute for Human Cognitive and Brain Sciences. Further Information:
lipsia@cbs.mpg.de
Copyright © 2007 Max Planck Institute for Human Cognitive and Brain Sciences.
All rights reserved.