• Version History
• Version 0.1
• Overview
• What the Software Does
• Requirements
• Installation Instructions
• Obtaining the Software
• Verifying your Perl Installation
• Setting up the IRT Environment
• Verifying the IRT Installation
• Testing the IRT Installation
• How to Run the Software
• How the Software Works
• How run_ice_surf_stats.pl Works
• How ice_surf_stats.pro Works

Version History

Version 0.1 released April 11, 2002

• Initial version.

Overview

What the Software Does

The Ice Reconnaissance Toolbox (IRT) is a set of software tools that can be used to read sea-ice surface type tif images and create sea-ice surface type coverage statistics text files.

IRT consists of a Perl script (run_ice_surf_stats.pl) that calls an IDL procedure (ice_surf_stats.pro) by way of another Perl script (idl_sh.pl). Also included are a setup script (irt_env.csh), an html document (irt.html), a test script (test_irt.csh), and some test data.

For a description of the syntax of run_ice_surf_stats.pl, see run_ice_surf_stats_usage. For an example of how to run run_ice_surf_stats.pl, see Testing the IRT Installation.

Requirements

In its current form, IRT is intended to run on a Unix/Linux workstation. It also requires Perl 5.0 or higher and IDL 5.3 or higher. The installation instructions assume that the user is running csh or tcsh as the Unix shell. Users of other shells (e.g. bash, ksh, sh, etc.) may have to make slight changes to the installation instructions.

IRT has been developed and tested on an SGI O2 workstation having 192 Mbytes of memory and running IRIX 6.5, perl 5.004_04, and IDL 5.5. However, ice_surf_stats.pro has been run successfully as a standalone IDL procedure on a Windows 2000 platform running IDL 5.4.

Installation Instructions

Obtaining the Software

The software and associated documentation can be downloaded from ftp://baikal.colorado.edu/pub/NSIDC/irt0.1.tar.gz, where 0.1 is the current version and release. Save this file into some directory where you want the IRT software installed. If you have a previous version of IRT installed in the same directory, you should either remove it or rename it. For example:

rm -fr irt

or something like:

mv irt irt.old

Then type:

gunzip -dc irt0.1.tar.gz | tar xvf -

This will create a directory in the current directory called irt which will contain several subdirectories. Further instructions on the installation and use of IRT can be then found in html files in the irt/doc subdirectory. At this point you can delete the tar.gz file if you want. Point your browser to irt/doc/index.html (this document).

Verifying your Perl Installation

Type the command:

perl -v

If you see something like:

This is perl, version 5.004_04 built for irix-n32

Copyright 1987-1997, Larry Wall

Perl may be copied only under the terms of either the Artistic License or the
GNU General Public License, which may be found in the Perl 5.0 source kit.

then you know perl has been installed ok. Just make sure you have at least perl version 5 installed. However, if you see something like:

perl: Command not found

then you need to contact your system administrator to get perl installed.

Assuming you have perl installed, then type:

/usr/bin/perl -v

If you see the same message as before, then you have a proper link to your installed version of perl. However, if you see something like:

/usr/bin/perl: Command not found

or you see mention of a lower version of perl, then you need to contact your system administrator and have a link called /usr/bin/perl created that points to your installed version of perl. For example, if you type:

which perl (or type perl if you're running bash, ksh, or sh)

and you see:

/usr/sbin/perl

then the command to create the link would be:

ln -s /usr/sbin/perl /usr/bin/perl

but you'll probably need to be logged in as root to be able to execute this command successfully.

Setting up the IRT Environment

Edit your .cshrc or your .login file and insert the following two lines:

setenv IRT_HOME $HOME/irt
source $IRT_HOME/irt_env.csh

If you installed irt into some directory other than $HOME, then change the first line accordingly. If your .cshrc or your .login includes lines such as:

setenv IDL_DIR /usr/local/rsi/idl
source $IDL_DIR/bin/idl_setup
setenv IDL_PATH ...

then the two IRT lines above should be placed after these IDL lines in the appropriate file. Once your .cshrc or your .login file has been editted, then logout and login again, or else type the following two lines:

source ~/.cshrc or
source ~/.login
rehash

Finally, create a writeable directory in your home directory called tmp that will be used by a Perl script called idl_sh.pl. This directory will be used for holding temporary shell scripts for running IDL programs:

mkdir ~/tmp

Verifying the IRT Installation

Try typing in the following command to get the syntax of the run_ice_surf_stats.pl perl script:

run_ice_surf_stats.pl

You should see a usage message that describes the syntax of the run_ice_surf_stats.pl script that is essentially the same as run_ice_surf_stats_usage. If you get "command not found" or something to that effect, it probably means that your $path is being set after the source $IRT_HOME/irt_env.csh command in your .cshrc or .login file. Find the line in your .cshrc or .login that looks like:

set path = <something>

and change it to:

set path = ($path <something>)

Then logout and login and try the commands again.

Next, verify that the environment variable $IDL_PATH is set correctly. Type:

echo $IDL_PATH

You should see a directory that looks like:

<something>/irt/src/idl

as one of the directories in the IDL path. If not, then make sure that you placed the source $IRT_HOME/irt_env.csh command after setting $IDL_PATH in your .login or .cshrc as decribed above.

Testing the IRT Installation

Once you have verified that the IRT software has been installed correctly, you can run a test script that will compute sea-ice surface type statistics for two sea-ice surface type image files and test that the output files match two expected statistics files. This test script also serves as an example of how to use run_ice_surf_stats.pl. First type:

cd $IRT_HOME/test
ls -FR

You should see two directories, images and expected_statistics, as well as a c-shell script, test_irt.csh. In the images directory are two TIFF images, beaufo_2000jun19a_2c.tif and beaufo_2000jul28a_3c.tif. These files will serve as input to run_ice_surf_stats.pl. In the expected_statistics directory are two text files, beaufo_2000jun19a_2c_stats.txt and beaufo_2000jul28a_3c_stats.txt. These files will be compared to the output files created by run_ice_surf_stats.pl. Next type:

cat test_irt.csh

to view the contents of test_irt.csh. The comments in test_irt.csh explain what the script does. Note that the output files will be created in an output directory called statistics which does not yet exist but will be created by run_ice_surf_stats.pl. To run test_irt.csh, type:

./test_irt.csh

The script should run for about 10-15 minutes depending on the speed of your computer. The screen output should look something like this:

run_ice_surf_stats.pl: MESSAGE: started Thu Apr 11 17:28:56 MDT 2002
> dir_in  = images
> dir_out = statistics

IDL Version 5.5 (IRIX mipseb). (c) 2001, Research Systems, Inc.
Installation number: 100.
Licensed for use by: barrow.colorado.edu

% Compiled module: ICE_SURF_STATS.

****************************************************************
ice_surf_stats.pro started Thu Apr 11 17:29:01 2002
  class_count:        3
  input_file:  images/beaufo_2000jul28a_3c.tif
  output_file: statistics/beaufo_2000jul28a_3c_stats.txt
% Loaded DLM: TIFF.
ice_surf_stats.pro completed Thu Apr 11 17:36:12 2002
  elapsed time:  7 minutes,  11 seconds
****************************************************************

IDL Version 5.5 (IRIX mipseb). (c) 2001, Research Systems, Inc.
Installation number: 100.
Licensed for use by: barrow.colorado.edu

% Compiled module: ICE_SURF_STATS.

****************************************************************
ice_surf_stats.pro started Thu Apr 11 17:36:14 2002
  class_count:        2
  input_file:  images/beaufo_2000jun19a_2c.tif
  output_file: statistics/beaufo_2000jun19a_2c_stats.txt
% Loaded DLM: TIFF.
ice_surf_stats.pro completed Thu Apr 11 17:42:58 2002
  elapsed time:  6 minutes,  45 seconds
****************************************************************
 

run_ice_surf_stats.pl: MESSAGE: completed Thu Apr 11 17:42:59 MDT 2002
****** elapsed time: 0 hours, 14 minutes, 3 seconds ******
****** 2 files processed successfully out of 2 attempted ******

diff expected_statistics/beaufo_2000jul28a_3c_stats.txt statistics/beaufo_2000jul28a_3c_stats.txt
3c3
< Tue Apr  9 11:53:26 2002
---
> Thu Apr 11 17:29:01 2002
Only in expected_statistics: beaufo_2000jul28a_3c_stats.txt,v
diff expected_statistics/beaufo_2000jun19a_2c_stats.txt statistics/beaufo_2000jun19a_2c_stats.txt
3c3
< Tue Apr  9 11:58:57 2002
---
> Thu Apr 11 17:36:14 2002

Note that the only differences found between the expected files and the output files should be in the date/time header records indicating when the files were created.

How to Run the Software

1. Identify a single directory that holds the all the input files to be processed by a single call to run_ice_surf_stats.pl. This directory can hold other files as well, but only those files having filenames of the form shown in run_ice_surf_stats_usage will be used as input to run_ice_surf_stats.pl.
2. Determine the directory into which the output files created by run_ice_surf_stats.pl should be placed. This may be a new directory or an existing directory or may even be the same as the input directory identified in step 1.
3. Invoke the run_ice_surf_stats.pl script by typing:
run_ice_surf_stats.pl dir_in dir_out
where dir_in is the input directory identified in step 1, and dir_out is the output directory identified in step 2. If dir_out is the same as dir_in, then it may be omitted. For either directory, use a period (.) to indicate the current directory.

When run_ice_surf_stats.pl starts, it will display a message indicating the current date and time as well as the input and output directories it is using.

For each input file, ice_surf_stats.pro will be called and will display a message indicating the current date and time as well as the number of classes, the input filename, and the output filename. When ice_surf_stats.pro completes, it will display a message indicating the current date and time as well as the elapsed time needed to process the input file.

4. Once run_ice_surf_stats.pl completes, it will display a message indicating the current date and time and the elapsed time. It also displays a message indicating the number of files successfully processed and the number of files attempted. If these numbers are not the same, then look for a previous WARNING message that indicates why a particular file was skipped.
5. Note that if a large number of input files are to be processed in a single call to run_ice_surf_stats.pl, it may be advisable to redirect stdout and stderr to a file by appending
>& logfile
to the run_ice_surf_stats.pl command invoked in step 3, where logfile is the name of a text file that will receive all the messages that normally would appear on the screen. In order to view the logfile while run_ice_surf_stats.pl is running, open another terminal window, cd to the directory that contains the logfile (i.e. the current directory in effect when run_ice_surf_stats.pl was invoked) and type:
tail -f logfile
You will have to press Ctrl-C to exit the tail command once run_ice_surf_stats.pl completes.

How the Software Works

How run_ice_surf_stats.pl Works

• run_ice_surf_stats.pl is given an input directory and an output directory (which defaults to the input directory if it is not provided) as command line parameters.
• A check is made to make sure that the input directory exists.
• If the output directory does not exist, it is created.
• A list of input files from the input directory that matches the template ??????_??????????_??.tif is created.
• Input filenames should be of the form shown in run_ice_surf_stats_usage.
• Each file consists of a 10000 x 10000 pixel color 1-byte TIFF image.
• There are two types of image files:
• 2 class images consist of 3 colors ([red, green, blue] below):
• black = [0, 0, 0] = missing
• sienna = [160, 82, 45] = water
• ivory = [255, 255, 224] = ice
• 3 class images consist of 4 colors ([red, green, blue] below):
• black = [0, 0, 0] = missing
• blue = [0, 0, 255] = open water
• cyan = [0, 255, 255] = melt pond
• ivory = [255, 255, 224] = ice
• For each input file in the list:
• The number of classes is determined by the class code in the input filename.
• An output file name is constructed by:
• stripping off the input directory from the beginning of the input filename and replacing it with the output directory.
• stripping off the .tif from the end of the input filename and replacing it with _stats.txt.
• An example output filename is output.dir/beaufo_2000jun19a_2c_stats.txt.
• The output file (if it exists is deleted).
• The number of classes, the input and output filenames, and a set verbose flag are passed to ice_surf_stats.pro through the Perl script idl_sh.pl.
• Once ice_surf_stats.pro returns, the output file is examined to make sure that it exists and that it contains 404 lines (i.e. 4 header lines and 400 data lines):
• If so, then the call to ice_surf_stats.pro is considered successful.
• Otherwise, the output file (if it exists) is deleted, and the call to ice_surf_stats.pro is considered unsuccessful.
• Once all input files have been processed, a count of the successful and attempted calls to ice_surf_stats is displayed.

How ice_surf_stats.pro Works

• ice_surf_stats.pro is given the number of classes (2 or 3), an input (tif) filename, an output (txt) filename, and an optional verbose flag as parameters.
• If the verbose flag is set, then a message containing the date and time marking the start of processing, together with the values of the passed parameters, is displayed.
• For each 500 x 500 pixel cell (400 cells total) in the input file:
• If processing the first region then:
• The palette and the region data are read.
• The output file is initialized with 4 header lines:
• Sea Ice Surface Characteristics from High Resolution Reconnaissance Imagery data file - F. Fetterer
• the input filename, e.g. 2000jun19a_beaufo_2c.tif
• the current date and time of processing, e.g. Thu Apr  4 18:19:46 2002
• cell  ice   pond  owtr  water
• If not processing the first region, then just the region data are read.
• Fractional coverages for each surface type, as indicated by color ([red, green, blue] below), are computed.
• For 2 class images:
• black = [0, 0, 0] = missing
• sienna = [160, 82, 45] = water
• ivory = [255, 255, 224] = ice
• pond is set to 9.99
• open water (owtr) is set to 9.99
• For 3 class images:
• black = [0, 0, 0] = missing
• blue = [0, 0, 255] = open water (owtr)
• cyan = [0, 255, 255] = melt pond (pond)
• ivory = [255, 255, 224] = ice
• water = owtr + pond
• For both 2 and 3 class images:
• If the region contains any missing values, then all outputs are set to 9.99.
• A data line is written to the output file containing:
• cell - a code identifying each 500 x 500 cell. Each code is of the form RRCC where:
• RR is the cell row (1-20)
• CC is the cell column (1-20)
• fractional ice coverage as computed above
• fractional melt pond (pond) coverage as computed above
• fractional open water (owtr) coverage as computed above
• fractional water coverage as computed above
• Once all 400 cells have been processed, if the verbose flag is set, then a message containing the date and time marking the end of processing, together with the elapsed time required for processing, is displayed.