S martR T

version 4.1

Software created by Xavier Draye and Guillaume Lobet

[email protected]

Manual written and maintained by Guillaume Lobet

[email protected]

April 11, 2014

 SmartRoot is a semi-automated image analysis software which streamlines the quantifi-
cation of root growth and architecture for complex root systems. The software combines a
vectorial representation of root objects with a powerful tracing algorithm which accommo-
dates to a wide range of image source and quality. In its vectorial form, the root system is
treated as a collection of roots (possibly connected) that are individually represented as par-
simonious sets of connected segments. Pixel coordinates and grey level are therefore turned
into meaningful biological attributes such as segment diameter and orientation, distance to
any other segment or topological location. As a consequence, user interaction and data
analysis directly operate on root segments and are not hampered by the spatially discrete,
pixel-based nature of the original image. The software supports a sampling-based analysis
of root system images, in which detailed information is collected on a limited number of
roots selected by the user according to specific research requirements. SmartRoot is an
operating system independent freeware based on ImageJ and uses cross-platform standards
for communication with data analysis softwares.

More precise explanation about SmartRoot algorithm can be found in the following pa-
per:

A Novel Image Analysis Toolbox Enabling Quantitative Analysis of Root System

Architecture.
Guillaume Lobet, Loic Pagnd Xavier Draye.
2011, Plant Physiology, 157, pp 29-39

2
3
 CONTENTS

1 SmartRoot Installation 6
1.1 First steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 Windows installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Mac OSX installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 Linux installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2 Introducing SmartRoot 12
2.1 SmartRoot versus other root image analysis software . . . . . . . . . . . . . . 12
2.2 The windows of the ImageJ / SmartRoot user interface . . . . . . . . . . . . 13

3 Using SmartRoot 14
3.1 Quick start tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2 Opening images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.3 Preparing images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4 SmartRoot tools 15
4.1 Overview of SmartRoot Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 The Trace tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3 The Mark tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.4 The Registration Anchor tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5 SmartRoot window tabs 23

5.1 Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2 Root list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3 Linked files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4 Data transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.5 Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.6 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

6 Miscellaneous informations 32
6.1 Root growth measurement in rhizotrons . . . . . . . . . . . . . . . . . . . . . 32
6.2 About the SmartRoot datafile . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3 Using ImageJ functions and plugins in SmartRoot windows . . . . . . . . . . 34
6.4 Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

7 Troubleshooting 35

4
 LIST OF FIGURES

4.1 SmartRoot tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.2 Traced root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3 Attaching parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4 Crop children . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.5 Connecting roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.6 Touching roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.7 Escape centering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.8 Registration window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.1 Display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.2 Root list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3 Linking file tab in the SR window . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4 Linking files in SR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.5 Root Length Density export settings . . . . . . . . . . . . . . . . . . . . . . . 27
5.6 Plotting examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.1 Root growth drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.2 Root growth drawing and treatment . . . . . . . . . . . . . . . . . . . . . . . 33

5
CHAPTER 1
SMARTROOT INSTALLATION

1.1 First steps

1.1.1 System requirement
Memory: At least 1024 MB of RAM for a good functioning

Java: SmartRoot works with Java 1.5 or higher

Database (optional): SmartRoot can export data to .csv text files but also directly into
a database. For Windows we present how to setup a MS Access database connection.
For Mac OS X and Linux (Ubuntu), we present how to setup a MySQL connection.
People who does not have MS Access on Windows can follows similar steps as for
Linux and Mac OS to install a MySQL database.

1.1.2 Installation files

Inside the SmartRootSetup.zip file, you will find the following folders and files:

SmartRoot Quick Start.pdf This document. Helps you to quickly install SmartRoot.

SmartRoot User Guide.pdf Complete user guide to learn all the SmartRoot function-
alities.
Quick Start Images folder Four images to learn how to trace root with SmartRoot. In-
structions are written directly on the images.
SmartRoot folder The SmartRoot program in itself. Contains four .jar files: Smart Root.jar,
Image Explorer.jar, jcommon-1.0.16.jar, jfreechart-1.0.13.jar and mysql-connector-
java-5.1.7-bin.jar. This is the folder you will have to copy in the ImageJ folder (see
below).

6
CHAPTER 1. SMARTROOT INSTALLATION

1.2 Windows installation

1. Configure the database (optional)
2. Install ImageJ and SmartRoot
3. Use the Quick start images

1.2.1 Database installation and connection

To configure an ODBC data source that connects SmartRoot to a MS Access database:

1. Close the ImageJ program if it is running

2. Starts the ODBC administrator from the
Control panel > Administrative tools > ODBC administrator
3. Under the tab User DSN, click Add
4. A list of database drivers is displayed. Select Microsoft Access Driver, and click
Finish. You may need to contact your DB vendor if the driver is not in that list.
5. In the next dialog box, specify SmartRoot in the Data Source Name field. In the
Database area, click Create to create a new database. Choose the directory in which
you want to create the database, and name it SmartRoot.mdb (in the upper left text
field).
6. Click OK to validate and quit the ODBC administrator.

When you launch SmartRoot (see below), the following message is displayed in the
Results window of ImageJ if the connexion was successfully established:

SQL connection started on ODBC source SmartRoot

If the program failed to open the datasource, the message is:

The ODBC datasource ’SmartRoot’ was not found.

You will not be able to write to a database.

1.2.2 SmartRoot installation

1. Download and install ImageJ

2. Copy the SmartRoot folder in the Program Files > ImageJ > Plugins folder.
3. Open ImageJ and choose Plugins > SmartRoot > SR Explorer

