• View
• Edit
• History
• Print

Frequently Asked Questions

This page contains answers to some frequently asked questions. Where possible, it provides links to more comphensive information and a brief outline of the solution. Many problems can be addressed by looking at the Camino user guide and tutorials on the main Camino website. These give a guided tour of the basics of Camino and some of its functionality. The Camino man page camino(1) also contains an overview of the various camino commands and information on how to use them.

Platform

1. Does Camino work on Windows?
2. I've installed Cygwin and Java but I still can't run Camino. What's wrong?

Usage and Publication

1. Can I publish work that uses Camino?
2. Can I use Camino in commercial work?
3. Do I need to know how to use Java in order to use Camino?
4. What versions of Java are supported?
5. Can I modify or add to Camino?
6. Do I need to upgrade to a new version of Camino every time the version number on the website changes?

Running Camino

1. How fast is Camino?
2. How can I stop camino producing all those "INFO:" entries on the commandline?
3. I get an error message like 'Exception in thread "main" java.lang.OutOfMemoryError: Java Heap Space'
4. When I try to run something, it crashes immediately with the error "Could not create the Java virtual machine"
5. How do I...?
6. I typed a command but nothing seems to be happening...
7. I think something has gone wrong...
8. What is shredder and what is it for?
9. I am running Camino on a large Sun cluster and everything is running very slowly. When I check what processes are running, I find that there are hundreds of Java proceses running. What should I do?

Data

1. What data formats does Camino support?
2. How can I convert camino data files to images in Analyze format?
3. Can I have a copy of the data you used?
4. What coordinate system is used for images?

Scheme Files

1. What is a scheme file?
2. How do I make a schemefile?
3. Which scheme file format is right for me?
4. The Camino scheme file requires |q| and DELTA (the diffusion time). We are not using a standard pulsed-gradient spin-echo sequence, so what values should we use?
5. My fractional anisotropy map looks OK, but I can't do any tractography. What's going on?
6. The colour-coded anisotropy map looks OK, but the principal directions are wrong. How can I fix this?

In the future

1. Will new methods, algorithms and techniques be added to camino?

Support

1. What support do you offer?

Platform

1. Does Camino work on Windows? Yes, but the shell scripts won't work in the normal Windows environment. Camino will work normally with Cygwin.
2. I've installed Cygwin and Java but I still can't run Camino. What's wrong? Firstly, check that you have followed all the steps in the installation section of the user guide. Common problems include only installing the Java Runtime Environment (JRE) from Sun. Camino requires the full Java software developer's kit (SDK) to be installed, or not adding the java SDK installation folder to your Windows path environment variable. See the user guide for details.

Usage and Publication

1. Can I publish work that uses Camino? Absolutely yes! Camino is intended to be a research tool and we hope that you will be able to use it in many of your studies. If you use Camino in published work, we ask that you cite the Camino 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", 14th Scientific Meeting of the International Society for Magnetic Resonance in Medicine, Seattle, WA, USA, p. 2759, May 2006. The home page contains a list of other relevant citations for specific techniques implemented in Camino. Please note that because Camino is a research tool, it is not intended as a clinical tool.
2. Can I use Camino in commercial work? Potentially, yes but please contact the Camino team if you want to involve Camino with commercial work in any way.
3. Do I need to know how to use Java in order to use Camino? No. However, you do need to ensure that the Java programs are available to the shell, but aside from that, you do not require any knowledge of Java. The programs java and javac must be on the PATH. See the Camino user guide for details.
4. What versions of Java are supported? Camino will run on Sun Java version 1.5 or later. See the Related Links page for a link to the Sun Java web page where you can download Java for free. Note that you need the SDK to build Camino. The Java Runtime Environment includes the java program but not javac, which the camino installation requires.If you are not sure which version of Java you are running, type java -version to find out.
5. Can I modify or add to Camino?Camino is open-source software and as such you are free to modify the source code in any way you like. The code is fully documented and it is possible to construct Javadoc from the comments in the usual way. If you have implemented something that you think would be useful to other people, or have a suggestion for making Camino better please contact the Camino team about including it in the repository.
6. Do I need to upgrade to a new version of Camino every time the version number on the website changes? No. The Camino version number on the website is the current version of the code repository, and changes every time any change is made, however small. The majority of changes made are bug fixes or other small changes and are not important to the majority of users. Periodically, we add new functionality or make other changes that are of wider interest, and these changes will be announced on the camino-users mailing list. By adding yourself to the list, you will receive these updates and be able to decide if you want to upgrade or not.

