Tutorial: data import to Camino

Converting DICOM data

Limitations on image format support in Camino

DWI data - supported image formats

Camino doesn't have any support for reading DICOM data, so we use dcm2nii, which is part of the mricron package by Chris Rorden. This program will give you a 4D nii file that you can feed to image2voxel. If possible, it will also output the b-values and b-vectors associated with the acquisition. You can convert these to a Camino scheme file with fsl2scheme. Note that the units of the b-values will be those used by the scanner, typically s / mm². Some Camino programs are sensitive to the choice of units (eg datasynth), so the default options may not work with some scheme files. You can avoid this issue by scaling your b-values into s / m² using fsl2scheme.

Dealing with image data

If you have data in Analyze, MetaIO, or NIfTI format, you can convert it directly to voxel order using image2voxel. This takes care of endianness, ordering, datatypes, and so on. For example, you can do

Here, image2voxel has read in the ScannerOrder.hdr image, taken care of the conversion to voxel order, and output voxel-order data in float format, the default expected by dtfit. And we don't need to worry about manually calculating the number of voxels and such.

Sometimes we may have or want 3D volumes instead of one 4D image. For example, we might want to coregister all the DWI volumes to correct for motion. You can split them with split4dnii. You can use a series of 3D images with image2voxel by writing a text file listing the 3D images in order. For example, split a 60-component image :

produces 3d_0001.nii through 3d_0060.nii. To use these images with image2voxel, do something like

Converting DICOM data

Camino doesn't have any support for reading scanner data, so we use dcm2nii, which is part of the mricron package by Chris Rorden. This program will give you a 4D nii file that you can feed to image2voxel. If possible, it will also output the b-values and b-vectors associated with the acquisition. You can convert these to a Camino scheme file with fsl2scheme. Note that the units of the b-values will be those used by the scanner, typically s / mm². Some Camino programs are sensitive to the choice of units (eg datasynth), so the default options may not work with some scheme files. You can avoid this issue by scaling your b-values into s / m² using fsl2scheme.

Limitations on image format support in Camino

Camino will read .nii, .hdr, or .mha files, but it will only read the raw data on its original voxel grid, which is assumed to be RAS, ie the data is packed on disk with x increasing left to right, y posterior to anterior, and z inferior to superior. We don't yet have the ability to apply header transformations or reordering of the data.

Raw data can be manipulated in various ways. You may need to change the ordering of data, the endianness, or the data type.

By default, DWI data is expected to be float - big-endian, 32-bit decimals. Programs such as scanner2voxel and modelfit expect float data by default. If you pass raw DWI data explicitly (eg, giving DWI data to track) it is also assumed to be float.

Processed raw image data is assumed to be double - big-endian, 64-bit decimals. Programs such as fa or dteig expect double data. You can change the input and output data types for most programs with -inputdatatype and -outputdatatype. These flags don't apply to non-image objects, such as fiber tracts. Some programs read images with headers (eg image2voxel), these do not need the -inputdatatype flag.

Data type

Probably the most common task is to re-order data from image to voxel order. In scanner order or image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order. You can get into and out of scanner order with the scanner2voxel and voxel2scanner commands. Since these commands expect to deal with mostly raw data, they read and write floats by default (see below). You can change this behaviour with -inputdatatype and -outputdatatype options. For example:

Data type

By default, DWI data is expected to be float - big-endian, 32-bit decimals. Programs such as scanner2voxel and modelfit expect float data by default. If you pass raw DWI data explicitly (eg, giving DWI data to track) it is also assumed to be float.

Processed raw image data is assumed to be double - big-endian, 64-bit decimals. Programs such as fa or dteig expect double data. You can change the input and output data types for most programs with -inputdatatype and -outputdatatype. These flags don't apply to non-image objects, such as fiber tracts. Some programs read images with headers (eg image2voxel), these do not need the -inputdatatype flag.

where -components specifies the number of volumes in the 4D input and -voxels specifies the number of voxels (ie, X×Y×Z, where X, Y, Z are the dimensions of the image).

Where -components specifies the number of volumes in the 4D input and -voxels specifies the number of voxels (ie, X×Y×Z, where X, Y, Z are the dimensions of the image).