ImageJ download:

http://rsbweb.nih.gov/ij/download.html
If you do not have Java installed, please choose a version of ImageJ bundled with Java

Important:
If you are using Windows 7, all the components you are using together (in our case, Java,
ImageJ and Access) have to be build on the same architecture (32bit or 64bit).
For instance, if your Access software is 64bit, please choose the ImageJ bundled with 64 bit
Java in the ImageJ download page.

7
CHAPTER 1. SMARTROOT INSTALLATION

1.3 Mac OSX installation

1. Install and configure MySQL database (optional)

2. Install ImageJ and SmartRoot

3. Use the Quick start images

1.3.1 MySQL installation and configuration

1.3.1.1 Installation
Download the latest MySQL version from:

http://dev.mysql.com/downloads/

Open the disk image then install MySQL by double clicking on the mysql-...-.pkg icon.
Also install the MySQLStratupItem.pkg and MySQL.prefPane.

Open the System Preferences>MySQL and start the MySQL server.

1.3.1.2 Configuration
Download the MySQLWorkbench from the following link and install it

http://dev.mysql.com/downloads/workbench

Open the application and click New Connection. Fill the fields as follow:

Connection Name: choose the name you want (ex: SmartRoot)

Connection Method: Standart (TCP/IP)
Hostname: localhost
Port: 3306
Username: choose the name you want (ex: root)
Password: leave it empty
Default Schema: leave it empty
Open the connection and create a new schema called SmartRoot by clicking the ’+’ sign.
Name the new schema SmartRoot and create it.
Click the Refresh button to see your newly created database.

1.3.2 SmartRoot installation

1. Download and install ImageJ

2. Copy the SmartRoot folder in the Applications > ImageJ > Plugins folder.

3. Open ImageJ and choose Plugins > SmartRoot > SR Explorer

ImageJ download:

http://rsbweb.nih.gov/ij/download.html

8
CHAPTER 1. SMARTROOT INSTALLATION

1.3.3 Connect SmartRoot to the database

Once you have installed SmartRoot, open it. The following message is displayed in the
Results window of ImageJ if the connexion was successfully established:

SQL connection started

If the program failed to open the datasource, the message is:

The specified datasource was not found.

You will not be able to write to a database.

If you see this error message, go in the SmartRoot window, choose the Settings tab and
find the SQL options panel. Fill the fields as follow:

Driver class name: com.mysql.jdbc.Driver

Connection URL: jdbc:mysql://localhost/SmartRoot
Connection user name: the username you choose previously
Connection password: leave empty
Press the Save Prefs then Restart server button. You should see the correct message
saying the connection started

9
CHAPTER 1. SMARTROOT INSTALLATION

1.4 Linux installation (Ubuntu distribution)

1. Install MySQL (optional)
2. Install ImageJ
3. Install ImageJ and SmartRoot
4. Configuring the database (optional)
5. Use the Quick start images

1.4.1 MySQL installation and configuration

1.4.1.1 Installation
In the terminal window type:

$sudo apt-get install mysql-server

$sudo apt-get install mysql-query-browser

While installing, you will be asked to setup username and password for your database
connection. Leave the default values.

1.4.1.2 Configuration
Open MySQL Administrator. To connect to the database fill the form as follow:

Server Hostname: localhost

Username: root
Password: Leave empty
In the MySQL Administrator window, choose Catalog in the left panel.
In the bottom left panel Schemata, right-click and choose Create Schema.
Name it SmartRoot

1.4.2 ImageJ installation

In the terminal window type:

$sudo apt-get install imagej

1.4.3 SmartRoot installation

Copy the SmartRoot folder from the SmartRootSetup folder you downloaded into the
usr/share/imagej/plugins/ folder

In the terminal window type:

$sudo mv /home/where_you_unzipped/SmartRootPlug/SmartRoot /usr/share/imagej/plugins

To launch SmartRoot open ImageJ and choose Plugins > SmartRoot > SR Explorer

Important:
Ubuntu use the Alt-key to grab and move windows. SmartRoot use the same key to
automatically trace roots. In order to use SmartRoot correctly, you have to change one
Ubuntu parameter:

Go to System > Preferences > Windows and set the Movement key to Super.

10
CHAPTER 1. SMARTROOT INSTALLATION

1.4.4 Connect SmartRoot to the database

Once SmartRoot is installed, open it.
The following message is displayed in the Results window of ImageJ if the connexion was
successfully established:

SQL connection started

If the program failed to open the datasource, the message is:

The specified datasource was not found.

You will not be able to write to a database.

If you see this error message, go in the SmartRoot window, choose the Settings tab and
find the SQL options panel. Fill the fields as follow:

Driver class name: com.mysql.jdbc.Driver

Connection URL: jdbc:mysql://localhost/SmartRoot
Connection user name: the username you choose previously (default = root)
Connection password: leave empty
Press the Save Prefs then Restart server button. You should see the correct message
saying the connection started

11
CHAPTER 2
INTRODUCING SMARTROOT

2.1 SmartRoot versus other root image analysis soft-

ware
SmartRoot differs from most root image analysis software in that it does not use traditional
raster-based morphological operations (such as skeletonizing) to extract roots structures.
SmartRoot uses vector-based and interactive algorithms to detect root objects. Each root
object consists of a polyline (an open polygon) with a name, and whose thickness (root
diameter) is estimated at each node. The polyline coordinates, diameters and other features
are stored in a DataFile in the XML format. Because it is vector based, SmartRoot has
a potential for higher resolution than raster-based. Because it is interactive, the human
eye and hands are involved in the tracing of roots, which makes the algorithm powerful yet
time consuming at the same time. Therefore, and although this problem could be worked
around in future versions, SmartRoot may not be suited to exhaustive analyses of whole
root systems comprised of hundreds of roots.

