User Guide and Installation

It's often necessary to increase the amount of RAM Camino can use from the defaults. To do this, set the environment variable CAMINO_HEAP_SIZE to the number of megabytes of RAM you want to allow Camino to allocate, which must be less than your available physical RAM (a bit less than the total because some RAM is used by the system). For example, if you have 2Gb of RAM, you should safely be able to set CAMINO_HEAP_SIZE to 1800 or so.

Setting the memory allocation

It's often necessary to increase the amount of RAM Camino can use from the defaults. To do this, set the environment variable CAMINO_HEAP_SIZE to the number of megabytes of RAM you want to allow Camino to allocate. Please note that this must be less than your available physical RAM (actually a bit less than that because some RAM is used by the system). For example, if you have 2Gb of RAM, you should safely be able to set CAMINO_HEAP_SIZE to 1800 or so.

The exact procedure will depend upon your shell. Type

to tell what you have. If it's sh / bash, then type

If your shell is csh / tcsh, then type

You can set these values in your configuration files so that they remain in effect - please see the documentation for your particular shell for instructions on how to do this.

(:Title User Guide and Installation:)

Camino is a fully-featured toolkit for Diffusion MR processing and reconstruction, including diffusion tensor techniques, tractography and advanced algorithms for resolving non-Gaussian diffusion profiles, the so-called fibre-crossing problem. Camino is written entirely in Java, and is an open source development project, meaning that anyone can contribute to the project.

This document is a brief introduction to the Camino toolkit, the philosophy behind it and a jumping-off point for starting to use Camino in your own projects. We start by discussing the installation of Camino, including installation under Windows using Cygwin, and then discuss building and testing the toolkit and conclude with some simple ways to use Camino. Here we assume no prior knowledge of the systems side of things at all and (hopefully) will explain enough so that the remainder of the case-studies included on this website will be readily accessible for more complicated uses of Camino.

Installing Camino

Camino can be installed under Linux/Unix, Mac OS X and Windows. For more detailed instructions and requirements, click on the links below:
Installing Camino in Linux/Unix
Installing Camino in Windows
Installing Camino in OS X

Getting started using Camino

Camino works by assembling processing "pipelines" by stringing sequences of commands together to perform complex tasks. In essence, this involves sending data into one end, and outputting one or more files at the other end. Pipelines are constructed by using the shell "pipe" operator, which takes the output of one command and uses it as the input to another. The default input and output or commands are referred to as "standard input" and "standard output". The pipe operator is the "|" character (a vertical line, on UK keyboards it is usually shift-backslash) and is placed between the commands whose input and output is connected together:

In this way, any number of pipes can be used to form a sequence of commands, each performing one stage in a processing pipeline.

In the Camino documentation you will also find several other standard shell commands and operators that are commonly used. The most important of these is the cat command. cat (short for conCATenate) is a standard shell command that spools one or more files either into a new file, or to standard output.

will place the contents of myData1.Bfloat and myData2.Bfloat IN THAT ORDER in a file called allData.bfloat. In this case we have used the redirect operator ">", which takes the output of the cat command and "redirects" it into a file. without the redirection, cat's output will go to standard output.

In essence, a typical Camino pipeline has the following constituents:

As an example, we might take scanner-order data, send it through a command that shuffles it into voxel-order, send those voxels to a command that fits diffusion tensors, and then the fitted tensors to a command that calculates the fractional anisotropy in each voxel and sends those fractional anisotropies to a data file. By adding an analyze format header using an additional command we could then visualise this FA image using MRIcro, or similar program.

An example command pipeline for finding FA would be

