Recent Changes - Search:

Homepage

This is the old Camino website, please visit our new page to download the code and get the latest documentation.









UCL MIG Home

UCL CS Home

UCL Home

edit SideBar

Man /

Camino

Content-type: text/html Manpage of camino

camino

Section: User Commands (1)
Index Return to Main Contents

 

NAME

camino - Overview of the Camino diffusion MR reconstuction toolkit

 

DESCRIPTION

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 shows discusses building and testing the toolkit as concludes 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.

System requirements

In order to run Camino you will need:


  A bash-like shell environment
  Oracle Java 7 SDK or later. Note that you will need the SDK (with the javac compiler) in addition 
  to the JRE. 
  Cygwin(if running under windows)

Installing Camino

This section discusses installing the toolkit under a linux/unix environment. To install Camino under windows some extra steps are required. These are described in the next section.

Download the latest version from Sourceforge - you will get a file that looks like


  camino-code-163f67cbf550560aa351b3d0a3bbbd7a22863cb4.zip

The string following code- is the commit hash. Make a note of this as it uniquely identifies the exact version of the code you are running.

We recommend moving the unzipped code to a directory named camino:


 $ unzip camino-code-commithash.zip


 $ mv camino-code-commithash camino

Next, compile and make the toolkit. Make sure you have the Oracle (Sun) Java 6 SDK (or later) installed. To check whether you have the correct environment, try


  javac -version

You should see something like


  java version "1.8.0_25"

If you get something like


  gcj: unrecognized option '-version'

then your javac is probably aliased to GCJ, the GNU Java compiler. Camino will not compile properly with GCJ, so you will need to install the Oracle java and ensure that the javac and java commands point to that implementation. Next, compile Camino:


  cd camino
  make

after this is completed, Camino is ready to use. For convenience, you can add environment variables in your shell to include the camino binary and man page directories. To do this in bash (used on Macs and many *nix systems), open your shell initialization file in your favorite editor, eg


  vi ~/.bashrc

Add the lines


  export MANPATH=/path/to/camino/man/$MANPATH


  export PATH=/path/to/camino/bin:$PATH

where /path/to/camino is the full path to wherever you installed Camino. Then, open a new shell (or source your ~/.bashrc) and type


  which dtfit

it should show you


  /path/to/camino/bin/dtfit

Installing under Windows using Cygwin

Although the individual components of Camino will run from a commandline under windows, in order to get the most out of Camino it is necessary to have a UNIX-like shell environment that allows data pipes and redirection. Without these facilities, it is extremely difficult to use Camino in the way it was designed.

Fortunately, it is extremely easy to install Camino under windows with Cygwin, this section explains the procedure step-by-step. Firstly, download the Cygwin installer from Sun is installed. Make sure you have the SDK as well as the usual JRE! This is not installed under windows as standard!

Once Cygwin and the Java SDK are installed on your system, check that the location of the Java SDK is added to you windows path. You can do this as follows:


  1) From the desktop, click start and right-click on "My Computer"
  2) In the "System Properties" window that appears, select the "advanced" tab
  3) Click the "Environment variables" button.
  4) Highlight the "path" variable and click the "edit" button
  5) If the path to your Java SDK is not in the list, add the FULL path to the end of the list, 
     using a semi-colon to separate it from the previous entry

Now start Cygwin and follow the instructions for installing Camino under linux/unix. For instructions on how to install geomview under windows and Cygwin, click here (SaVi is not required)

Getting started using Camino

Camino works by assembling processing "pipelines" by stringing sequences of commands together to perform complex tasks. This can either be done sequentially, writing results to intermediate files, or by using the Unix "pipe" operator to pass data from one program to another. In essence, this involves sending data into one end, and outputting one or more files at the other end. 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

See the man pages for the individual commands for more examples.

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.

 

Online documentation and support

The Camino website


  http://camino.org.uk 

has tutorials, documentation (including HTML man pages) and links to join the Camino users mailing list.

Bugs and feature requests can be added on Sourceforge.

 

Citations and publishing

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

There is a list of additional citations on the Camino web page for specific tools, please cite these where appropriate.

 

NOTATION

The Camino man pages use 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^tar(q) - The measurement acquired with wavenumber q.

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

b - The b-value.

 

FILE FORMATS

Camino uses various file formats consistently. A voxel-ordered raw-binary format is used internally for most data, to facilitate parallelization. There are tools to import and export data to NIFTI images. For more information on the data formats, see the man pages and the file formats page on the Camino website.