Another difference between SmartRoot and other systems is that the objects are dis-
played in different layers than the root image itself. The root image is therefore not modified
during tracing of roots, and it is possible to show/hide the various features of the objects:
root axis, root border, root area, root nodes (nodes of the polyline showing the root diame-
ter) or a ruler along roots. This also allows to remove or modify any root object.

12
CHAPTER 2. INTRODUCING SMARTROOT

2.2 The windows of the ImageJ / SmartRoot user in-

terface
The ImageJ window The native window of ImageJ. It allows the user to select SmartRoot
tools and to perform image manipulations on images during a SmartRoot session (see
6).

SmartRoot Explorer An ”image browser” which displays the list of image files in the
file system. Image windows are opened by double-clicking an image item in the list.
Several images can be opened concurrently. Images have to be open with this window
to be recognize by SmartRoot

Image windows Display the working images. To access functions of SmartRoot, one uses
the mouse right button within the area of an Image window, which brings up a con-
textual popup menu.
Results window Displays some notes / error messages on the execution of SmartRoot.

SmartRoot window Comprises seven tabs (see chap. 5 for detailed description).

Layout tab Select the attributes to be displayed.

Root List tab Visualize all the traced roots and marks of the image.
Linked files tab Import data from other image (see 5).
Data Transfer tab Send the data to an external database or to a .csv file (see 5).
Plot tab Plot several data of the current image (see 5.4.5)
Settings tab Change the settings such as the resolution or the root names
About tab Learn about SmartRoot

ImageJ Window

SmartRoot Window

Explorer Window

Image Window

Results Window

Figure 2.1: SmartRoot different windows

13
CHAPTER 3
USING SMARTROOT

3.1 Quick start tutorial

Together with SmartRoot comes a Quick start tutorial made of four images. All instructions
to analyze these images are written on the images themselves and, at the end of this short
tutorial, you will be able to use all the main functions of SmartRoot.

3.2 Opening images

To work on a root image, you have to open it with the Explorer Window of SmartRoot (see
figure 2.1, the window on the right side).

Important:
If you open an image with the ImageJ regular file opener (File>Open or drag and drop),
the image will not be recognize by SmartRoot and you will not be able to trace roots.

3.3 Preparing images

SmartRoot only processes grayscale (8-bit) images. If you attempt to open an image
that is not of grayscale type, a warning message will be displayed that the image will be
converted to grayscale and you will be invited to save the new (converted) image (which is
not mandatory if you prefer to reconvert the image every time you work on it).

The current implementation assumes roots have lower pixel (darker) values than the
background (the Status line in the ImageJ window indicates the value of the pixel under
the mouse cursor). If the value of root pixels appears to be higher than that of background
pixels, you should use the Edit > Invert command of ImageJ before proceeding to root
tracing.

Keep in mind that the screen grey level may be inverted relative to the pixel values,
depending on the current Lookup table (i.e. a table which assigns screen grey levels to pixel
values). The Image > Lookup Table > Invert LUT command of ImageJ allows you to
reverse the screen greyscale without changing the pixel values.

14
CHAPTER 4
SMARTROOT TOOLS

4.1 Overview of SmartRoot Tools

SmartRoot uses six different tools: the trace, the mark, the line, the zoom, the hand and the
registration anchor. To switch from one tool to another, use either the contextual (right-
button) popup menu inside the image or the corresponding icons in the ImageJ window.

(a)   (b)   (c)

  (d) (e)
  (f)
  (g)
Figure 4.1: SmartRoot tools. (a) Line tool (b) Zoom tool (c) Hand tool (d) Trace tool (e) Lateral trace
tool (f) Registration Ancor tool (g) Mark tool

Line tool If the user draw a line crossing several roots, he can use the function
Automatic drawing in the right-click menu. This function will start tracing all the
roots crossing the line.
Zoom tool The left and right mouse buttons zoom in and out, respectively. To switch
from the zoom tool to another tool, either use the ImageJ icons or press the escape
key (which brings you back to the crosshair tool).

Hand tool Moves the image in the window. When the crosshair or the zoom tool is active,
you can transiently switch to the hand tool by holding the space bar down (as in
Photoshop). This allows you for example to access the non visible part of a large
image while tracing a root.

Trace tool Used for all root objects manipulations (drawing, selecting; moving) (see sec.
4)

Lateral Trace tool Used to trace lateral roots along a traced first order root.
Registration Anchor tool Used to add anchor points that will be used to align time-series
of images.
Mark tool Used to add marks along roots. These marks can be exported all at once to
the database from the Data transfer tab of the SmartRoot window.

15
CHAPTER 4. SMARTROOT TOOLS

4.2 The Trace tool

4.2.1 Manual tracing procedure
Root tracing is best illustrated with the basic, most inefficient way (yet sometimes neces-
sary) of tracing a root, viz. tracing a polyline manually along the axis of the root, as you
would do with any drawing software.

Before tracing your first root, select the Trace tool (either from the popup menu
within your image, or from the toolbar of ImageJ) and make sure the Display nodes and
Display axis items of the Layers tab in the SmartRoot window are checked so you can
see what you are drawing.