Running Camino

1. How fast is Camino? Camino is designed to be as numerically efficient as possible, but some processing tasks are more computationally intensive than others. Fitting the diffusion tensor to full brain data is a comparitively fast operation (a minute or so on a fast PC), whereas performing a non-linear reconstruction such as PAS-MRI could potentially take days.
2. I get an error message like 'Exception in thread "main" java.lang.OutOfMemoryError: Java Heap Space' Sometimes a command will require more memory tham is allocated to it by default. You can increase the amount of memory Camino programs can allocate by setting the CAMINO_HEAP_SIZE variable to some number (in Mb), eg CAMINO_HEAP_SIZE=1024 for 1Gb of RAM. This number must be less than your actual allocatable system memory. If you have 2 Gb RAM, then the maximum value is about 1800, but you probably want less than this for most apps.
3. When I try to run something, it crashes immediately with the error "Could not create the Java virtual machine" This often occurs when a Camino command tries to allocate more RAM than is available on the system. The message should be preceded by "Could not reserve enough space for object heap" if this is the case. This has been fixed in the current version, programs will not try to allocate more RAM than is available.
4. How can I stop camino producing all those "INFO:" entries on the commandline? Camino uses Java's JLogging functionality to record messages of different levels of importance in different ways. All messages produced by the system are given a level of importance and logged accordingly, messages to the commandline are shown if they have "INFO" prority or higher. The minimum logging levels are set in the logging.properties file in the camino root directory. To change them, load this file into your favourite text editor, and scroll down to the line that says
   
   # Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter (this is line 46 in an unaltered file).
   
   To prevent INFO level messages appearing on the commandline, change the line
   java.util.logging.ConsoleHandler.level = INFO
   to
   java.util.logging.ConsoleHandler.level = WARNING