Where -components specifies the number of volumes in the 4D input and -voxels specifies the number of voxels (ie, X×Y ×Z, where X, Y, Z are the dimensions of the image).

Where -components specifies the number of volumes in the 4D input and -voxels specifies the number of voxels (ie, X ×Y ×Z, where X, Y, Z are the dimensions of the image).

Where -components specifies the number of volumes in the 4D input and -voxels specifies the number of voxels (ie, X&<times>;Y&<times>;Z, where X, Y, Z are the dimensions of the image).

Where -components specifies the number of volumes in the 4D input and -voxels specifies the number of voxels (ie, X&<times>Y&<times>Z, where X, Y, Z are the dimensions of the image).

Camino doesn't have any support for reading scanner data, so we use dcm2nii, which is part of the mricron package by Chris Rorden. This program will give you a 4D nii file that you can feed to image2voxel. If possible, it will also output the b-values and b-vectors associated with the acquisition. You can convert these to a Camino scheme file with fsl2scheme. Note that the units of the b-values will be those used by the scanner, typically s / mm². Some Camino programs are sensitive to the choice of units (eg datasynth), so the default options may not work with some scheme files. You can avoid this issue by scaling your b-values into s / m² using fsl2scheme.

Dealing with image data

Probably the most common task is to re-order data from image to voxel order. In scanner order or image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order. You can get into and out of scanner order with the scanner2voxel and voxel2scanner commands. Since these commands expect to deal with mostly raw data, they read and write floats by default. You can change this behaviour with -inputdatatype and -outputdatatype options. For example:

Probably the most common task is to to re-order data from image to voxel order. In scanner order or image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order. You can get into and out of scanner order with the scanner2voxel and voxel2scanner commands. Since these commands expect to deal with mostly raw data, they read and write floats by default. You can change this behaviour with -inputdatatype and -outputdatatype options. For example:

If you have NIfTI tensor data, you can convert it with niftidt2camino:

Probably the most common task you'll need to do is to to re-order data from image to voxel order. In scanner order or image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order. You can get into and out of scanner order with the scanner2voxel and voxel2scanner commands. Since these commands expect to deal with mostly raw data, they read and write floats by default. You can change this behaviour with -inputdatatype and -outputdatatype options. For example:

If you have data in Analyze, MetaIO, or NIfTI format, you can convert it directly to voxel order using image2voxel. This takes care of endianness, ordering, datatypes, and so on. For example, you can do

The NIfTI tensor format contains a bit less information than the Camino format (ie, no exit code or unweighted signal), so these will be blank in the output unless you provide them on the command line. You can convert back to NIfTI format with dt2nii.

Sometimes we may have or want 3D volumes instead of one 4D image. For example, we might want to coregister all the DWI volumes to correct for motion. You can split them with split4dnii. You can use a series of 3D images with image2voxel by writing a text file listing the 3D images in order. For example, split a 60-component image :

produces 3d_0001.nii through 3d_0060.nii. To use these images with image2voxel, do something like

Camino doesn't have any support for reading scanner data, so we use dcm2nii, which is part of the mricron package by Chris Rorden. This program will give you a 4D nii file that you can feed to image2voxel. If possible, it will also output the b-values and b-vectors associated with the acquisition. You can convert these to a Camino scheme file with fsl2scheme. Note that the units of the b-values will be those used by the scanner, typically s / mm^2^. Some Camino programs are sensitive to the choice of units (eg datasynth), so the default options may not work with some scheme files. You can avoid this issue by scaling your b-values into s / m^2^ using fsl2scheme.

NIfTI tensor data

If you have NIfTI tensor data, you can convert it with @@niftidt2camino:

Camino doesn't have any support for reading scanner data, so we use dcm2nii, which is part of the mricron package by Chris Rorden. This program will give you a 4D nii file that you can feed to image2voxel. If possible, it will also output the b-values and b-vectors associated with the acquisition.

Camino doesn't have any support for reading scanner data, so we use dcm2nii, which is part of the mricron package by Chris Rorden.

Raw data can be manipulated in various ways. You may wish to change the ordering of data, the endianness, or the data type. If you have image data (eg Analyze, NIfTI), many of these tasks can be done for you, see the section on image2voxel below.

