The MR-RIPL 2.0 User's Guide

Vera Bakic

Root Image Processing Lab
Plant and Soil Science Department
Michigan State University

(c), 1996, Board of Trustees, Michigan State University

1 Introduction

MR-RIPL is a program for measuring numerous root parameters from video-recorded images taken by the minirhizotron camera. Statistics measured are root length, surface area, volume and total length for 10 width classes. The program processes one image or frame at a time, and generates files containing the above mentioned statistics. In addition, a program to process the video images in one directory, and a program which generates a compressed statistical database file for several minirhizotron tubes are also provided. MR-RIPL 2.0 is based on a previous program for the recognition of roots from a minirhizotron images developed earlier using the VICOM image processor at Michigan State University. MR-RIPL is implemented in the C language, and tested on SUN workstations and on a PC using the LINUX operating system. The image formats that can be read as input are SUN rasterfile and JPEG. Output images are generated in SUN rasterfile format.

The input images for MR-RIPL should be grayscale, with light roots on dark background. The images size used was 256x256 pixels and 320x240 pixels, and the execution time on SparcStation 5 is 32 seconds, and on SparcUltra 1 is 16 seconds.

1.1 Comments and bug reports

If you have any comments or reports of bugs in the MR-RIPL 2.0 release, please send them to the following address:

2 Overview of the algorithm

Figures 1 depicts the process of finding segments of roots in an image. The original image is in Figure 1(a). The image is processed using the following algorithm:

(a) original image (b) centerlines found are white lines
(c) centerlines-white, edges-gray (d) centerlines identified as background are white lines
(e) centerlines identified as roots are white lines (f) models of the identified roots

Figure 1. Process of finding roots in an image (filename: C_19.ras)

This is our first and imperfect identification. Additional revisions, which improve the accuracy of identification are underway.

3 Compiling MR-RIPL 2.0

  1. Extract the files from the archive using:
    tar xvf MR-RIPL-2.0.tar

    Directory MR-RIPL-2.0 will be created, with subdirectories bin, src, images and docs. The directory src contains the source code, the executable files are placed in bin directory, images included in this text are in images directory, and the documentation is placed in the docs directory.

  2. To use a compiler other than cc from Sun Systems, edit the src/Makefile, and change cc to indicate another compiler (such as gcc).

  3. To use JPEG images, edit src/Makefile, and change the LIBS line, as described in the comments in the file. In addition, edit file src/root_defines.h and uncomment the line that defines ADD_JPEG variable.

  4. To run the program under LINUX, edit src/Makefile, and change the CFLAGS lines. Also, edit src/root_defines.h to uncomment the SUNSOLARIS variable definition and to define the PCLINUX variable.

  5. Change directory to src directory, and type make. This will compile all the files and place the executable mrripl in the bin directory.

  6. Add directory MR-RIPL-2.0/bin in the path by editing a file such as .cshrc, and executing it ( source \~/.cshrc).

  7. The following files should be found in the directory bin at this point:
    mrripl    - the executable for the minirhizotron program
    runmrripl - script for processing images in one directory by mrripl
    stattocom - script for generation of the compressed files, uses
                maketocom program
    makecom   - program for the generation of compressed files, should
                not be used by itself

4 Running MR-RIPL 2.0

4.1 Processing input images and generating statistics files

There are two ways to use MR-RIPL: to process one image at a time or to process all the images in one directory (ex. images from the beginning to the end of a video tape).

4.1.1 Process one image at a time

Run mrripl. It requires the following arguments:

usage: mrripl in_file out_prefix pixels_per_mm quiet_img create_log
  in_file       - input file (SUN rasterfile format)
  out_prefix    - output files prefix
  pixels_per_mm - pixels per mm for camera used
                  must be > 0
  quiet_img     - 0 - no output images
                  1 - segments image only
                  2 - models of roots only
                  3 - segments and models of roots
  create_log    - 0 - don't create log file
                  1 - create log file

in_file is the full path of the input image in SUN rasterfile or JPEG format. The image files must have the extensions .ras or .jpg respectively.

out_prefix is the prefix used for the output files, with a path to the desired directory if needed.

pixels_per_mm is the area of the soil covered by the image, and should be in pixels per mm. It will depend on the type of the camera used, and if it is unknown camera type, 1.0 should be entered. This parameter must be determined by the user.

quiet_img defines which output images will be created. If the user needs no images, this should be set to 0. The segments image will outline all the segments found in the image, coloring segments rejected as background into white, and segments recognized as roots into non-gray colors according to the width class. Figure 1(d) shows such image. The image will have name <out_prefix>_segments.ras. The models of the roots will model the roots using the segment contour and the width of the segment, and will outline the model in white(Figure 1(e)). The image will have name <out_prefix>_model.ras.

create_log if set will create log file with the data on each segment found in the image. The log file will have name <out_prefix>.log. If no log file is needed, this should be 0.

