RooTrak Files

                                 RooTrak

1. What is RooTrak
------------------

RooTrak is an open-source tool, developed to aid in the separation
process of plant roots from the surrounding soil, in X-ray micro 
computed tomography (µCT) images. The tool facilitates the extraction
and visualisation of plant root systems and allows the quantification
of certain root system traits. 

An accompanying paper is available in Plant Physiology (2012).
http://www.plantphysiol.org/content/158/2/561


2. Version
----------

RooTrak 0.3.1-b1 beta


New from 0.2.1:

# General
- option for backward tracking added to extract upwards growing roots
- redisign of the code for the tracking tool, (volume renderer and measurement tool 
  have been taken over from version 0.2.1 - will be reworked in the next released version)
- allows to stop and resume the tracker with different settings, without having to 
  reload all the image data
- seed points can be removed if placed at a wrong position
- seed points can be added anywhere in the image data, not only in the frist image of 
  the stack 
- the 'Curvature' parameter is now called 'Smoothness'
- the 'Similarity' parameter has been reversed and works now as 1.0-Similarity

# Bug/Issue Fixes
- fixed endless loop for objects of 1 pixel size
- in case of object clashing and non-updating of the model destribution, the model
  of the dominant (bigger) object is used, rather the one that occures first by scanning 
  along the x/y direction
- added maximum number (1e3) of level set iteration, to prevent endless loops (should 
  be reached only on rare occasions)
- fixed invisible overlying mask of the current segmentation when 'white' objects are tracked



3. Installation Guide
---------------------

Download RooTrak from http://sourceforge.net/projects/rootrak/. Run the
rootrak_0.3.1_setup.exe and select the installation directory. The 
visual c++ 2008 redistributable package will be installed if not present.
Alternatively build RooTrak form the source code (see section 6).


4. User Guide
-------------

RooTrak is installed (if not selected otherwise) under %ProgramFiles%\RooTrak\ 
with a shortcut on the desktop and an entry in the start menu. Under the Tools
menu, there are three menu items; 'Tracker', 'Measurement', 'Volume rendering'.

# Tracker
  The tracking tool extracts the root system form non-root material. In the 
  dialog window select (double-click) the first image from the image stack 
  (preferable a lossless image format such as bmp, png, ...). In the Tracker
  tab set the parameters for curvature and similarity, and select (double-click)
  the output directory, where the image stack for the extracted root system 
  is saved. In the loaded and displayed image, select a target setting one or
  multiple seed points. Press the Start button to run the tracker.

# Measurement
  The measurement tool calculates a number of root system traits. In the
  dialog window select (double-click) the first image from the generated 
  segmentation stack. Under advanced options, choose an appropriate size 
  for the marching cubes algorithm. The smaller the cube size, the longer 
  it takes to calculate the triangle mesh and its vertex normals, but provides
  a more detailed visualisation of the extracted root system. The measured 
  results will be shown under the Measurement tab. Objects can be shown/hidden
  under the Objects tab. If the option is disabled, it means that the vertex 
  normals are still calculated. This might take several minutes, depending on 
  the size of the triangle mesh.

# Volume rendering
  Renders the root system using GLSL (works only on a GLSL compliant graphics
  card). In the dialog window select (double-click) the first image of the 
  data image stack and the first image of the generated segmentation stack.

For any three-dimensional rendering, the object is rotated by clicking and moving 
the mouse pointer, zoomed by scrolling the mouse wheel, and moved by pressing the 
Shift-key while clicking and moving the mouse pointer.  


5. Copyright and licensing information
--------------------------------------

Copyright (C) 2011-2013  Stefan Mairhofer

RooTrak is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

RooTrak is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.


6. Development
--------------

The source code is written in C++ and includes Visual Studio 2008 project 
files to compile for Windows. The Qt 4.8 framework is required for the 
compilation of the source code. The project is divided into following 
sub-solution. 

# Design
  This solution is the central part of RooTrak and includes the GUI as 
  well as the core libraries for accessing images, communicate between 
  processes and the definition of the plugin interface.

# Tracker
  This solution contains the technical aspects for the extraction of 
  the root system from its surrounding environment.

# Measurement
  This solution is responsible for the calculation of root system traits and
  the generation of the triangle mesh data.

# Volume
  This solution samples the data for volume rendering.  


7. Bug Reporting
----------------

Please drop an e-mail (sbxsm3@nottingham.ac.uk) to the developer to report 
any issues and bugs encountered with RooTrak.