Camino File Formats

On this page... (hide)

1. General I/O behavior
1. 1.1 Format identification
2. 1.2 Text files
3. 1.3 Byte ordering
4. 1.4 Data ordering
2. Native Camino data formats
3. DT
4. Multitensor
5. PDs
6. DTEig
7. Streamline fiber tract
8. Streamline VTK object

This page is a quick reference for the binary file formats produced by various Camino programs. Not all users will need to know the details of the native Camino data files, but it can be useful for troubleshooting and interoperability with other tools. If you are looking for information on scheme files, please see the scheme file page. For help importing scanner data into Camino, please see the I/O documentaion and the DTI tutorial.

1. General I/O behavior

Three types of data may be read or written by Camino: text, raw binary, and binary data in standard image formats such as NIfTI. We are working to incorporate greater NIfTI support into Camino. Other image formats may be supported, but for simplicity we will talk about NIfTI in contrast to raw data below.

1.1 Format identification

NIfTI and other standard formats are identified by file extension. A file will be read as NIfTI if it ends in .nii or .nii.gz. A file will be read as Meta if it ends in .mhd or .mha. Raw data is read according to internal defaults unless the user specifies otherwise. For example, diffusion tensor data is assumed to be double precision floating point, unless the user specifies a different type with the -inputdatatype option.

1.2 Text files

Floating point numbers in text files should be in UK / US format, 12.34 or 1.2345E2 will work.

1.3 Byte ordering

Camino raw binary data is always in network byte order (big-endian), following Java convention. No conversion is required to read little-endian NIfTI images. The endianness is specified in the header, and the image will be read correctly. Raw data imported to Camino from external programs must be big-endian, the conversion can be done with shredder.

All binary data written by Camino is big-endian unless otherwise required by a NIfTI header.

1.4 Data ordering

Raw data input to Camino must be voxel ordered. This means the voxel data is stored together, so that the ordering of data on disk is [voxel1_value1, voxel1_value2, ..., voxel1_valueN, voxel2_value1, ...]. Some image formats, including NIfTI, store things in volumetric order (we call this "scanner order" elsewhere on the site), where data is [voxel1_value1, voxel2_value1, ..., voxelN_value1, voxel1_value2, ...]. The main advantage of volumetric order is the ability to split the data set up and look at each component as an image. The main advantage of voxel ordering is the ability to split the data for parallel processing, and stream large data sets one voxel at a time.

You can convert between volumetric and voxel ordering as needed using image2voxel, scanner2voxel, and voxel2scanner. You can also use shredder to extract individual values from voxel-ordered data and voxel2image to export data back to an image or series of images.

2. Native Camino data formats

3. DT

The basic DT type for standard DTI.

Produced by: dtfit, modelfit, restore, wdtfit

Values per voxel: 8

Format: [exitcode, lnA0, dxx, dxy, dxz, dyy, dyz, dzz]

Command line params: -inputmodel dt

Can be converted to NIfTI with dt2nii, and from nifti with niftidt2camino.

Field definition:

exitcode	Encodes information about the reconstruction procedure. -1 means the voxel was skipped as background, 0 indicates success. Positive values mean something went wrong in the reconstruction or some data was modified or excluded. See modelfit for details.
lnA0	Log of the geometric mean of all measurements at b=0 in this voxel.
dxx	D(1,1) = dxx, component of the diffusion tensor.
dxy	D(1,2) = D(2,1) = dxy, component of the diffusion tensor.
dxz	D(1,3) = D(3,1) = dxz, component of the diffusion tensor.
dyy	D(2,2) = dyy, component of the diffusion tensor.
dyz	D(2,3) = D(3,2) = dyz, component of the diffusion tensor.
dzz	D(3,3) = dzz, component of the diffusion tensor.

4. Multitensor

Gaussian mixture model with maximum of N components per voxel. The maximum number of components, N, is specified by the -maxcomponents option on the command line - it is not encoded in the file. If "-inputmodel multitensor" is passed to a program, N is assumed to be 2 unless otherwise stated.