In addition to binary data, there are other supporting files, probably the most important of which are the scheme files.

Scheme files

The scheme file specifies the acquisition sequence used to acquire diffusion MRI data, which is usually required for reconstruction. There are multiple scheme formats, which contain different levels of detail about the acquisition. For most purposes, it is only necessary to specify the gradient directions and b-values.

Please see fsl2scheme(1) for instructions on converting FSL scheme files to Camino format.

Gradient directions

The orientation and 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, which pdview will do for you if you pass it the scheme file on the command line.

BVECTOR schemes

BVECTOR schemes are designed for users who only wish to specify gradient directions and b-values. The format is:


 VERSION: BVECTOR
 g_x g_y g_z b
 :
 :
 g_x g_y g_z b

where g is a gradient direction and b is a b-value. The gradient directions should be normalized to unity (they may be 0 for b=0 measurements).

BVECTOR is the only scheme format that is compatible with arbitrary units.

If the schemefile contains b-values with SI units (s / m^-2) 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 b-value is specified in the conventional s / mm^2, then the tensors will have units of mm^2 / s. Reconstruction programs such as dtfit are compatible with any choice of units.

Programs that synthesize data, such as datasynth and the PICo calibration program dtlutgen, assume scheme files in SI units (m^2 / s). You can use schemes in nonstandard units if you alter the units of the tensors used to generate the data. See the individual man pages for details.

STEJSKALTANNER schemes

These 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 format assumes a PGSE acquisition. All quantities must be in SI units.

Data files

Many Camino programs support NIfTI I/O as well as raw data. Conversion between the two formats is sometimes useful. The image2voxel, voxel2image, dt2nii, nii2dt commands are provided for this purpose.

When handling raw data, Camino expects 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.

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.

Note that this is just a convention, and the programs do not infer type from the file name unless it is a recognized header format like .nii or .hdr. With raw data, you must pass the appropriate options if you differ from the default data types. Raw data must be in big-endian format. It can be converted with shredder.

When you need to import or export image data, the headers set the endianness and data type, thus for example when you call image2voxel, you don't need to specify the data type or change endianness.

Camino supports GZIP input of files ending in ".gz". GZIP input must be from a file ending in ".gz", it cannot be from stdin. To send compressed data on stdin, do


  cat file.gz | gunzip -c | [Camino command]

GZIP output is supported via the -gzip option, you may also redirect standard output to gzip.

Command Reference

The summaries below are a few of the most commonly used 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.

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(1).

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(1)) 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.

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.

image2voxel

Converts DWI data in NiFTI or Analyze format into the raw format used by Camino.


  image2voxel -4dimage data.nii.gz | dtfit - A.scheme > dt.Bdouble

If you have a series of 3D images, list them (in order) in a text file, one image per line


  ls data/*.nii > imagelist.txt


  cat imagelist.txt

The cat command should show your images in correct order - check this! For example:


  dwi_0001.nii 
  dwi_0002.nii
  dwi_0003.nii
  dwi_0004.nii
  dwi_0005.nii
  dwi_0006.nii
  dwi_0007.nii

Then do


  image2voxel -imagelist imagelist.txt | dtfit - A.scheme > dt.Bdouble

To convert data from DICOM or other scanner formats to NIfTI, we suggest dcm2nii, part of the mricron package by Chris Rorden.

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(1).

multitenfit

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

procstreamlines

Process streamline output from track.


  track -inputmodel dt -inputfile dt.Bdouble -seedfile roi.nii -anisthresh 0.1 | procstreamlines \
  -waypointfile waypoints.nii -outputacm -outputroot subj_

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.

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 -seedfile subAROI.nii \
  -anisthresh 0.1 -outputroot A_oneDT_ 

where the -seedfile option specifies a NIfTI image 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 sfpeaks(1) and track(1).

Probabilistic tracking is available for both diffusion tensor and non-tensor models. See track(1) or the Camino web tutorials for more information.

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.

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.

 

AUTHORS

Daniel Alexander, Philip Cook <camino@cs.ucl.ac.uk>

 

BUGS


 

Index

NAME
DESCRIPTION
Online documentation and support
Citations and publishing
NOTATION
FILE FORMATS
AUTHORS
BUGS

This document was created by man2html, using the manual pages.
Time: 02:06:59 GMT, November 21, 2017

Edit - History - Print - Recent Changes - Search
Page last modified on October 26, 2009, at 02:41 PM