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:

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. 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

cat data.Bfloat | bin/dtfit - A.scheme | bin/fa > fa.Bdouble.img

analyzeheader -datadims 128 128 60 -voxeldims 2 2 2 -datatype double -outputfile fa.Bdouble.hdr

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

Next steps

For more information and examples of the data I/O, please see the data import documentation. 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.

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.