To start tracing, place the cursor close to the base of the root (within the root) and click
the left button to insert a ”node” there. Then proceed drawing the polygon with succes-
sive clicks. Each node is displayed as a ”drop” symbol whose diameter approximates the
root diameter at the node location and whose orientation indicates the direction of draw-
ing. You will notice that SmartRoot always tries to keep the node that you are tracing in
the center of the root, even if the mouse if not in the center (see 4.7 to control this behavior).

To insert the last node of the polygon, make a double-click. By default, SmartRoot
assumes you have traced the root from the base to the apex. The root apex is represented
with a filled yellow circle. You are then invited to enter a name for that root (the reason
for this will be obvious later). If you press Cancel, the tracing will be discarded.

  Figure 4.2: Traced root

4.2.2 Semi-automated tracing procedure

SmartRoot offers more efficient ways to trace roots, in which algorithms attempts to trace
the root polygon by itself. The algorithms are semi-automated in that they still requires
some user input for each root. Semi-automatic tracing starts whenever the user press the
Alt key when inserting a node.
If you press the Alt key when creating the first node of a root, SmartRoot will trace a
new root in both directions from that node. Because the algorithm needs to guess the root
direction, it is recommended not to trace the first node just at the intersection between two
roots.
If you press the Alt key when you insert the nth node (n > 1) of a root (manual tracing),
SmartRoot switches to semi-automatic tracing and proceeds until it reaches the end of the
root.

16
CHAPTER 4. SMARTROOT TOOLS

4.2.3 Modifying a root

Once a root has been traced, it can be modified in a number of ways.

To move a single node, just click within the area of the node symbol and drag it with
the mouse to the desired location. If you hold the Alt key (semi-automatic) while releasing
the mouse button, the distal part of the root will be completely reconstructed (unless you
are moving the first node of a root, in which case SmartRoot elongates the root proximal to
that node).

The other modifications of root objects are requested by clicking with the right but-
ton on the root node to be modified (within the node symbol area) or anywhere in the root
to be modified (within the area enclosed by the root borders), then choosing the desired
action in the popup menu that shows up. This will bring up a popup menu whose first items
(unselectable, yellow background) indicates the name of the selected root, the name of its
parent (if applicable) and the ramification order of the root.

If you select a node:

Append nodes: this item will be selectable only if the selected node is either the first or
the last node of a root object. After selecting this item, the user is left as if he was
tracing the root in the manual tracing mode (with the possibility to connect the root
to the base / end of an existing root and that to switch to the semi-automated tracing
mode).

Split root: splitting a root actually creates two roots: the proximal part is stored in the
original root object, while the distal part is stored in a new root object with the default
name ”unnamed”.
Remove node: this will remove the selected node, linking (in any) the previous node to
the next node.
Remove all nodes (after): this item will discard all node located distal to the selected
node.
Remove all nodes (before): this item will discard all node located proximal to the se-
lected node.

If you select a root:

Bring to front: this item will bring the selected root to the front of the list of roots. By
default, every time a root is created, it is added at the front of the root list. Where
roots overlap, only the root in front of the others can be selected. This command (and
the next one) allows the user to move the selected root at the back or front of the root
list.
Send to back: this item will send the selected root to the back of the list of roots.

Find laterals: this item will check along the root axis if there is lateral roots. Newly
created laterals will be set as children of the selected root

Fast find laterals: Same function as Find Laterals, but using a other algorithm that is
faster, but a little less efficient.

Attach parent root: this item set a parent for the current root (see sec.4.2.5). SmartRoot
will display a list of all the available roots. The root closest from the base of the selected
root will be set as first choice. The root selected in the list will be highlighted in red
on the image (fig 4.3).

17
CHAPTER 4. SMARTROOT TOOLS

Figure 4.3: Attaching parent. The root we want to attach a parent to is the one displayed in yellow. The
red root is the one selected in the root list in the Attach parent dialog.

Detach parent root: this item remove the relationship between a root and its parent.

Detach children roots: this item remove the relationship between a root and all its chil-
dren.

Rename root: this item will bring a dialog box to change the name of the selected root.
Delete a root: this item will remove the whole root. If the root has child(ren), the user
will be asked if he wants to delete all the children or not. If not, the children will be
detached.

Reverse orientation: this item will reverse the root orientation, changing the root base
into the root apex and vice-versa.
Crop childrens: this item will cut all roots whose first node is located within the area of
the selected root at their intersection with the border of the selected root, as shown
on figure 4.4.

  (a)   (b)   (c)

Figure 4.4: Crop children. (a) Before cropping children (b) After cropping children (with nodes) (c) After
cropping children (without nodes)

18
CHAPTER 4. SMARTROOT TOOLS

4.2.4 Connecting two tracing

There may be cases where you need to join two root objects that should make a single root.

If you want to join two drawings A & B, make sure you the Trace tool is active, right-click
the end of A, select Append node and start adding nodes until you come close to the ”start”
of B, then add the last node of A using the right-click precisely on top of the first node of B,
and you are done. Note there is no requirement as to the orientations of A and B (you can
append A by its base or apex, to the base or apex of B). The orientation of the resulting
root will be that of A (you can reverse it as indicated in 4.2.3). If the final orientation is
A?B, the name of the resulting root will be that of A (and reverse).

On figure 4.5, the top root is being traced (4.5a) and an ultimate node is added onto the
first node of the bottom root, automatically joining the two roots (4.5b).

  (a)   (b)

Figure 4.5: Connecting roots. (a) Before connecting roots (b) After connecting roots

4.2.5 Topological informations

SmartRoot allow the user to set parent and children roots. Setting a root B as a parent of
a second root B means B was created by A and is connected to it.