Produced by: modelfit

Values per voxel: 3 + 7 * N

Format: [exitcode, lnA0, numDTs, N * (mix_i, dxx_i, dxy_i, dxz_i, dyy_i, dyz_i, dzz_i)]

Command line params: -inputmodel multitensor [-maxcomponents 2]

Field definition:

exitcode	Encodes information about the reconstruction procedure. -1 means the voxel was skipped as background, 0 indicates success. Positive values mean something went wrong in the reconstruction or some data was modified or excluded. See modelfit for details.
lnA0	Log of the geometric mean of all measurements at b=0 in this voxel.
numDTs	Number of Gaussian components in this voxel, from 0 to N.
mix_i	Mixing fraction for tensor i, between 0 and 1. Sum of mix_i over all components is 1.
d**_i	Components of the diffusion tensor i, see DT model.

5. PDs

Peak directions of a spherical function with a maximum of N peaks per voxel. N is specified with the -numpds option, default N=3.

Produced by: sfpeaks

Values per voxel: 6 + N * 8

Format: [exitcode, ln(A(0)), numPeaks, consistent, meanF, stdF, N * (x_i, y_i, z_i, f_i, H00_i, H01_i, H10_i, H11_i)]

Command line params: -inputmodel pds

Field definition:

exitcode	Inherited from the input stream.
lnA0	Inherited from the input stream.
numPeaks	Number of peaks detected in this voxel, between 0 and N.
consistent	1 if number of peaks and peak directions are consistent when the peak search is repeated from a different starting point, zero otherwise.
meanF	Mean value of the spherical function.
stdF	Standard deviation of the spherical function.
[x,y,z]_i	Orientation of the peak i.
f_i	Value of the spherical function at the peak orientation.
H**_i	Hessian of f at the peak.

6. DTEig

Diffusion tensor eigen system data. Contains no exit code, nor any information on mixing fractions. If the data was produced from multitensor data with a maximum of N components, then there are N eigensystems output per voxel - though some will be zero in voxels where the number of tensors fit to the data is less than N.

Produced by: dteig

Values per voxel: N * 12

Format: [N * (l_1i, e_11i, e_12i, e_13i, l_2i, e_21i, e_22i, e_33i, l_3i, e_31i, e_32i, e_33i)]

Command line params: -inputmodel dteig

Field definition:

l_1i	Largest eigenvalue for component i.
e_11i	x-component of eigenvector corresponding to l_1.
e_12i	y-component of eigenvector corresponding to l_1.
e_13i	z-component of eigenvector corresponding to l_1.
l_2i	Middle eigenvalue for component i.
e_11i	x-component of eigenvector corresponding to l_2.
e_12i	y-component of eigenvector corresponding to l_2.
e_13i	z-component of eigenvector corresponding to l_2.
l_3i	Smallest eigenvalue for component i.
e_11i	x-component of eigenvector corresponding to l_3.
e_12i	y-component of eigenvector corresponding to l_3.
e_13i	z-component of eigenvector corresponding to l_3.

7. Streamline fiber tract

Produced by: track, procstreamlines

Not voxel based - contains N points

Format: [N, seedIndex, N * (x, y, z) ]

Command line params: -inputmodel raw, -outputtracts raw

Can be converted to VTK with vtkstreamlines

Field definition:

N	Number of points in streamline
seedIndex	Index to the point where tracking was seeded.
x	x-coordinate of point in physical space
y	y-coordinate of point in physical space
z	z-coordinate of point in physical space

The raw streamline format is always 32 bit float, regardless of the -outputdatatype option. The points are described in physical space according to the image header (normally NIFTI) that was used to generate the tracts, as documented on the NIfTI page.

8. Streamline VTK object

Produced by: vtkstreamlines

Not voxel based

Format: VTK PolyData

The vtkstreamlines program can convert tracts to VTK streamlines and optionally attach scalar values to each point. The tracts are stored in binary format as a PolyData object.