Preparing to Use RootReader3D

Install Java

RootReader3D (Java version) has been compiled and tested using Java Runtime Environment (JRE) and Java Development Kit (JDK) v. 1.8.0 Update 131 and OpenJDK 1.7.0 Update 121 (on Linux).

You can check what version of Java JRE and JDK you are running by opening a command line terminal and typing the following two commands:

$ java -version
java version "1.8.0_131"
Java(TM) SE Runtime Environment (build 1.8.0_131-b11)

$ javac -version
javac 1.8.0_131

If you do not have the latest version of Java installed, or are missing either the JRE or JDK, you can download them from the official Java website for your particular platform: JRE 8 or JDK 8.

Install Perl

To compile the Java source code, a convenience function has been provided, written in the Perl programming language (https://www.perl.org).

Unix-like operating systems (e.g., Linux and Mac OS X) have default installations of Perl. You can check if you have perl installed on your machine by typing the following command:

$ perl -version
This is perl 5, version 18, subversion 2 (v5.18.2)
Copyright 1987-2013, Larry Wall

If you are a Microsoft Windows user and do not have Perl installed on your computer, you can download and install a copy of Strawberry Perl (http://strawberryperl.com).

Build from Source

The Java source code is located in the java_version/src directory. The src directory contains the following subdirectories:

Name Description
META-INF Includes the manifest file used by the Java compiler
com/sun/media/jai Java Advanced Imaging support files
controls The main RootReader3D Java class
dataStorage The data storage Java class
descriptors Used in measurement helper functions
fileFilters Filters for reading/writing files
fileIO Classes for reading/writing files
filters Classes for processing and operations
helpers Class objects for plant roots
imagePanels GUI classes for visualization windows
images GIF files for window/button icons
javax/media/jai Java Advanced Imaging support files
Makefile Makefile for compiling Java source code (not used)

The Perl script (java_version/setup.pl) handles the compilations, heap memory allocation, Jar file bundling, and program execution for you.

To run the setup script, open a command line terminal, navigate to the java_version directory, and type the following command:

$ perl setup.pl -h
Usage:
  make, jar and run ... perl setup.pl
  make ................ perl setup.pl -m (--make)
  jar ................. perl setup.pl -j (--jar)
  run ................. perl setup.pl -r (--run)
  clean ............... perl setup.pl -c (--clean)
  help ................ perl setup.pl -h (--help)

The setup script has six modes of operation and five special command-line arguments (i.e., -m, -j, -r, -c, and -h). The first command-line argument, -m, compiles the Java source code (i.e., the .java files) into .class files. Any errors in the Java code will be made known during this step. All errors must be fixed before continuing.

The second command-line argument, -j, bundles the .class files into an executable jar file (src/RootReader3D.jar), which is ready to run the RootReader3D program. Use the third command-line argument, -r, to run the newly compiled and bundled jar file. You must have compiled the Java files and bundled the class files into a jar before running.

You can automatically complete the first three command-line arguments (i.e., -m, -j, and -r) in sequence by running the setup script with no command-line arguments (i.e., perl setup.pl). Note that errors during the compilation will result in a failed execution.

Use the fourth command-line argument, -c, to remove the compiled .class files from the source code directories. Note, this preserves the .class files located in the JAI subdirectories.

Run

Once the source code has been successfully compiled (i.e., utilizing the -m flag in the setup script) and jarred (i.e., utilizing the -j flag in the setup script), you may execute the program by running the setup script with the -r flag.