To connect two root with a topological link, select the child root and right-click on it.
Choose Attach parent and select the parent root in the list. The selected root in the list
is highlight in red for better visualization. Once attached, roots of different ramification
orders are displayed in different colors. When the user delete a root which has children, he
will be asked if he wants to also delete the children. Stored topological informations are
insertion position, insertion angles and ramification density.

In order to decrease to time needed a lateral finding algorithm was implemented in

SmartRoot. To start the algorithm, right-click on a root and select Find laterals (see sec.
4.2.3). Settings of the algorithm could change from one image to the other. Information
about the settings can be found in the section 5.5.2

4.2.6 How to escape the centering mechanism

In semi-automatic tracing, SmartRoot detects situations where the root diameter suddenly
increases by a given factor (by default 1.6) during the tracing. This typically happens when
one reachs a region where the traced root comes so close to another root that it becomes
virtually impossible to distinguish the two roots (fig. 4.6a).

When this happens, the diameter is prevented to increase and keeps the same value as
that of the preceding node. As long as the next node diameter is more than 1.6 times that
of the preceding node (possibly frozen) the correction will hold. In this situation, nodes are
not anymore centered relative to the root object. Instead, they are aligned relative to the
closest border of the root(s), at a distance corresponding to the root (frozen) radius (fig.

19
CHAPTER 4. SMARTROOT TOOLS

4.6b).

  (a)   (b)

Figure 4.6: Automatic tracing with touching roots. (a) Two touching roots (b) Automatic drawing

The current implementation may fail in certain circumstances: if one of the roots is mak-
ing too strong a bend, the algorithm may sweep to the other root, as illustrated on figure 4.7a.

  (a)   (b)

Figure 4.7: Escape centering mechanism. (a) Two touching roots (b) Automatic drawing

When this occurs, the user will have to correct the tracing, typically by moving the first
”bad” node to its correct position, clicking the Alt key to tell SmartRoot to rebuild the root
from there.

For this reason, the user is left the possibility to request the ”diameter freeze” and ”align
to border” manually. To force the diameter of the current node to be equal to that of the
previous node, just hold the control key while adding or moving the node (in this case, the
node is placed at the exact position of the mouse). To force the current node to be aligned
relative to the closest root border instead of to the root center, just hold the shift key while
adding or moving the node.

The shift, control and alt keys can be combined in any way and their effects are
additive. Typically, to correct the root of the last illustration, just move the first badly
aligned node while holding the control, shift and alt keys together: the control key will
make sure that the node diameter is correct, the shift key will make sure that the node
is aligned to a border and the alt key will request that the rest of the root be re-traced
automatically.

On figure 4.7b is another example of combinations of the shift and control keys. The top
node is the first one, it uses the default centering mechanism. The second node was adjusted
to the right border (shift key). The third node was forced to have the same diameter as
the previous one (control key). The fourth node was forced to have the same diameter and
to be aligned on a border (shift + control keys). the last node was traced without any
modifier key.

20
CHAPTER 4. SMARTROOT TOOLS

4.3 The Mark tool: how to annotate roots and get all
measurements at once
When you select the Mark tool, a ruler line appears along the root axis which is the
closest to the mouse, orthogonal to the closest root axis and aligned on the mouse position.
The name of that root is displayed next to the mouse pointer (the label may not be dis-
played if the pointer is too far from all roots). A left-click will place a mark at this position.
Marks are tools to enrich the information stored in the image and that can be exported.
When adding a mark, the user will be asked to choose the kind of mark he wants to add.
Indeed, several kind exist, depending of the kind of information you want to add to the image.

Free Text. A single mark with a text field to annotate a specific point on a root (e.g.
broken root, unexpected curvature, ...).

Number. A single mark with a number field to annotate a specific point on a root (e.g a
date for time series, ). If other Number marks are present on the root, the default
value proposed for the mark will be set according to its longitudinal position on the
root.

Most distant lateral. A mark indicating the position of the most distant lateral of a root.
It is automatically updated whenever a more distant lateral is created.

Interval. Twin marks defining a region of the root presenting specific features (e.g. poorly
branched, cluster roots, ...).

Measure. The simplest mark in SmartRoot, which take measurement at its position (e.g.
root diameter, position on the axis, ...).

4.4 The Registration Anchor tool: Image Registration

When working with time series of images of root system grown in solid substrates, it
can be assumed that a root at time t will occupy the same 2D location at time t+1. In
principle, it should therefore be possible to re-use every root object traced at time t on the
image at time t+1 and, therefore, to avoid retracing the same roots for every image. Then,
tracing the growth increment would simply require an Alt-click (and short drag) on each
root apex with the Trace tool (which will automatically construct the apical root segment
grown between the two image acquisitions).

However, it is unlikely that the root material will be placed precisely at the same loca-
tion relative to the scanner or camera on every images. This would result in small transla-
tion/rotation/rescaling of the roots when comparing two different images. The correction
of these modifications is the object of image registration and is based on registration anchor
points that are precisely located on the two images and that can be used to estimate the
parameters of the translation/rotation/scaling transforms.

The implementation of Image Registration in SmartRoot assumes that the plane of the
scanner/camera is always parallel to that of the root material, so it only needs two regis-
tration anchors. Working with Image Registration in SmartRoot involves the following steps:

1. In the image at time t (in which a number of roots have been traced), locate two image
features (typically far from each other) that can be easily located on the image at time
t+1. Point the Registration Anchor tool to the first feature and raise the popup menu
to select ”Add Registration Anchor”. Repeat with the second feature and close the
datafile. The registration anchors are stored in the datafile.

