S martR T

Quick Start Guide

How to install, setup and use SmartRoot

October 5, 2011

Contents
1 First steps 2

2 Windows installation 3

3 Mac OSX installation 4

4 Linux installation 6

5 Quick Start SmartRoot 8

6 Tracing roots 9

7 SmartRoot window’s tabs 12

This small document presents briefly how to install, setup and use SmartRoot.

For more detailed informations about SmartRoot, you might want to read either the
User Guide1 or the related paper:

Guillaume Lobet, Loı̈c Pagès and Xavier Draye. A Novel Image Analysis Toolbox En-
abling Quantitative Analysis of Root System Architecture. 2011 Plant Physiology
157 doi:10.1104/pp.111.179895

1 www.uclouvain.be/en-smartroot

1
1 FIRST STEPS

1 First steps
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 me 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.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 2 . This is
the folder you will have to copy in the ImageJ folder (see below).

2 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

2
2 WINDOWS INSTALLATION

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

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.

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.

3
3 MAC OSX INSTALLATION

3 Mac OSX installation

1. Install and configure MySQL database (optional)
2. Install ImageJ and SmartRoot

3. Use the Quick start images

3.1 MySQL installation and configuration

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.

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.

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

4
3 MAC OSX INSTALLATION

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

5
4 LINUX INSTALLATION

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

4.1 MySQL installation and configuration

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.

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

4.2 ImageJ installation

In the terminal window type:

$sudo apt-get install imagej

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.

6
4 LINUX INSTALLATION

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

7
5 QUICK START SMARTROOT

5 Quick Start SmartRoot

In order to learn how to use SmartRoot, open the different tutorial images inside the
software (start with the image quick start 1.tif). To open an image in Smart root, just find
it on your computer in the Explorer window (fig. 1). Follow the instruction on the image
to learn how to trace roots.

ImageJ Window

SmartRoot Window

Explorer Window

Image Window

Results Window

Figure 1: SmartRoot different windows

8
6 TRACING ROOTS

6 Tracing roots
Manual tracing

1. Select the Trace tool

2. Check Display nodes and Display axis in the Layer tab

3. Click inside a root to place a node.
4. Keep going until the end of the root
5. Double click to end the root

6. Choose a name for the newly created root

Semi-automated tracing

1. Select the Trace tool

2. Check Display nodes and Display axis in the Layer tab

3. Maintain the Alt key down
4. Click inside a root to trace it.

5. Choose a name for the newly created root

Manually continuing a root

1. Select the Trace tool

2. Check Display nodes and Display axis in the Layer tab

3. Right click on the first or last node of an existing root and choose Append node.
4. Click inside the image to place a new node.

5. Keep going until the end of the root

6. Double click to end the root

9
6 TRACING ROOTS

Automatically continuing a root

1. Select the Trace tool

2. Check Display nodes and Display axis in the Layer tab
3. Hold the Alt key down
4. Click on an existing node and drag it a bit further.

Modifying nodes

Right click on an existing node. Choose on of the following action:

Append nodes: Continue tracing in manual mode

Split root: Split a root in two new roots.

Remove node: Remove the selected node.
Remove all nodes (after): Discard all node located distal to the selected node.

Remove all nodes (before): Discard all node located proximal to the selected node.

Modifying roots

Right click inside an existing root. Choose on of the following action:

Bring to front: Bring the selected root to the front of the list of roots.
Send to back: Send the selected root to the back of the list of roots.

Find laterals: Check along the root axis for lateral roots creation.
Attach parent root: Set a parent for the current root.
Detach parent root: Remove the relationship between a root and its parent.

Detach children roots: Remove the relationship between a root and all its children.
Rename root: Change the name of the selected root.
Delete a root: Remove the whole root.
Reverse orientation: Reverse the root orientation.

Crop children: Cut all roots whose first node is within the area of the selected root.

10
6 TRACING ROOTS

Connecting two existing roots

1. Select the Trace tool

2. Check Display nodes and Display axis in the Layer tab
3. Right click on the first or last node of an existing root and choose Append node.
4. Right click on the first or last node of an other existing root.

Escaping the centering mechanism

1. Select the Trace tool

2. Check Display nodes and Display axis in the Layer tab

3. Hold the Control key down and move a node for a Diameter freeze
4. Hold the Shift key down and move a node for a Align to border
5. Combine Control, Shift and Alt keys.

11
7 SMARTROOT WINDOW’S TABS

7 SmartRoot window’s tabs

Layers tab

A. Type of layers.
B. Save your preferences.
A

Root list tab

A. Primary roots, in yellow.

B. Secondary roots, in green.
A C C. Informations about the selected root(s).
D. Marks of the selected root.
E. Perform actions on the selected root(s).
F. Validate the chosen action.
B
G. Refresh the root list

D
E F G

Actions: Delete root(s) — Delete mark(s) — Rename root

Attach parent — Detach parent — Detach child(ren) — Find laterals

Linked files tab

A. Files to link.
B. Marks to link.
C. Add a file to the list.
A B D. Refresh the image display.
E. Refresh the list display.

C D E

Data transfers tab

12
7 SMARTROOT WINDOW’S TABS

A. List of SmartRoot datasets.

B. Export to SQL.
A C. Export to CSV
D. Transfers button.
B
C
D

Datasets: Global Root Data — All marks — Root Nodes — Root Length density

Plot tab

A. Histograms.
A B B. Charts.
C. Refresh button.
D. Close all plots.
E. Plot the selected charts and histograms.

C D E

Settings tab

A. Image resolution.
A B. Naming options.
B
C. SQL options.
D. Lateral finding options.
E. Thresholding options.
C

13