In each run, a statistics file will be created with the name <out_prefix>.stat. An example file is:

cumulative statistics for 148 root segments
total length:           504.00 mm
total surface area:   12820.00 mm^2
total volume:         37230.00 mm^3
total length per width class
  class   1 [  0--  2]:      75.00 mm
  class   2 [  2--  4]:     272.00 mm
  class   3 [  4--  6]:       0.00 mm
  class   4 [  6--  8]:      52.00 mm
  class   5 [  8-- 10]:     105.00 mm
  class   6 [ 10-- 12]:       0.00 mm
  class   7 [ 12-- 14]:       0.00 mm
  class   8 [ 14-- 16]:       0.00 mm
  class   9 [ 16-- 18]:       0.00 mm
  class  10 [ 18-- 20]:       0.00 mm

Examples of startup of mrripl are:

mrripl MR_KBS_090996_123_12.ras MR_KBS_090996_123_12 1.0 3 0

that will process image file MR_KBS_090996_123_12.ras, create statistics output file MR_KBS_090996_123_12.stat, and both segments and models of the identified roots images ( MR_KBS_090996_123_12_segments.ras and MR_KBS_090996_123_12_model.ras), using value of pixels per mm of 1.0.

mrripl MR_KBS_090996_123_12.ras MR_KBS_090996_123_12 28.9 0 0

that will process image file MR_KBS_090996_123_12.ras, and create statistics output file MR_KBS_090996_123_12.stat, using value of pixels per mm of 28.9.

4.1.2 Process all images in some directory

This script facilitates the processing of sequence of images (ex. all the images from one tape). All images to be processed must be in the same directory, and must be in SUN rasterfile format and have extension .ras.

Start script runmrripl. A series of questions will be asked about the settings for the runs. Example session is:

Directory for the input images:
> /images/KBS/090996/123 
Directory for the output images:
> /img_stat/KBS/090996/123
Pixels per mm for the camera used:
> 1.0
What output images to be created:
  0 - no output images
  1 - segments image only
  2 - models of the roots only
  3 - segments and models of the roots
> 2
Create log file (0 - no, 1 - yes):
> 0
Processing all image files in directory: /images/KBS/090996/123
Output directory will be: /img_stat/KBS/090996/123
Current settings are
  Pixels per mm: 1.0
  Output images to be created: 2
  Create log file: 0
Do you want to change settings? (y)es, (n)o, (q)uit
> n

This example will process all the images with the extension .ras in the directory /images/KBS/090996/123, and store the results in same directory. Only models of the roots image will be created in addition to the statistics file. The output files will have the same prefix as the input image---.ras will be replaced with _segments.ras and .stat. If the user makes a mistake in the input data, it can be corrected if 'y' is entered on the last question, and the input data can be entered again. If the user wishes to quit the run, the answer on the last question should be 'q', and in that case no images will be processed.

4.2 Compressing statistics files

For further processing of the statistics files (ex. analyze the data for one tube in time, or analyze the data for several tubes on one location, etc.), the data from several statistics files can be compressed in one file. The compressed files can be used as input to a database, or used to plot the graphs of the changes in the root length.

Generated statistics files (with the extension .stat) can be compressed using the stattocom script. All the files must have fixed name format, and all letters must be capital letters:


There must be exactly 4 `` _'' characters, that will separate the identifiers:

For one tube and date (assuming fixed experiment), the only information that will vary is <frame>. The first frame on the soil surface should have the lowest number (ex. 1 or 10), and the last frame in the tube (presumably at the end of the tube) will have the highest number (ex. 85).

All the statistics files in some directory will be processed using a look-up table (generated by the experimenter). Each line in the look-up table must have the following format:

<tube>,"code1 code2 ...",<beginning_frame>

where <tube> is the tube number, codes section is defined by the experimenter and is described in the comments, and <beginning_frame> is the first frame number on the soil surface. The codes section can be empty, or can have any information needed for the experiment. The codes can be described in the look-up table file in the form of comments. Lines starting with '\#' are comments. A sample look-up table is:

# this is a sample lookup table for KBSLYS 94 tubes
# code 1 is for tillage  1:notill 2:convtill
# code 2 is soil depth of tube
# code 3 is crop  1:corn  2:alfalfa  3:beans  4:wheat
#  these codes are ficticious
1,"2 30 2",1
65,"1 30 2",1
66,"1 45 2",1
4,"1 30 4",15

The compression is done by summing the data for $N$ consecutive frames starting from the first frame on the soil surface. The number of frames $N$ is entered by the user. The user can choose which statistics out of 13 generated will be compressed. The lines in the compressed file will be in the format:

<tube> "code1 code2 ..." <date> <sequence of compressed data>

To start the script, type stattocom, and the series of questions will be asked to set up the run. An example session is:

Directory for the input stat files:
> .
Directory for the look-up tables:
Enter look-up table name (with full path):
> /lut/KBS/96/KBS_0696.lut
Number of windows to compress in one:
> 10
Which statistics to compress:
  1 - total length of all roots
  2 - total surface area
  3 - total volume
  4 - total length for width class  1 [ 0 -  2 pixels]
  5 - total length for width class  2 [ 2 -  4 pixels]
  6 - total length for width class  3 [ 4 -  6 pixels]
  7 - total length for width class  4 [ 6 -  8 pixels]
  8 - total length for width class  5 [ 8 - 10 pixels]
  9 - total length for width class  6 [10 - 12 pixels]
 10 - total length for width class  7 [12 - 14 pixels]
 11 - total length for width class  8 [14 - 16 pixels]
 12 - total length for width class  9 [16 - 18 pixels]
 13 - total length for width class 10 [18 - 20 pixels]
> 1
Compressed filename:
Directory for the input stat files: .
Look-up table used: /lut/KBS/96/KBS_0696.lut
Number of windows to compress in one: 10
Statistics that will be compressed: 1
Compressed filename:
Do you want to change settings? (y)es, (n)o, (q)uit
> n

This example will process all the statistics files in the current directory (denoted as .), using look-up table file /lut/KBS/96/KBS_0696.lut. The number of frames to compress is 10, and total length will be compressed. If the user makes a mistake in the input data, it can be corrected if 'y' is entered on the last question, and the input data can be entered again. If the user wishes to quit the run, the answer on the last question should be 'q', and in that case no images will be processed.

5 Results obtained

In Section 2, a sketch of how the discrimination between root and background is done. When the Discriminant Analysis was done, the emphasis was to minimize the false alarms (Type I error: deciding a background segment is root) and to minimize false dismissals (Type II error: deciding a root segment is background) for long roots that contribute more to the total length. The goal to minimize the false alarm error is in conflict with the goal of maximizing the hit rate for short (or not very long) root segments. Since there may be many more background segments, it was essential to put more emphasis on the minimization of false alarms, thus reducing the hit rate for small root segments (which, fortunately, do not contribute a lot to the overall root length). This approach results in the underestimation of total root length.

The error rates are calculated on the independent test images (178 images taken from 5 tapes, each tape records a different crop) that were all different from the training images, and are based on the measured length of roots and background. All segments in test images were manually classified as root or background, and the results obtained by the program are compared to the manual classification. The lengths of the roots measured manually and detected by the program are in the Table 1. Errors for the data from all tapes analyzed together and errors for the data from one tape only are included.

Manually Correctly Incorrectly Error
classified classified classified in %
All Tapes root 65698 45301 20397 31.05
background 238496 234149 4347 1.82
Tape 1 only (corn roots) root 9234 6662 2572 27.85
background 70614 69120 1494 2.12
Tape 2 only (alfalfa roots) root 8235 6402 1833 22.26
background 34244 33398 846 2.47
Tape 3 only (popoulus roots) root 10390 6991 3399 32.71
background 31665 31389 276 0.87
Tape 4 only (beans roots) root 27325 16696 10629 38.90
background 35313 34412 901 2.55
Tape 5 only (wheat roots) root 10514 8550 1964 18.68
background 66660 65830 830 1.25
Table 1. Length in pixels measured manually, and classified by MR-RIPL 2.0

We can divide test images into three categories: perfect tubular objects, good minirhizotron images and bad minirhizotron images. The error rates for the first two categories are small. However, for the third category, it might happen that background is recognized as root and that roots are not recognized at all. Figure 2 depicts the results for perfect tubular objects. The original input image and the models of the roots found are displayed. The root length and width are very accurate. Figure 3 depicts the results for the good minirhizotron images. Very little of the root length is lost, and live roots are well separated from dead roots (Figure 3(a)). Figure 4 depicts the results for the bad minirhizotron images. A lot of roots (as much as 50%) are lost, since the roots either overlap, thus making a lot of small segments, or are very dark and hard to separate from the background (even for the humans).

filename original image white lines are detected roots

Figure 2. Results for perfect images

filename original image white lines are detected roots

Figure 3. Results for good minirhizotron images


Figure 4. Results for bad minirhizotron images

6 Conclusion and Future Work

The program for measuring root lengths from minirhizotron images has been implemented in the C language, and can be run on several platforms (Unix, Linux, Dos). The results obtained are very accurate if the images have high contrast. For images where humans might find it difficult to define roots, the program might not find all of the roots and might misclassify background as root. The errors result due to poor contrast in the image, or if roots are darker than the background, what makes the segmentation hard. Also, it was not possible to separate roots and background classes perfectly using Discriminant Analysis, what results in misclassification. The accuracy of the program can be improved by improving the discrimination function, or using other classification methods, what is currently under development.