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
  Java 5 SDK or later. Note that you will need the SDK 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.

After downloading the archive, unpack the toolkit using:


  bunzip camino.tar.bz2
  tar xvf camino.tar

Next, compile and make the toolkit. Make sure you have Sun's Java 1.4 SDK (or later) installed. The SDK is required to compile Camino, it includes the JRE which allows it to run. To compile the toolkit, type


  cd camino
  make

after this is completed, Camino is ready to use.

Additionally, it is a good idea to set the environment variables in your shell to include the camino binary and man page directories. To do this in tcsh add


  setenv MANTPATH $MANPATH:camino/man/

and


  setenv PATH $PATH:camino/bin

to the end of your .cshrc file.

Or in bash


  export MANPATH=MANPATH:camino/man/

and
  export PATH=$PATH:camino/bin/

to the end of your .bashrc file.

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

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 from the Camino root directory, type


  man -M./man camino

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

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

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

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

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

A(q) - The normalized measurement with wavenumber q; A(q) = A^tar(q)/A^tar(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. Version 2 stores the gradient directions and b-values, in a similar manner to FSL's scheme format. We recommend using either version 1 or 2.

Schemes and units

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.

Programs that synthesize data, such as datasynth and the PICo calibration program dtlutgen, assume scheme files in the default units (diffusion time in seconds, wave vectors in m^{-1}). 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.

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

Version 0 schemes

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 you should use a version 2 scheme file. Alternatively, you can 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.

Version 1 schemes

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.

Version 2 schemes

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


 VERSION: 2
 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). Unlike version 0 schemes, this format does not require b=0 measurements to be the first measurements in the scheme; therefore you don't need to re-order your data, just include a line like


  0.000000   0.000000   0.000000   0.000E0

to represent a measurement at b=0.

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

Data files

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 or analyze2voxel, 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 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.

 

AUTHORS

Daniel Alexander <camino@cs.ucl.ac.uk>

 

BUGS


 

Index

NAME
DESCRIPTION
NOTATION
FILE FORMATS
AUTHORS
BUGS

This document was created by man2html, using the manual pages.
Time: 02:06:54 GMT, December 10, 2011