2. Open the image at time t+1 (it should have an empty datafile), locate the same two fea-
tures and add the two registration anchors (as in 1.). Then select popup¿File¿Import

21
CHAPTER 4. SMARTROOT TOOLS

Seed Datafile and select the xml file of image t. All root objects of image t should
appear at the right place (i.e. correctly aligned on image t+1), but with the length
and diameter they had at time t.

3. You will be prompted and asked if the tracing and the roots are properly aligned. If
not, press No and replace the root by using the different arrows in the new window
(fig. 4.8). When the tracing is correctly placed, click OK
4. Process to root tracing of the root growth increments and new roots.

Move up
Rotate left Rotate right

Move left Move right

Translation Rotation
increment (px) Move down increment (rad.)

Figure 4.8: Registration window

22
CHAPTER 5
SMARTROOT WINDOW TABS

5.1 Layers
The Layout tab ing the SmartRoot window allows to select the root objects attributes that
are displayed on top of the image (fig. 5.1). The Save in Prefs stores the current selections
so that they automatically apply when opening an image. The preferences are user-specific.

     
(a) Nothing (b) Display Axis (c) Display Nodes

     
(d) Display Borders (e) Display Area (f) Display Ruler (and
Axis)

Figure 5.1: Display options.

23
CHAPTER 5. SMARTROOT WINDOW TABS

5.2 Root list

The ”Root list” tab of the SmartRoot window is divided in three panels. The upper left
panel presents all the drawn root of the image as a tree (fig. 5.2 A and B) while the upper
right panel display informations about the root selected in the tree (fig. 5.2 C). The bottom
panel show all the marks of the selected root (ig. 5.2 D).

The selected root(s) will also appear in red on the image.

A C
Figure 5.2: Root list.

A List of primary roots shown in

yellow.
B B If a root has children, they will be
shown in green.
C The right shows information about
the selected root(s).
D The bottom panel shows the marks
of the selected root.
D E Action menu to perform actions on
the selected root(s).
E F G F Apply button to validate the action
chosen.
G Refresh button to refresh the root
list (not done automatically)

This view allow the user to visualize easily the different root of the image as well as
perform some action on them with the Action button (fig. 5.2 E):

Delete root(s) Delete the selected root(s). Can be performed on multiple items.
Delete mark(s) Delete the selected mark(s). Can be performed on multiple items.

Rename root Rename the selected root. Can be performed on only one item. Can also
be done by double clicking on the root in the tree.

Attach parent Attach a new parent to the selected root(s). The user will be asked to
selected the parent in the list and then click the ”OK” button to validate his choice.
Can be performed on multiple items.

Detach parent Detach the parent(s) of the selected root(s). Can be performed on multiple
items.

Detach child(ren) Detach the child(ren) of the selected root(s). Can be performed on
multiple items.

Find laterals Run the ”Find lateral” function (see sec. 4.2.3) on the selected root(s). Can
be performed on multiple items.

24
CHAPTER 5. SMARTROOT WINDOW TABS

5.3 Linked files

SmartRoot enables time-series analysis of root images. General principle is to trace the
root you want to follow on every image of the time-series and to name them identically. Once
the root of the last image is traced, click on the Linking files panel of the SmartRoot
window. Then, choose the information you want to import on this last image (fig. 5.4). All
information will be displayed on the last image (fig. 4.1g) and can therefore be exported to
a single table in the database (see sec. 5).

Figure 5.3: Linking file tab in the SR window: this tab allows the user to import information from
previously treated images on the current one

Figure 5.4: Linking files in SR: All informations contained in the previous images of the same time-series
are displayed on the last image.

25
CHAPTER 5. SMARTROOT WINDOW TABS

5.4 Data transfer

SmartRoot as the ability to export data directly to a database as well as to a text file.
To export data the your database or a .csv file (for database setup, see sec. 1), select the
Data transfers tab in the SmartRoot window.

5.4.1 Send to SQL database

• Check the Send to SQL database checkbox

• Select the SmartRoot dataset (for details on export functions, see table ??)
• Check the Create new table checkbox if you want to create a new table in the
database. If the table already exist it will be overwritten
• Click the Transfer button. Look at the Results window for comments on transfer
execution.

5.4.2 Send to CSV text file

• Check the Send to CSV file checkbox

• Select the SmartRoot dataset (for details on export functions, see table ??)
• Choose where you want to save the .csv file

• Write the name of the file (without extension)

• Click the Transfer button. Look at the Results window for comments on transfer
execution.

5.4.3 Send to image file

This export generates an image of the traced roots (only the skeleton).

• Check the Send tracing to image file chekbox

• Choose the image type (color of black and white)

• Choose the image format (.png, .bmp, .jpg or .tiff)

• Choose the line width for the tracing

• Choose the folder where to save the image

5.4.4 Batch export

It is often the case that the tracing of all the images is done prior to the export of the data.
This function allows the user to export all the data at the same time, without re-opening
the already traced images. The function will gather the informations directly into the .xml
datafiles without opening the images (hence making it faster to export).

• Choose the folder containing the traced images and their corresponding .xml datafiles.
• Choose the export you want to use (SQL, CSV or image) and provide the needed
informations accordingly (for more information see previous section).

26
CHAPTER 5. SMARTROOT WINDOW TABS

5.4.5 SmartRoot Datasets

Global Root Data:

This export function provides information about individual roots .

Root Nodes:
This export function provides information about individual nodes.

