Getting started using Camino

Please see the installation instructions for help installing Camino.

To get started on analysis, please see the tutorials page, in particular the DTI tutorial introduces several concepts that are of general relevance to using Camino, and has an example DWI data set you can use to practice Camino functionality.

For file format information and examples of the data I/O, please see the data import documentation.

Manual pages for individual command can be accessed through man, or through the online listing here. Example usage is discussed in the man pages, and more detailed tutorials are available on this site.

Camino Unix pipelines

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:

command1 | command2

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.

cat myData1.Bfloat myData2.Bfloat > allData.Bfloat

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:

cat myData.Bfloat | formatting command | reconstruction command | analysis command(s) > myResults.Bdouble

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.

All of these stages can be split up and done independently. The use of pipelines avoids writing out intermediate data to disk, and saves typing of file names.

Pipelines involving NIfTI I/O cannot be piped in this way. Instead of using a pipe, we would write the output to an image with -outputfile and then pass it to the next command with -inputfile.

An example command pipeline for finding FA would be

image2voxel -inputfile dwi.nii.gz | dtfit - A.scheme | fa -header dwi.nii.gz -outputfile a_fa.nii.gz

Using Camino for research

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

Particular techniques in the toolkit are based on published works in the diffusion imaging literature. Please see the citations page for background and appropriate citations.