If you have data in Analyze, MetaIO, or NIfTI format, you can convert it directly to voxel order using image2voxel?. This takes care of endianness, ordering, datatypes, and so on. For example, you can do

Here, image2voxel has read in the ScannerOrder.hdr image, taken care of the conversion to voxel order, and output voxel-order data in float format, the default expected by dtfit. And we don't need to worry about manually calculating the number of voxels and such.

Limitations on image format support in Camino

Camino will read .nii, .hdr, or .mha files, but it will only read the raw data on its original voxel grid, which is assumed to be RAS, ie the data is packed on disk with x increasing left to right, y posterior to anterior, and z inferior to superior. We don't yet have the ability to apply header transformations or reordering of the data.

Following Java convention, Camino writes raw data in big-endian format. Camino will never write little-endian data except when writing images with headers that indicate endianness (eg, when writing an Analyze header). When reading data, Camino assumes big-endian input unless told otherwise by an image header. Therefore if the file ScannerOrder.img is little-endian, we need to reverse the endianness. Note that although ScannerOrder.img is part of an Analyze image pair, when we use it in the context above, it is just a binary file like any other. Therefore we use shredder:

The shredder command reads periodic chunks of data from binary files. With a negative read size, the endianness is reversed in the output. Note that we don't use any data type commands with shredder because it only deals in bytes. You read them, optionally reverse the order, then output. The short datatype is implicit in the chunk size (2 bytes). If we were reading floats, the chunksize would be 4. In general, you can reverse byte order in a file by doing shredder 0 -size 0, where size is 2 for short, 4 for int or float, 8 for long or double.

Probably the most common task you'll need to do is to to re-order data from image to voxel order. In scanner order or image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order. You can get into and out of scanner order with the scanner2voxel? and voxel2scanner commands. Since these commands expect to deal with mostly raw data, they read and write floats by default. You can change this behaviour with -inputdatatype and -outputdatatype options. For example:

Endianness

Following Java convention, Camino writes raw data in big-endian format. Camino will never write little-endian data except when writing images with headers that indicate endianness (eg, when writing an Analyze header). When reading data, Camino assumes big-endian input unless told otherwise by an image header. Therefore if the file ScannerOrder.img is little-endian, we need to reverse the endianness. Note that although ScannerOrder.img is part of an Analyze image pair, when we use it in the context above, it is just a binary file like any other. Therefore we use shredder:

cat ScannerOrder.img | shredder 0 -2 0 | scanner2voxel -voxels 983040 -components 60 \\
            -inputdatatype short > VoxelOrder.Bfloat

Probably the most common task you'll need to do is to to re-order data from image to voxel order. In scanner order or image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order. You can get into and out of scanner order with the scanner2voxel? and voxel2scanner commands. Since these commands expect to deal with mostly raw data, they read and write floats by default. You can change this behaviour with -inputdatatype and -outputdatatype.

Raw data can be manipulated in various ways. You may wish to change the ordering of data, the endianness, the data type, or extract a subset of the data set. If you have image data (eg Analyze, NIfTI), many of these tasks can be done for you, see the section on image2voxel below.

Probably the most common task you'll need to do is to to re-order data from image to voxel order. In scanner order or image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order. You can get into and out of scanner order with the scanner2voxel and voxel2scanner commands. Since these commands expect to deal with mostly raw data, they read and write floats by default. You can change this behaviour with -inputdatatype and -outputdatatype.

Dealing with image data.

Ordering data

Probably the most common task you'll need to do is to to re-order data from image to voxel order. In image order, multi-component images are stored as consecutive volumes. This is convenient for visualization, since you can easily render a particular 3D volume. It is inconvenient for parallel processing, as you must read the entire 4D image in order to get the components for a particular processing. Data in voxel order stores all components for a particular voxel together. Thus you can read the image one voxel at a time, or skip ahead to particular voxel, without reading the entire image into memory. Camino does most of its I/O in voxel order.

Image2voxel

Converting DICOM data

Raw data can be manipulated in various ways. You may wish to change the ordering of data, the endianness, the data type, or extract a subset of the data set.

Dealing with raw data

DICOM data

NIfTI support in Camino

NIfTI raw data

NIfTI tensor data

(:title Tutorial: data import to Camino:)

Coming soon