|
|
Man /
CaminoContent-type: text/html caminoSection: User Commands (1)Index Return to Main Contents NAMEcamino - Overview of the Camino diffusion MR reconstuction toolkitDESCRIPTIONCamino 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:
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
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:
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
You should see something like
If you get something like
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:
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
Add the lines
where /path/to/camino is the full path to wherever you installed Camino. Then, open a new shell (or source your ~/.bashrc) and type
it should show you
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:
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:
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
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 supportThe Camino website 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.
NOTATIONThe 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 FORMATSCamino 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:
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:
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
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.
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.
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
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.
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.
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.
computes the eigenvalues and eigenvectors from each diffusion tensor in DiffTensorA.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.
computes the fractional anisotropy of each diffusion tensor in DiffTensorA.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.
If you have a series of 3D images, list them (in order) in a text file, one image per line
The cat command should show your images in correct order - check this! For example:
Then do
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.
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:
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.
computes the trace of each diffusion tensor in DiffTensorA.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. AUTHORSDaniel Alexander, Philip Cook <camino@cs.ucl.ac.uk>BUGS
Index
This document was created by man2html, using the manual pages. Time: 02:07:11 GMT, December 04, 2017 |