All Marks:
This function provides function about all the marks of the image. additionally to the marks
added by the user, SmartRoot export an Origin mark (beginning of the root) and a Length
mark (end of the root). Diameter and angle measurement are taken at the mark position.
Mark value depend on the type of mark (see sec. 4.1g).

Root Length Density:

This export function is use for plants grown in flat boxes (rhizotrons). It measure to root
length density (root cm / soil cm3 ) in user defined area. You have to know the thickness
of the rhizotron. When you choose this export function, a specific window will appear, in
order to define the region you want to analyze (fig. 5.5).

The size of the area to analyze

The size of the grid inside this area

The thickness of the rhizotron

Figure 5.5: Root Length Density export settings

Growth rate:
This export function is use for time lapse drawing of plants grown in flat boxes (see sect.
6). It will export root growth based on the marks (Free text or Number) on the roots.

Important:

If you check the ’Create new table’ check box, a new table will be create in the database
if none exist. If an other database with the exact same name existed while transferring, it
will be erased. To add data to and existing table, uncheck this checkbox.

When you choose the name of your table, you should follow certain rules to avoid SQL
syntax errors. For instance use the character underscore (_) instead of space and do not use
accentuations. Certain words, such as table are use in the database syntax and their use
to name tables will result in errors. Complete list of forbidden names can be found on the
following web page:

MySQL: http://dev.mysql.com/doc/refman/5.5/en/reserved-words.html
Access: http://msdn.microsoft.com/en-us/library/aa238507%28SQL.80%29.aspx

27
CHAPTER 5. SMARTROOT WINDOW TABS

Table 5.1: Field explanation of the export functions in SmartRoot

Field Name Description

child density number of children / cm of parent root in the ramified region
diameter root diameter (for a root, the mean diameter of all nodes)
first child identifier of the first child (from the base)
distance from base position of the node relative to the root base
distance from apex position of the node relative to the root apex
growth growth since the last measure
image image name
insertion angle insertion angle on the parent
insertion first child position of the first child (from the base)
insertion last child position of the last child (from the base)
insertion position insertion position on the parent (from the base)
last child name of the last child (from the base)
length root length
n child number of children
parent parent identifier
root root identifier
root name root name
root ontology root type based on ontology classification
root order root ramification order (0 = first order root)
theta orientation of the node (radian)
value value of the mark (see table 5.1)
x x-coordinate (in cm) of the node center
y y-coordinate (in cm) of the node center

5.5 Plot
In the SmartRoot windows, the user can choose the Plot tab to access the build-in plot-
ting capabilities of SmartRoot. The aim of this tools is not to provide a first analysis of the
data, but rather a rough insight. The figure 5.6 shows plotting examples.

5.5.1 Histograms

Several types of histograms can be created such as the distribution of root diameter (for
difference ramification orders), root insertion angles, or root inter-branch distance (the dis-
tance between two laterals). The number of classes of the histogram can be set by the user
int he bits field. The default unit of histograms is frequencies but it can be set to absolute
values by selecting the Absolute value checkbox.

5.5.2 Charts

Three kind of charts can be generated inside SmartRoot:

• inter-branch distance vs position on parent axis

• lateral root length vs position on parent axis

• change in direction vs position on the root (only for root of ramification order 0)

As these charts are generated with the information of single root, you will have to select
the root you want the plot. To do so, click the Refresh button to actualize the root of the
current image. Then choose the wanted root in the root list (under option). The selected

28
CHAPTER 5. SMARTROOT WINDOW TABS

root will appears in red on the image (if you check the corresponding checkbox).

Figure 5.6: Plotting examples: on this figure we can see a two histograms (of the insertion angles of
laterals and of root diameter per order) and a chart of the inter-branch distance along the parent root axis.

29
CHAPTER 5. SMARTROOT WINDOW TABS

5.6 Settings
5.6.1 Image resolution
SmartRoot allow the user to set the image resolution based on the DPI value of the image
or a random value based on a scale visible on the image.
To use a scale on the image, simply draw a line on the scale, click the Get Line button
and set the physical length of the scale. The unit can be chosen between cm, mm and inch.
Click the Apply button to set the scale on the image. SmartRoot will use either the DPI or
the cm/mm/inch value based on the box you checked.
The default value for the scale is the one stored within the image. This default value
will not be used once you saved an image with SmartRoot. SmartRoot will use the value
stored in the .xml file linked with the image.
Click the Set as default button to set the current DPI value as the default DPI value
for all the newly opened images.

5.6.2 Naming options

Once you draw a root SmartRoot choose a new name for it. The software will use a prefix
and a sequential number based on the number of root already traced in the image.
The prefix of the root names can be changed by the user. The Principal root prefix
applies for the root traced manually or with the line-drawing utility. The Lateral root prefix
applies for the lateral roots traced with the Find laterals function.
If the Ask for name box is checked, the user will be ask to confirm the root name every
time a new root is traced.

5.6.3 SQL options

These options are used to connect SmartRoot to the database. There are optional if you
choose to use the CSV export. See section 1 for details on how to setup the database
depending on your operating system.

5.6.4 Lateral research parameters

