----- Numerical Fibre Generator v0.9.5 ------
Contents:
1. License Info (for full license see 'GNU_GENERAL_PUBLIC_LICENSE.txt')
2. Citation Info (if you use this software please note the recommended citation format below)
3. Overview
4. Data Structure
5. File Formats
- Data
- Parameters
- DW Gradient Directions/b-values
- MR Images
6. Tool Descriptions
- rand_init
- optimise
- subdiv
- trim
- mri_sim
- noisify
7. Compiling
8. Running
9. Displaying
- display_strands
- display_subvoxels
- display_colour_key
----------------
1. License Info
----------------
Created by Tom Close on 25/06/08.
Copyright 2008 Tom Close.
Distributed under the GNU General Public Licence.
'Numerical Fibre Generator' 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.
'Numerical Fibre Generator' 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 'Numerical Fibre Generator'. If not, see <http://www.gnu.org/licenses/>
----------------
2. Citation Info
----------------
If you use my software in a publication could you please include a line such as the following to cite my work:
"The numerical fibres and their associated DW-MR images were created using the 'Numerical Fibre Generator' (NFG)
(T. G. Close, Brain Research Institute, NICTA Victorian Research Laboratory and Department of Electrical and Electronic
Engineering, University of Melbourne, http://wwww.brain.org.au/software/) [1]." (see citation below)
I am currently working on a draft of a paper relating to this software and will provide details about its publication
when it is (hopefully :) ) accepted, on our website. So before using the reference below if you could check our
software page "http://www.brain.org.au/software/" or the NITRC project page "http://www.nitrc.org/projects/nfg/"
for an updated reference it would be greatly appreciated. Until then, please cite my ISMRM conference abstract below.
"T. G. Close, J-D. Tournier, F. Calamante, L. A. Johnston, I. Mareels and A. Connelly. Software Tool to Generate Complex
Structures fo Validation of Fibre Tracking. In Proceedings of the ISMRM, volume 16, page 83, 2008."
-------------
3. Overview
-------------
The numerical fibre generator is a collection of six 'command-line' tools: 'rand_init', 'optimise', 'subdiv', 'trim', 'mri_sim'
and 'noisify'. It is used to simulate the structural characteristics of human white matter and the diffusion-weighted MR
images that would arise from them.
Each tool performs one stage of processing. They are usually used in the sequence above (with the exception that 'optimise'
and 'trim' are usually used twice). However each tool can be used independently on appropriately formatted datasets.
------------------
4. Data Structure
------------------
The white matter structures are represented as collections of continuous 'strands'. These strands are defined as continuous
paths with nominal cross-sectional radii. These paths are the linear interpolation of a sequence of control points.
The start and end points are fixed (and are hence considered separately), while the rest of the control points are free to move
during the optimisation (see 'optimise' tool description below). In order to define the orientation a strand at its start and
end points, a 'pre point' and 'post point' are prepended and appended to the strand respectively. The line joining the pre
(post) and start (end) points defines the starting (ending) orientation of the strand.
------------------
5. File Formats
------------------
--- Data ---
The file format used to hold the data is quite straightforward. A 'strand collection' (the output at each stage) is stored in
a single directory containing a seperate text file for each strand. These files are named in the following format:
'strand_' + (strand index) + '-' + (strand bundle index) + '-r' + (strand cross-sectional radius) + '.txt'
The pre, start, control, end and post points are stored in the 'strand file' in that order. Each point is stored on a seperate
line with their three coordinates (x,y,z) seperated by single spaces.
The strand radii, coordinate positions, voxel size, ... are only relative to one another. Thus they can represent any scale
that is convenient (eg. mm, cm, ...).
--- Parameters ---
Parameters are stored in text files, with each parameter stored on a separate line. The format for each line is simply:
key value
The parameters 'key' (name) must be at the very beginning of the line, followed by a SINGLE space then the parameter's value
corresponding value. Any lines that do not start with a recognised parameter are ignored.
WARNING: Lines that start with a recognised key and then are not followed by a valid value (or a valid value not after a SINGLE
space) will not be checked!
--- DW Gradient Directions / b-values ---
DW gradient directions and their corresponding b values are also stored in text files. Each gradient direction/b-value pair is
stored on a separate line. The gradient direction is stored in cartesian coordinates (x,y,z) and is normalised once it is
read in. The format for each pair is:
X Y Z b-value
Each value is separated by a SINGLE space and the X coordinate must be right at the beginning of the line.
--- MR Images ---
The MR images simulated by NFG are stored in ANALYZE format, with the voxels ordered by increasing coordinates in the x, y then z
dimensions.
NB: While both image simulation tools ('mri_sim' and 'noisify') accept an 'output_format' parameter, the only recognised option
at this stage is 'analyze'. If you want to add a different image format then please use this parameter to signal it.
--------------------------------------
6. Tool Descriptions
--------------------------------------
Descriptions of what each tool does is given below. Each tool has a number of parameters that control aspects of its function.
Default parameters can be found in appropriately named text files (eg. 'rand_init_param.txt', 'optimise_param.txt' ... ) in the
directory './default_parameters' along with descriptions as to which aspect each parameter is controlling.
--- rand_init ---
Usage: arg[1]= output directory location
arg[2]= parameters file location
'rand_init' randomly initialises a collection of strands such that their start and end points lie on the surface of a sphere.
It randomly assigns each strand a radius and ensures that no strands overlap at the sphere surface. The strand radii are drawn
from a uniform distribution between a predefined upper and lower bound. However if, given this radius, the start or end points
of the strand overlap with a previously generated strand the new strand is rejected. This means that radii closer to the lower
bound are increasingly likely as the surface of the sphere is filled, thus skewing the distribution of strand radii towards the
lower bound.
Additionally, to ensure that the centre of the sphere is sufficiently filled, longer strands are preferred via a rejection
sampling scheme where new strands are only accepted if
dot_product(start_point, end_point) < X
Where X is a uniformly distributed random variable between -1 and 1.
--- optimise ---
Usage: arg[1]= input directory location
arg[2]= output directory location
arg[3]= parameters file location
'optimise' is the heart of the toolbox, it is the tool that ensures that there is minimal overlap between strands while
maintaining reasonable curvature and length.
It optimises the coordinates of the control points, while keeping the start and end points fixed, w.r.t. a cost function
(source code located at './c_source/optimise/cost_function.c') that penalises overlap between strands, strand length and strand
curvature. Depending on the complexity of the initial configuration the optimisation algorithm will usually converge to an
acceptable configuration within 100 iterations. Due to the difficulty in defining suitable stopping criteria that are
invariant with different numbers/sizes of strands, the optimisation algorithm is left to run until it can no longer reduce the
cost function.
After each iteration the new 'cost', its calculated gradient, the step size taken and so forth are displayed to screen, in
addition to a '.' being printed after every cost function call. When the optimisation can proceed no further it will stop and
save the new strand configuration.
--- subdiv ---
Usage: arg[1]= input directory location
arg[2]= output directory location
arg[3]= parameters file location
'subdiv' divides all the strands in the collection into thinner strands of the same radius, specified by an input parameter.
The new strands will be hexagonally packed across the cross-section of the original strands.
--- trim ---
Usage: arg[1]= input directory location
arg[2]= output directory location
arg[3]= parameters file location
'trim' trims all control points that lie outside of a specified radius (given as an input parameter). Strands that enter the
sphere more than once are split into multiple strands. The start (end) points of the strands are recalculated to be the point
where the strand enters (leaves) the sphere.
--- mri_sim ---
Usage: arg[1]= input directory location
arg[2]= output file location (extensions for header and data files will be appended)
arg[3]= imaging gradient directions (normalised cartesian coordinates) and b values
arg[4]= parameters file location
'mri_sim' simulates the DW-MR images that would arise from imaging the simulated white matter structure. Orientations of the
strands are first plotted onto a fine subvoxel grid to retain partial volume effects. A tensor model of diffusion is assumed
at each subvoxel element and the corresponding DW signal is calculated given a specified b-value. These signals are then
summed into the coarser voxel grid for the final DW-MR images (ie retaining the partial volume contribution to the signal within each voxel).
In addition to the images a statistical summary of the strand collection will be written to a file 'stats.txt' in a
subdirectory 'stats' of the strand collection directory.
--- noisify ---
Usage: arg[1]= input directory location
arg[2]= output directory location
arg[3]= parameters file location
'noisify' adds rician noise to the images with a standard deviation specified by an input parameter 'noise_level'.
NB: After running each tool the parameters passed to it and previous tools used on the data set are copied into a subdirectory
of the strand collection directory called 'parameters'
--------------
7. Compiling
--------------
All tools are known to compile with gcc v4.0. Before compiling you will need to install the GNU Scientific Library v1.9 (or
greater). It can be found at 'www.gnu.org/software/gsl/'.
There is a makefile in the base directory. You may need to alter the 'GSL_PATH' variable in the makefile to suit your
installation of GSL. Simply type 'make' to compile all the tools (NB: remember to type 'make clean' before making any
subsequent attempts).
After compiling the executables can be found in the 'bin' directory.
--------------
8. Running
--------------
A bash script called './run' will call each of the tools in the appropriate sequence to generate a unique white matter
structure and one set of noisy DW-MRI images from it. Each tool will use the parameters stored in separate appropriately named
files in the './default_parameters' directory.
The generated strand collections will be stored subdirectories of the './generated_collections' subdirectory by default
(specified by the OUTPUT_PATH variable in the script). The output from each run is stored in a directory named by the datetime
the strand collection was initialised ('yymmddHHMMSS' format). The strand collection at each stage in the process will be
stored in numbered subdirectories with the final images being stored in '8_noisify'.
--------------
9. Displaying
--------------
Also included is a MATLAB script used to display the generated strands.
--- display_strands ---
Usage: arg[1]= Either the directory name of the stored collection or a cell structure containing the loaded strands from a
previous call (return variable 1).
arg[2]= (optional) The number of divisions around the diameter of the strand. The default is 6, which corresponds to
a hexagonal cross-section.
arg[3]= (optional) A Nx3 matrix containing the colours in which the different bundles will be displayed.
arg[4]= (optional) The indices of the strands to be displayed.
Output: return[1]= A 4xN cell structure containing the strand data (to be used as arg[1] in subsequent calls of the function)
return[2]= A Nx3 matrix containing the colours of the strands displayed (to be used as arg[3] in subsequent calls of
the function to keep colours consistent)
Displays a 3D-rendered image of the strands in the collection.
--- display_subvoxels ---
Usage: arg[1]= The directory name of output of a 'mri_sim' call (needs the 'save_subvoxels' parameter to be set to 1 when
calling 'mri_sim').
arg[2]= (optional) The out of plane slice dimension
arg[3]= (optional) The slice number.
Displays a RGB direction-encoded fibre orientation plot at each of the subvoxels used to get the final voxel intensities. If
no value for slice number is supplied it will iterate through all the slides (press any key to move to next slice). Note that
the 'save_subvoxels' parameter needs to be set to 1 when calling 'mri_sim' and that if the resolution is reasonably high (eg.
300 x 300 x 300) then the file size can be quite large (> 600MB).
--- display_colour_key --
Usuage: arg[1] = An N x 3 'colour' matrix (as returned in the second output of 'display_strands')
Displays an image that can be used as a legend for the different bundle colours displayed in 'display_strands'