The best place to look in order to get started with constructing Camino pipelines is the Camino man page. Man (short for manual) pages are a form of documentation accessible from the shell commandline. Man pages are accessed using the man command, and there is a man page for each command in the Camino toolkit. To access the Camino man page (assuming you've set up the MANPATH), type

Man pages for the other commands can be accessed in the same way, substituting the name of the command in question for "camino" in the above command.

Another good source of information is the Camino website. Several tutorials are included, which include step-by-step explanations of how to perform the studies described, and the pipelines involved in performing the analysis.

Hopefully you are now in a position to jump in and have a go with using Camino to perform an analysis. We hope you find the toolkit useful, and welcome suggestions and comments (email camino|at|cs.ucl.ac.uk) as well as bug reports and code submissions. We will always try to address queries and problems as quickly as possible -- Camino is under constant development and though we try to keep bugs to a minimum, inevitably some slip through the net!

Finally, if you use Camino in published work, please cite the following reference:

P. A. Cook, Y. Bai, S. Nedjati-Gilani, K. K. Seunarine, M. G. Hall, G. J. Parker, D. C. Alexander, "Camino: Open-Source Diffusion-MRI Reconstruction and Processing", International Society for Magnetic Resonance in Medicine, Seattle, WA, USA, p. 2759, May 2006

Command Reference

Below a list of some of the tools in Camino with a short description of what they do and some example command lines that run them. The man page for each tool contains a full description of how to use the program and a list of the command-line options.

cpstats

Does statistics on connection probability maps. For example, after tracking with the command:

cat A.inv1.watson.Bdouble | track -datadims 128 128 60 -voxeldims 1.7 1.7 2.3 -seedfile roi -watson -outputcp -outputroot A_oneDT_

cpstats -inputroot A_oneDT_watson_nonInt_1_ -operation max -outputfile maxroicp

The cpstats command finds the maximum connection probability to each voxel voxel from any of the seed points in the first ROI defined in the file roi.img. The output is an image maxroicp.{hdr, img}. As well as the maximum, cpstats computes the mean, minimum, or median.

datasynth

Creates synthetic diffusion MRI data from simple test functions or Monte-Carlo simulation.

datasynth -testfunc 1 -voxels 10 -snr 16 -schemefile A.scheme > /tmp/TenVoxP1.Bfloat

creates ten independent sets of synthetic measurements using the acquisition scheme detailed in A.scheme (see FILE FORMATS) assuming a zero-mean Gaussian model of particle displacements with diffusion tensor diag(17, 2, 2) * 10^-10 m^2 s^{-1} and signal to noise 16 in measurements with diffusion weighted factor b = 0.

datasynth -testfunc 3 -voxels 10 -snr 16 -schemefile A.scheme > /tmp/TenVoxP3.Bfloat

is similar to the first command above, but uses a mixture of Gaussians to model the particle displacement density, see datasynth man page.

Datasynth can also be used to run Monte-Carlo simulations of spins in a chosen diffusion environment. The command

datasynth -walkers 100000 -tmax 1000 -initial uniform -p 0 -geometry cyl_hex -G 0.022 -del 0.032 -Del 0.04 -cylinderrad 1E-6 -cylindersep 3E-6 -schemefile A.scheme > mc.bfloat

will perform a monte-carlo simulation of 100000 spins over 1000 updates. spins are initally uniformly distributed over the diffusion environment and their motion impeded by the presense of hexagonally packed cylinders parallel to the z-axis. Signals will be acquired in the directions given in the file A.scheme, but the q and b values in the schemefile will be overridden by the delta, DELTA and G values given on the command line. Output will be redirected to the file mc.bfloat.

dtfit

Fits the diffusion tensor to diffusion MRI data.

dtfit SubjectA.Bfloat A.scheme > DiffTensorA.Bdouble

fits the diffusion tensor to every voxel in the diffusion MRI data file SubjectA.Bfloat, which comes from the acquisition scheme detailed in A.scheme, and stores the diffusion tensors in DiffTensorA.Bdouble.

datasynth -testfunc 1 -voxels 10 -snr 16 -schemefile A.scheme | dtfit - A.scheme > DiffTensorTenVoxP1.Bdouble

fits the diffusion tensor to ten independent sets of synthetic measurements.

The script restore (see restore man page) also fits the diffusion tensor, but uses the robust fitting procedure in Chang et al MRM 53 2005.

dteig

Computes the eigenvalues and eigenvectors of diffusion-tensor data.

dteig < DiffTensorA.Bdouble > EigenA.Bdouble

computes the eigenvalues and eigenvectors from each diffusion tensor in DiffTensorA.Bdouble.

datasynth -testfunc 1 -voxels 10 -snr 16 -schemefile A.scheme | dtfit - A.scheme | dteig > EigenTenVoxP1.Bdouble

computes the eigensystem of the diffusion tensor fitted to ten independent sets of synthetic measurements.

Note that dteig also works on output of twotenfit or threetenfit.

dtlutgen

Calibrates the PDFs for PICo probabilistic tractography. This program needs to be run once for every acquisition scheme. It outputs a lookup table that is used by the dtpicoparams program to find PICo PDF parameters for an image. The default single tensor LUT contains parameters of the Bingham distribution and is generated by supplying a scheme file and an estimated signal to noise in white matter regions of the (q=0) image. The default inversion is linear (inversion index 1).

dtlutgen -schemefile A.scheme -snr 16 > bingham_Ascheme_snr16_inv1

Advanced users can control several options, including the extent and resolution of the LUT, the inversion index, and the type of PDF. See dtlutgen man page for details.

dtpicoparams

Uses a lookup table to associate PDF parameters with each voxel. The input is the tensor eigen system (the output of dteig). The eigenvalues are used to index the LUT. Given tensor data SubjectA.Inv1.Bdouble, dteig calculates the eigen system in each voxel, which is piped to dtpicoparams.

cat SubjectA.Inv1.Bdouble | dteig -inputmodel dt | dtpicoparams -inputmodel dt -lut bingham_Ascheme_snr16_inv1 > SubjectA.Inv1.bingpars.Bdouble

fa

Computes the fractional anisotropy of diffusion-tensor data.

fa < DiffTensorA.Bdouble > FA_A.Bdouble

computes the fractional anisotropy of each diffusion tensor in DiffTensorA.Bdouble.

datasynth -testfunc 1 -voxels 10 -snr 16 -schemefile A.scheme | dtfit - A.scheme | fa > EigenTenVoxP1.Bdouble

computes the fractional anisotropy of the diffusion tensor fitted to ten independent sets of synthetic measurements.

Note that fa also works on output of twotenfit or threetenfit.

linrecon

Performs a voxelwise linear reconstruction on diffusion MRI measurements. The script reads in a matrix with which to perform a linear transformation on the data in each voxel. The transformation can operate on the raw measurements, the log measurements or the normalized measurements with zero measurements removed. linrecon can be used to perform various common reconstruction methods, such as fitting the diffusion tensor, q-ball reconstruction, linear PASMRI, linear spherical deconvolution. The linear transformation matrices for some of these methods must be computed outside camino, however, in matlab for example.

modelfit

General model-fitting program that includes various options for fitting single or multiple diffusion tensors and other models to diffusion MRI data. See modelfit man page.

multitenfit

Fits different tensor models to the data in each input voxel according to a precomputed voxel classification, such as the output of voxelclassify.

picopdfs

Constructs a spherical PDF in each voxel for probabilistic tractography.

scanner2voxel

Converts scanner-order data to voxel order.

scanner2voxel -voxels 983040 -components 60 < ScannerOrder.img > VoxelOrder.Bfloat

converts scanner-order data file ScannerOrder.img, for which the measurement volume has size 128x128x60 (=983040) and the acquisition scheme acquires 6 measurements with b=0 and 54 diffusion-weighted measurements (total of 60 measurements), to voxel order (see File Formats).

sfpeaks

Computes peak directions from spherical functions, such as the output of PASMRI, MESD, QBall, etc.

sfplot

Creates images of spherical functions, such as the output of PASMRI, MESD, QBall, etc, in each voxel. For visualization of results.

shanis

Computes the anisotropy of spherical harmonic models of diffusion MRI data.

shfit

Fits the spherical harmonic series to diffusion MRI data.

voxelclassify

Uses the spherical harmonic analysis in Alexander, Barker and Arridge (MRM 48 2002) to produce a classification of the diffusion propagator in each voxel as isotropic, anisotropic Gaussian or non-Gaussian.

track

One of the tools for tractography. Does streamline tractography (deterministic or probabilistic). See the man page track(1) for detailed information on this tool.

Streamline tracts can be computed directly from the output of dtfit. For a data file A.Bfloat:

dtfit A.Bfloat A.scheme | track -inputmodel dt -datadims 128 128 60 -voxeldims 1.7 1.7 2.3 -seedfile subAROI -anisthresh 0.1 -outputroot A_oneDT_

where the -seedfile option specifies a Analyze hdr/img pair containing regions of interest. Any voxels within the seed image with an intensity value > 0 are considered seed points for streamlines. Voxels with the same nonzero intensity are part of a single ROI.

Non-tensor reconstruction data can also be used to compute streamlines. See the sfpeaks and track man pages

Probabilistic tracking requires a calibration step for each acquisition scheme. See track(1) and dtlutgen(1) for more information. A probability density function of the fibre orientation in each voxel of an image is created using the picopdfs program. See picopdfs man page.

threetenfit

Fits a three-tensor model to diffusion MRI data.

threetenfit SubjectA.Bfloat A.scheme > ThreeTensorA.Bdouble

fits the three-tensor model to every voxel in the diffusion MRI data file SubjectA.Bfloat, which comes from the acquisition scheme detailed in A.scheme, and stores the model parameters in ThreeTensorA.Bdouble.

datasynth -testfunc 4 -voxels 10 -snr 16 -schemefile A.scheme | threetenfit - A.scheme > DiffTensorTenVoxP1.Bdouble

fits the three-tensor model to ten independent sets of synthetic measurements.

trd

Computes the trace of the diffusion tensor.

trd < DiffTensorA.Bdouble > TrD_A.Bdouble

computes the trace of each diffusion tensor in DiffTensorA.Bdouble.

datasynth -testfunc 1 -voxels 10 -snr 16 -schemefile A.scheme | dtfit - A.scheme | trd > EigenTenVoxP1.Bdouble

computes the trace of the diffusion tensor fitted to ten independent sets of synthetic measurements.

Note that trd also works on output of twotenfit or threetenfit.

twotenfit

Fits a two-tensor model to diffusion MRI data.

twotenfit SubjectA.Bfloat A.scheme > TwoTensorA.Bdouble

fits the two-tensor model to every voxel in the diffusion MRI data file SubjectA.Bfloat, which comes from the acquisition scheme detailed in A.scheme, and stores the model parameters in TwoTensorA.Bdouble.

datasynth -testfunc 3 -voxels 10 -snr 16 -schemefile A.scheme | twotenfit - A.scheme > DiffTensorTenVoxP1.Bdouble

fits the two-tensor model to ten independent sets of synthetic measurements.

voxel2scanner

Converts voxel-order data to scanner order.

voxel2scanner -voxels 983040 -components 60 < VoxelOrder.Bfloat > ScannerOrder.img

converts voxel-order data file VoxelOrder.Bfloat, for which the measurement volume has size 128x128x60 (=983040) and the acquisition scheme acquires 6 measurements with b=0 and 54 diffusion-weighted measurements (total of 60 measurements), to scanner order (see File Formats).

Notation

The Camino documentation uses various symbols consistently.

N - The number of measurements excluding those with b=0. Often the number of gradient directions.

M - The number of measurements with b=0.

q - The wavenumber.

A*(q) - The measurement acquired with wavenumber q.

A(q) - The normalized measurement with wavenumber q; A(q) = A*(q)/A*(0).

File formats

Camino uses various file formats consistently.

Scheme files

The scheme file specifies the acquisition sequence used to acquire diffusion MRI data, which is usually required for reconstruction. There are now two scheme file formats that Camino commands understand. Version 0 is the original format that contains the diffusion time and a list of wavevectors (q_i). Version 1 contains more information, such as pulse widths, separations, etc, for more advanced techniques.

The version 0 scheme file contains the diffusion time and wave vectors for each measurement in the order the measurements are stored in the data file. The first value in the file is the diffusion time, usually in seconds although changing units will generally just affect the units of the output. The second value is the total number of measurements (including measurements with no diffusion weighting). Then the wavenumber, usually in m^-1, of the measurements are listed one by one; the x-component comes first, then the y-component, then the z-component. Every value is on a separate line, so the file looks like this:

diffusion time
number of measurements (N+M)
q_1X
q_1Y
q_1Z
q_2X
q_2Y
q_2Z
:
:
q_(N+M)X
q_(N+M)Y
q_(N+M)Z
Camino expects the unweighted measurements (|q| = 0) to be the first measurements in the version 0 scheme file.

If you are doing diffusion-tensor reconstruction, and you know only the "b-value", then choose an approximate diffusion time (e.g. t = 5.0 x 10^{-2} s) and set |q| such that b = |q|^2 t.

Camino users who scan with the twice-refocused spin-echo sequence of Reese et al (Magn Reson Med, 49(1), 177-82, 2003) typically set delta to the sum of the first two pulse durations, and DELTA to the time between the start of the first pulse and the start of the third pulse.

The handedness of the coordinate system used by the scanner may not agree with that used within Camino. A simple way to check for this is to fit the diffusion tensors and visualize the principal directions with the pdview program. If the anisotropy appears correct but the principal directions appear to be rotated by 180 degrees about the X, Y or Z directions, then the likely cause is that the gradient directions do not agree. This can be remedied by negating the relevant entries in the scheme file.

If the schemefile contains the diffusion time and wavenumbers in the default units (s and m^-1, respectively) then the fitted diffusion tensor has units m^2 s^-1. If the schemefile uses other units, the diffusion tensor is scaled accordingly. For example, if the diffusion time has units milliseconds and the wavenumbers have units millimeters^-1, the diffusion tensor has units mm^2 ms^-1. Reconstruction programs such as dtfit do not need to know the units.

The PICo calibration programs, including dtlutgen, require scheme files in the default units (diffusion time in seconds, wave vectors in m^{-1}). The datasynth program also requires the scheme to be specified using the default units. Wavenumbers in nonstandard units can be scaled using the command line option -qscale < value >. Diffusion times can be scaled with the -tauscale value option. These options allow scheme files with units to be used with PICo programs and datasynth.

Version 1 schemefiles have the following format:

VERSION: 1 nx_1 ny_1 nz_1 |G_1| DELTA_1 delta_1 TE_1
nx_2 ny_2 nz_2 |G_2| DELTA_2 delta_2 TE_2
:
:
nx_N+M ny_N+M nz_N+M |G_N+M| DELTA_N+M delta_N+M TE_N+M
where (nx_i, ny_i, nz_i) is the i-th gradient direction, |G_i| is the strength of the i-th gradient pulse, DELTA_i is the separation of the gradient pulses for the i-th acquisition and delta_i is the i-th pulse width; TE_i is the echo time for the i-th acquisition. The first line is required to indentify the file format. Like version 0 schemefiles, the format assumes a PGSE acquisition; for twice-refocussed acquisitions, follow the instructions above for the version 0 schemefile. Future releases will include schemefiles specifically for other pulse sequences, such as the twice-refocussed sequence. With version 1 schemefiles, there is now no requirement for all the b=0 measurements to be at the start of the list.

camino/PointSets/OldSchemeToNew is a script that converts version 0 schemefiles to version 1. See camino/test/bmx7_ED.scheme1 for an example of a version 1 schemefile.

Data files

Basic DTI processing can be done using Analyze data files and a scheme file. Please see the man page for analyzedti, which takes Analyze input and produces tensor information in Analyze format.

Camino uses big-endian data files with voxel ordering. Voxel-order data files store all of the measurements for the first voxel followed by all the measurements for the second voxel followed by all measurements for subsequent voxels. Scanner-order data-files store the whole volume of the first measurement followed by the whole volume of the second measurement followed by the whole volume of subsequent measurements. Analyze format diffusion MRI data files are commonly in scanner order. Such files must be converted to voxel order, using scanner2voxel, before inputting to the Camino tools.

By convention in Camino, we use the filename extension to indicate the data type in data files. The first letter is either "B" or "L" to indicate big-endian or little-endian data, respectively. The remainder of the extension is one of "byte" (8 bit, signed), "char" (8 bit, unsigned), "short" (16 bit, signed), "int" (32 bit, signed), "long" (64 bit, signed), "float" (32 bit, signed) or "double" (64 bit, signed).

Thus the extension ".Bfloat" indicates that the data file contains big-endian four-byte floating point data; ".Lint" indicates little-endian four-byte integer data.

Camino supports GZIP input of files ending in ".gz". GZIP output is supported by most programs, add the -gzip option to compress output.