WARNING is the next highest level of logging priority above INFO. The highest level of all being SEVERE, which will mean only messages associated with error that prevent the execution of a camino command will be logged.In addition to the console output of messages, camino also creates a log file, containing all messages produced by camino. This file will appear in the camino root directory each time camino is run, and is often useful when reporting bugs or difficulties with using camino. The logging level of the file can be set independently of the console output level. By keeping the log file level at INFO the INFO level output will still be record.
5. How do I...?There are lots of ways to learn how to use Camino. A good place to start is with the user guide and Camino tutorials. These include:Detecting crossing fibres, Using Camino for tractography, Running PASMRI in parallel, Data Synthesis, Spatial normalisation using FLIRT with diffusion tensor reorientation. These contain getting started information step-by-step examples of performing common tasks with Camino. If you have any more ideas for tutorials, please take advantage of the wiki format and contribute!
6. I typed a command but nothing seems to be happening...Most of the time, camino commands are not designed to work by themselves and are instead strung together into a pipeline. Simply typing a command in isolation will sometimes do nothing at all (for example, typing "dtfit" will not, by itself, start fitting diffusion tensors). If you are new to Camino, we recommand having a look through the user guide and tutorials on the main camino website. These give a guided tour of the basics of Camino and some of its functionality.If you are still having trouble with running your analysis, see the next question...
7. I think something has gone wrong...If your Camino pipeline crashes, it will give a java exception and code trace. This will be sent tot he command line and to the runtime log file. If you encounter an error like this you should contact the Camino team, making sure you let us know what you are trying to do, the exact command pipeline you have run and a copy of the error you have received. Whilst we make every effort to eliminate bugs and to fully test every part of camino, sometimes unforseen circumstances cause problems to occur. We will try to remedy any bugs you find as quickly as possible.
8. What is shredder and what is it for?shredder is a camino command that reorders and selectively reomves data, sending the result to standard out. It has many uses, the most common being to switch the endianness of data. shredder works with repeating blocks of data. The command takes three parameters, each representing a number of bytes: an initial number of to skip, the number to extract and output and the sixe of the block. shredder l m n will process a binary file by skipping the first l bytes, extracting the next m and then skipping the next n. By specifying a negative number for m, the endianness of those bytes will be swapped. It will keep going until there is no more input data.For more information, see the shredder man page. is also used in the tractography tutorial on the main camino web page.
9. I am running Camino on a large Sun cluster and everything is running very slowly. When I check what processes are running, I find that there are hundreds of Java proceses running. What should I do?This is an issue with Java. The Sun Java Virtual Machine (JVM) starts one Garbage Collector (memory manager) thread per CPU per machine. On a large cluster with mutliple processors this can become overly demanding and lead to a significant overhead during execution. To prevent this from happening, you need to add a command line option to the JVM for each command you are running. This is quite simple to do. Firstly, open the command file (these are found in the Camino bin/ directory) you need to change in your favourite text editor. Then locate the line that begins "exec java", this should be the last line in the file. Finally, add the option -XX:ParallelGCThreads=8 immediately after the word java. For example, if you want to change the reorient command, change the line exec java -Xmx${MAXHEAPSIZE}M -Djava.util.logging.config.file=${SCRIPTDIR}/../logging.properties apps/Reorient $* so that it reads exec java -XX:ParallelGCThreads=8 -Xmx${MAXHEAPSIZE}M -Djava.util.logging.config.file=${SCRIPTDIR}/../logging.properties apps/Reorient $* (don't insert any line breaks, keep everything on one line)

Data

1. What data formats does Camino support? Camino will read diffusion-weighted data in Nifti or Analyze format or in raw format. The first step in a data analysis pipeline is to convert the input data into big-endian, voxel ordered format. This is different to the image-order in which data is typically produced by scanners. Please see the tutorial on importing raw data. Certain programs that operate on images, such as track, procstreamlines and pdview will read Analyze, NIFTI-1 or MetaIO (ITK) images. Please see individual man pages for more information.Diffusion tensors in NIFTI-1 or ITK format may be converted to Camino format with the niftidt2camino or metadt2camino commands.
2. How can I convert camino data files to images in Analyze format?If the image contains one value per voxel, then you only need to make a header and move / copy / symlink the data to a file with a .img extension. See the analyzeheader(1) manpage (man -M man analyzeheader)for details. If there are multiple values in the file and you want to extract one, use the camino command shredder to extract the data you want.To make a multi-component 4D Analyze file from a Camino file, use voxel2scanner to make the img file and analyzeheader to make the hdr file. You will need the -nimages option to tell analyzeheader how many volumes are in the output image. See the man pages voxel2scanner(1) and analyzeheader(1) for more details.If you have Analyze data and you require diffusion tensor information in Analyze format, you may use the analyzedti command. Given the data and scheme file, it will produce Analyze images of each diffusion tensor component, the eigenvalues, trace and fractional anisotropy. See analyzedti(1) for more details.Some Camino programs produce Analyze images directly, for example connectivity images derived from probabilistic tractography are in Analyze format.
3. The Camino scheme file requires |q| and DELTA (the pulse separation). We are not using a standard pulsed-gradient spin-echo sequence, so what values should we use? If your scanner gives you a "b-value" for the sequence, then you should choose values such that |q|^2 * t is approximately equal to the b-value, where t is the diffusion time. In standard spin-echo, delta is the diffusion-weighted pulse duration and DELTA is the time between the beginning of the first and the beginning of the second gradient pulse. The modulus of the wavevector q=gd|G| where g is the gyromagnetic ratio of the proton multiplied by the gradient strength |G| and pulse duration d. The diffusion time t is usually set the the effective diffusion time t=D-d/3Camino users who scan with the twice-refocused spin-echo sequence of Reese et al (Magn Reson Med, 49(1), 177-82, 2003) typically set d to the sum of the first two pulse durations, and D to the time between the start of the first pulse and the start of the third pulse.
4. Can I have a copy of the data you used?In some cases, the data is available on the web (e.g. for the ) but more usually ethical constraints prevent us from making data generally available. We are an image analysis group without access to our own scanner. Because we rely on our collaborators for data to work from, we are bound by the ethics of each particular study.
5. What coordinate system is used for images?If the readValue() method reads the next value from the disk, then the image is read in the following order:for (z = 1:slices) for (y = 1:columns) for (x = 1:rows) image(x, y, z) = readValue(); end end endImage data is written in the same order.For display (in the pdview or sfplot programs) the image is rendered on the screen such the coordinates increase from left to right and bottom to top, so in an axial slice x increases from left to right and y increases from bottom to top.Fibre tracts are stored either as a list of voxels or as points in physical space. The origin of physical space is at the corner of the image at voxel (0,0,0) and the orientation is the same as the voxel coordinate system. The units of physical space are mm.Camino does not process images differently if the voxel spacing in an Analyze header is negative, but it will preserve this feature when processing Analyze images. For example, if you use an Analyze ROI for tractography with voxel sizes (-2, 2, 2) mm, PICo connectivity images (also Analyze) will have the same dimensions.Note that the coordinate system of the image may not be aligned with the coordinate system of the imaging gradients, see below.

Scheme Files

1. What is a scheme file?A scheme file is a text-file which contains the scan parameter settings used to acquire the data. It includes details such as b-value, diffusion time and gradient directions. These parameters are required by Camino to perform its analysis correctly.
2. How do I make a scheme file?The simplest way to make a scheme file is to use the pointset2scheme command. This takes a set of normalised gradient directions, listed in the order ... ddiffusion time and scan parameters and constructs a schemefile. Please see the pointset2scheme man page for more information.
3. Which scheme file format is right for me?Some applications (such as monte-carlo data synthesis) require more information about a pulse sequence than is contain in a standard scheme file. For this reason there are several version of the scheme file format that contain more detailed descriptions of the scan sequence.The standard scheme file format (V2) is enough for most applications, and if you are not sure which version you need it is best to start with this format. Scheme file V1 stores pulse duration delta, diffusion time DELTA and gradient intesity |G| explicitly, rather than just b value or gradient wavevector length. It also allows these parameters to vary in different directions. Scheme file V2 is designed to be similar to the FSL scheme, it contains gradient directions and b-values. See the man page for fsl2scheme for more information. Take care to specify the correct units for your scheme file. By default, Camino programs expect the b-values of the imaging scheme to be specified in units of s / m^2. If you use different units, you need to specify additional options to some Camino programs. The following programs require additional options if non-SI units are used: datasynth, dtlutgen, modelfit (sometimes), sflutgen, sfplot. Diffusion tensor reconstruction will work with different units, the units of diffusion coefficients depend on the scheme units. For example:
   
   # b = 1000 s / mm^2
pointset2scheme -inputfile PointSets/Elec030.txt -bvalue 1000 -addzeromeas 1 > b_in_s_mm2.scheme
# tensors have units mm^2 / s
cat data.Bfloat | dtfit - b_in_s_mm2.scheme > dt.Bdouble
# b = 1000 s / mm^2 = 1E9 s / m^2
pointset2scheme -inputfile PointSets/Elec030.txt -bvalue 1E9 -addzeromeas 1 > b_in_s_m2.scheme
# tensors have units m^2 / s
cat data.Bfloat | dtfit - b_in_s_m2.scheme > dt.Bdouble
   
   If you use a V1 scheme file, you must specify everything in standard units: meters, seconds, tesla. More information on scheme file formats and how to make scheme files can be found on the camino man page.
4. My fractional anisotropy map looks OK, but I can't do any tractography. What's going on?
5. The colour-coded anisotropy map looks OK, but the principal directions are wrong. How can I fix this? This happens when the coordinate system of the diffusion gradients do not agree with the scheme file. Any rotation of the gradient direction will re-orient the diffusion tensor but will not change its shape, so fractional anisotropy (FA) and trace of the tensor will be preserved, but tractography will fail. We advise checking the correctness of a scheme file using the pdview program. This program will display a colour-coded FA map with a line to show the principal tensor eigenvector. The colour coding is the standard combination of red for the x component, green for the y component, and blue for the z component. Because the colour coding is based on the magnitude of each vector component, the colour map does not change if we change the handedness of the coordinate system, for example if we replace every vector (x,y,z) with (x, -y, z). If the colour map looks correct but the principal eigenvectors are wrong, then one of the axes of the gradient coordinate system is flipped with respect to the scheme file. This can be fixed by telling pointset2scheme to flip the appropriate component. When dealing with a new imaging scheme, we usually check the genu of the corpus callosum in an axial view and the corticospinal tract in a coronal view.Beware that many scanners describe the gradient coordinate system in physical space, so the gradient directions will not change if the orientation of the image field of view is changed. We have had some success avoiding these issues by using the dcm2nii program that comes with mricron, which extracts the gradient directions and b-values from the DICOM headers and outputs them in FSL format (which can then be converted using fsl2scheme.

In the future

1. Will new methods, algorithms and techniques be added to camino? Yes they will. We are constantly working to expand the number of techniques that are implemented in Camino. As new successful algorithms develop, we will add them to Camino. Please send any suggestions for new functionality to the Camino team.

Support

1. What support do you offer? We offer documentation through man pages, tutorials and the other content on this site. You may also join the camino-users mailing list to keep up to date with the software and ask for help. The Camino developers also subscribe to the camino-users list. If you email the list, please include the commands you ran and any error messages.