The Find lateral function use several test while building the new laterals. These tests can
be disabled or parametrized depending on the image type and / or quality.
Number of steps along the root Number step between two node while screening paral-
lels of the selected root. The bigger is the number, the bigger is the precision but the
longer is the research.
Check the size of the nodes If selected, the algorithm will check the diameter of the
base node of every newly created laterals. If the node is either too big or too small,
the root will not be created. This size is relative to the diameter of the parent node.
A size of 1 means a size equal to the parent node’s
Minimal diameter of a node Define the minimal size of the node.
Maximal diameter of a node Define the maximal size of the node.
Check the size of the roots Check the size of newly created root. If this root is too
small, it is considered as noise and is deleted.
Minimal size of a lateral Define the minimal size of the newly created root. This
size is relative to the diameter of the parent node. A size of 1 means a size equal
to the parent node’s.
Check the direction of a node Check the insertion angle of the newly created root.
Force to root to be created in a given direction
Maximal insertion angle Define the maximal insertion angle possible for a newly
created lateral root.

30
CHAPTER 5. SMARTROOT WINDOW TABS

5.6.5 Thresholding method

The thresholding method used by SmartRoot can be chosen between an Adaptive thresholding
method or a fixed threshold based on ImageJ threshold. It is recommended to used the
Adaptive thresholding for optimal performances.

31
CHAPTER 6
MISCELLANEOUS INFORMATIONS

6.1 Root growth measurement in rhizotrons

Growing plant in rhizotrons is an easy way to track root growth over time:

• simply place a transparent sheet on the transparent surface of the rhizotron

• draw the root seen on the surface.

• write the day at the apex position (fig. 6.1).

• come back on a regular basis and repeat the process by appending new tracing to the
old ones

Figure 6.1: Example of hand drawing of root growth on a rhizotron surface

Once the tracing is done, you will have to process it in SmartRoot as follows:

• trace the different roots, with topology if necessary

• us the Mark tool to place Free Text mark were you point the apexes

• set the value of the mark to the day on which you trace the apex (fig. 6.2)
• use the export function ”Root Growth” and you are done

32
CHAPTER 6. MISCELLANEOUS INFORMATIONS

Figure 6.2: Example of hand drawing of root growth with subsequent treatment in SmartRoot

6.2 About the SmartRoot datafile

When closing a root image window, all graphic objects (name, nodes coordinates and
diameter, marks) and the DPI setting are recorded in a separate file in XML format, referred
to as the SmartRoot datafile. The datafile is named after the image name, with the .xml
extension and is stored in the same directory as the image. When the image is opened later,
the datafile is loaded and every root objects are automatically reloaded.

By default, the datafile is saved whenever an image is closing, unless you close explicitly
the image with the command File>Quit without saving datafile in the popup menu.
If you modified the image content itself, for example by applying a smooth filter, ImageJ
will ask you whether you want to save the image and or the datafile.

If you use the SaveAs command of ImageJ to save a copy of your image in a different
folder and/or under a different name, a copy of the datafile is created as well and will be
saved at the new location when the window is closed.

The File item of the popup menu brings a submenu with a few actions related to the
datafile:

Save DataFile: Allows to directly save the datafile, without closing the image window
(because SmartRoot is still a new software, it is recommended to regularly save the
datafile this way)

Clear DataFile: Erase all root objects in memory.

Use backup datafile: Allows to use a previously saved datafile after a wrong manipulation
of computer crash (see below).
Quit without saving datafile Name is self speaking.

Import Seed Datafile Allows to load the datafile of a different image (the ”seed” image),
provided the current image and the seed image have been registered with two anchor
points (the process of registration is explained above).

When a datafile is saved, the current datafile on disk is not replaced. Instead, its ex-
tension is changed to .xml01 (if an archive datafile .xml01 exists, it is renamed .xml02, and
so on until the .xml05 file which is deleted). To open an image with an archive datafile,
right-click on the image name in the SmartRoot Explorer window and select the archive
datafile you would like to use from the popup menu or use the right click on the image and
choose File > Use backup datafile.

33
CHAPTER 6. MISCELLANEOUS INFORMATIONS

6.3 Using ImageJ functions and plugins in SmartRoot

windows
It is in principle possible to use ImageJ functions and plugin on image windows that
were opened with the SmartRoot user interface, with two exceptions:

1. Functions / plugins that change the size of the image will permanently inactivate the
SmartRoot user interface in the modified image window.
2. Functions / plugins that change the type of the image to anything else than 8-bit
grayscale will prevent the the root detection algorithm to work properly (the rest of
SmartRoot will be OK, though). The situation will get back to the normal as soon as
the image type is reset to 8-bit grayscale.

Image editing through ImageJ will not modify existing SmartRoot objects, simply be-
cause ImageJ does not know about root objects. It may therefore be necessary to re-trace
these objects.

The process of saving images and datafiles becomes confusing when the user has edited
an image that was opened in SmartRoot. Indeed, whenever an image has been edited,
ImageJ brings up its own Save ? Yes-No-Cancel dialog box when the image is closing.
The user response only tells ImageJ whether the edited image should be saved, but does not
tell SmartRoot whether the datafile should be saved. Whether the datafile is saved depends
only on the way the image was closed. The only exception is the Save As menu item of
ImageJ, which stores both the image and datafile to a new location. In most instances,
the user will not edit the image while working in SmartRoot and there should not be any
problem.

6.4 Disclaimer
We put a lot of effort and time trying to make SmartRoot accurate, fast and user-friendly.
However, we make no claims that SmartRoot is perfect and will work in every situation and
with every image. You are advised to use it at your own risk. SmartRoot is still a work in
progress and is still evolving. If you have any question, proposition, advise, please visit the
our website (www.uclouvain.be/smartroot) to contact us.

34
CHAPTER 7
TROUBLESHOOTING

There is FAQ section on SmartRoot’s website (www.uclouvain.be/en-smartroot) covering

the different troubles you might have using SmartRoot.

35
 INDEX

tools, 15

36