U.S. Department of the Interior

U.S. Geological Survey

Open-File Report 2013–1300

The Tetracorder User Guide—Version 4.4
The Tetracorder User Guide—Version 4.4

By K. Eric Livo and Roger N. Clark

Open-File Report 2013–1300

U.S. Department of the Interior

U.S. Geological Survey
ii

U.S. Department of the Interior

SALLY JEWELL, Secretary

U.S. Geological Survey

Suzette M. Kimball, Acting Director

U.S. Geological Survey, Reston, Virginia: 2014

For more information on the USGS—the Federal source for science about the Earth,

its natural and living resources, natural hazards, and the environment—visit 

http://www.usgs.gov or call 1–888–ASK–USGS

For an overview of USGS information products, including maps, imagery, and publications,

visit http://www.usgs.gov/pubprod

To order this and other USGS information products, visit http://store.usgs.gov

Suggested citation:

Livo, K.E., Clark, R.N., 2014, The Tetracorder user guide—Version 4.4: U.S. Geological

Survey, Open-File Report 2013‒1300, 52 p., http://dx.doi.org/10.3133/ofr20131300.

ISSN 2331-1258 (online)

Any use of trade, firm, or product names is for descriptive purposes only and does not imply 

endorsement by the U.S. Government.

Although this information product, for the most part, is in the public domain, it also may contain

copyrighted materials as noted in the text. Permission to reproduce copyrighted items must be 

secured from the copyright owner.
iii

Contents

Part I—Getting Started .................................................................................................................................................. 1

Introduction.................................................................................................................................................................... 1

What is Tetracorder? ..................................................................................................................................................... 1

Visualization and Spectral Plots .................................................................................................................................... 9

Part IIa—Quick Start...................................................................................................................................................... 9

Quick Start Steps for MS-Windows® PCs ....................................................................................................................11

Evaluation of Results....................................................................................................................................................11

Part IIb—Running Tetracorder......................................................................................................................................12

More Details .................................................................................................................................................................12

Tetracorder Command-Scripts and Control-Files .........................................................................................................17

Running Tetracorder Directly........................................................................................................................................17

Material-Map Output Files ............................................................................................................................................18

Part III—Tetracorder Details .........................................................................................................................................20

Tetracorder Algorithms .................................................................................................................................................20

Mapping Subdirectory Structure ...................................................................................................................................22

Imaging Spectrometer Data..........................................................................................................................................23

Spectral Library Database ............................................................................................................................................24

Creating/Modifying Tetracorder Script Command Files ................................................................................................24

tetsetup .....................................................................................................................................................................24

tetrun.........................................................................................................................................................................25

r1...............................................................................................................................................................................25

cmds.start.t4.4a ........................................................................................................................................................25

cmds.start.t4.4a.single ..............................................................................................................................................31

cmd.lib.setup.t4.4a5s6 ..............................................................................................................................................31

Comment Section..................................................................................................................................................31

Setup Section........................................................................................................................................................31

Knowledge Base Section ......................................................................................................................................35

Constraints ...................................................................................................................................................................41

Tetracorder Runtime Debugging...................................................................................................................................43

Optional tetracorder.out and tetrun.out.........................................................................................................................44

Image Output Files .......................................................................................................................................................44

References ...................................................................................................................................................................44

Appendix 1—Tetracorder Description and Getting Help ...............................................................................................46

About Tetracorder.....................................................................................................................................................46

Getting Help..............................................................................................................................................................46

Appendix 2—Tetracorder Installation Procedures ........................................................................................................47

Tetracorder Download and Installation......................................................................................................................47

File Structure: UNIX/Linux® and Large MS-Windows® Projects ................................................................................48

Appendix 3—Optional Software....................................................................................................................................48

Optional Programs Installation—Windows® PCs.......................................................................................................49

Optional Programs Installation—LINUX and UNIX®..................................................................................................51

Appendix 4—Data and Spectral Libraries.....................................................................................................................51
iv

Figures

Figure 1. Spectral features with vibrational absorptions near 2.2 microns. Note that alunite also has a 

diagnostic absorption near 1.5 microns, and that the continuum intervals (the green boxes) are at different 

locations for the absorptions in each material. The spectra are offset for clarity. From Clark and others (2003)........... 2

Figure 2. Tetracorder results for well-crystallized kaolinite. The left side of the image contain the results 

coded in red overlaid on a gray-scale image background for context, and on the right side of the image are 

the same results in white on a black background. The results are Tetracorder fit times depth (fit*depth) 

and gamma scaled ........................................................................................................................................................ 5

Figure 3. The GIF format image results for well-crystallized kaolinite, gamma scaled fit*depth. This is the 

same sub-image as the right side of figure 2................................................................................................................. 7

Figure 4. The JPEG format image results for well-crystallized kaolinite, gamma scaled fit*depth on a 

gray-scale background. This is the same sub-image as the left side of figure 2............................................................ 8

Figure 5. Command window showing the inputs to create and set up a mapping directory for Tetracorder 

using the program tetsetup. The responses from tetsetup are shown, and the mapping program tetrun is ready

to be started with the press of the Enter key................................................................................................................ 10

Figure 6. A, the material map directory setup for the start of a mapping run and B, the material map directory 

with the additional directories and output-files after a mapping run (Microsoft Windows® ). They contain the 

mapping image and statistical output ready for analysis, clustered into subdirectory groups of related materials....... 15

Figure 7. Definition of shoulderness from Clark and others (2010)......................................................................... 41

Table

Table 1. Example Tetracorder data structure with subdirectories and data files.................................................... 13
The Tetracorder User Guide—Version 4.4

By K. Eric Livo and Roger N. Clark

Part I—Getting Started

Introduction

Imaging spectroscopy mapping software assists in the identification and mapping of materials 

based on their chemical properties as expressed in spectral measurements of a planet including the solid 

or liquid surface or atmosphere. Such software can be used to analyze field, aircraft, or spacecraft data; 

remote sensing datasets; or laboratory spectra. Tetracorder is a set of software algorithms commanded 

through an expert system to identify materials based on their spectra (Clark and others, 2003).

Tetracorder also can be used in traditional remote sensing analyses, because some of the 

algorithms are a version of a matched filter. Thus, depending on the instructions fed to the Tetracorder 

system, results can range from simple matched filter output, to spectral feature fitting, to full 

identification of surface materials (within the limits of the spectral signatures of materials over the 

spectral range and resolution of the imaging spectroscopy data). A basic understanding of spectroscopy 

by the user is required for developing an optimum mapping strategy and assessing the results.

What is Tetracorder?

Tetracorder is a public domain analysis program that is used to identify specific materials, 

classify image components using spectroscopic data, or both. It also may be used to assist in the 

identification of materials measured using laboratory spectrometers. An important feature of this 

program is the identification of materials. If the spectral features are diagnostic, the identified material 

can be robust, whereas in other cases, the identification requires additional verification. Many other 

spectral identification algorithms simply provide spectra of potential end-members, leaving 

identification of the material up to the analyst. For example, given sufficient spectral resolution, the 2.2-

micron (μm) absorption in the clay mineral kaolinite is diagnostic and the Tetracorder identification is 

robust, but the broad 1 μm absorption in the mineral jadeite only is indicative of a ferrous (Fe2+)-bearing 

mineral because many other Fe2+-bearing minerals have similar absorptions. Tetracorder reports the best 

match, but it is left to the analyst to understand the significance and robustness of any such 

identification.

Tetracorder has been used to map many materials on the Earth and throughout the Solar System, 

ranging from ecosystems (Kokaly and others, 2003, 2007; Karnieli and others, 2001), disaster response 

on land (The World Trade Center disaster; Clark and others, 2001, 2006) and sea (Clark and others, 

2010), mineralogic mapping (Clark and others, 2003; Swayze and others, 2009), site characterization 

(King and others, 2000), to ice on the remote moons of Saturn (Clark and others, 2012 and references 

therein). Tetracorder also was used to map occurrences of water and hydroxyl on the Moon (Clark, 

2009).
2

Tetracorder relies on a spectral library (Clark and others, 2007) of materials. This library of 

materials (which can include minerals, vegetation, snow, and engineered materials – see fig. 1) is used 

to create the material maps apparent spectral abundance, and indicate associations of adjacent materials 

(in areal and linear mixtures). Once mapped using Tetracorder, these material relations may be used to 

help define physical, chemical, and temporal processes that created the target being mapped.

Figure 1. Spectral features with vibrational absorptions near 2.2 microns. Note that alunite also has a diagnostic 

absorption near 1.5 microns, and that the continuum intervals (the green boxes) are at different locations for 

the absorptions in each material. The spectra are offset for clarity. From Clark and others (2003).

Clark and others (2003) described Tetracorder in detail and discussed a number of applications. 

At its most basic level, Tetracorder identifies materials by comparing a remotely sensed observed 

spectrum (the unknown) to a large spectral library of well-characterized materials using techniques that 

maximize accuracy and performance. Importantly, in the comparison of a specific reference to the 

unknown, only the portions of the spectrum that are known to be diagnostic of the reference material are 

used (fig. 1). Every spectral feature is due to an interaction of photons of particular energies with the 

atoms and electrons within the material under study, and the nature of the absorption largely is unique to 

the specific chemical structure and composition. At other wavelengths, photon interactions do not give 

rise to significant absorption; instead, mainly transmission or scattering occurs without strong 

absorption of the incident photons. Taken together, the presence of "active" and "inactive" spectral 

regions for a material gives rise to the concept of a diagnostic absorption feature. Diagnostic absorption 

features are unique to particular materials, vary in shape (variation in intensity with wavelength within a 

narrow interval), and usually are concentrated at specific wavelengths based on their chemical 

compositions (and types of chemical bonds). Between diagnostic features are portions of the spectral 
3

continuum that contain little information specific to the material of interest (i.e., they have no diagnostic 

absorptions). The focus on diagnostic features in analysis of natural scenes is critical because mixtures 

that obey nonlinear systematics (e.g. coatings, intimate mixtures, and solutions) are common in the 

natural environment and frustrate simple matching over large spectral ranges.

In Tetracorder, each comparison of an observed spectrum (unknown) to a reference spectrum is 

highly tailored to the chemistry of the reference material by focusing on diagnostic spectral features 

with pre-programmed instructions based on input from a human spectroscopy expert. This could be the 

user entering tailored commands into Tetracorder just before running it, but is more likely in the form of 

a well-tested command file containing information on hundreds of materials pre-compiled to cover a 

wide range of applications (Clark and others, 2003). The tailoring of these pre-packaged instructions is 

based on specific expert knowledge of a team of spectroscopists, geologists, and biologists. By 

neglecting portions of the spectrum that are less relevant to the chemistry of the reference material, 

Tetracorder reduces noise or clutter induced by these "inactive" wavelengths. Tetracorder can recognize 

the spectrally dominant material in a pixel even when that material has spectral features that overlap 

with those of other materials. It can also map both areal and intimate mixtures of materials if spectra of 

those material mixtures are included in its library, or if the spectral features do not overlap. In addition, 

Tetracorder can, and routinely does, detect the presence of multiple materials in a spectrum without 

performing unmixing analyses required by some other systems. For example, consider an intimate 

mixture of iron oxides and clays where the diagnostic electronic spectral absorptions of iron oxides are 

in the visible to 1.3 μm wavelength range, whereas clay minerals exhibit vibrational diagnostic 

overtone and combination absorptions between 1.4 and 2.5 μm. Material maps of both spectral regions 

can be produced simultaneously showing the spectrally dominant material in each spectral region. Even 

though the presence of multiple materials within a given pixel may dilute the strength of their spectral 

features relative to those in a reference spectrum, Tetracorder’s continuum removal and shape matching 

technique locates the most important spectral similarities and, through competition, picks the most 

likely match at relatively low signal-to-noise ratios (Clark and others, 2003; Swayze and others, 2003).

Tetracorder has the ability to apply different algorithms to different situations. Also, the output 

of one analysis can be directed into additional algorithms for further analyses. In principle, there is no 

limit to the number of analytical steps that may be performed on a single spectrum or on whole imaging 

spectrometer datasets. 

Subsequent to the Clark and others (2003) description of Tetracorder, new features have been 

added, including fuzzy logic and shoulderness (Clark and others, 2010). This user manual is based on 

Tetracorder version 4.4, which was used to map oil on the ocean's surface in the Deepwater Horizon oil 

spill in the Gulf of Mexico (Clark and others, 2010).

The principle Tetracorder algorithms are:

1. Ratio spectra

2. Modified least-squares spectral feature fitting algorithm

3. Red edge or blue edge characterization

4. Hooks for future algorithms

Additional algorithms for the above include:

1. Continuum removal

2. Continuum band center threshold with fuzzy logic
4

3. Left continuum threshold with fuzzy logic

4. Right continuum threshold with fuzzy logic

5. Left shoulderness with fuzzy logic

6. Right shoulderness with fuzzy logic

7. Left/right continuum ratio with fuzzy logic

8. Right/left continuum ratio with fuzzy logic

9. Reflectance times band-depth limits with fuzzy logic

10. Constraint analysis

11. Identification analysis

The output of each algorithm includes a quality and magnitude measure. For example, the 

spectral feature fitting algorithm derives a least-squares correlation-coefficient ranging from 0.0 to 1.0, 

with zero being a poor fit and 1 being an excellent match between the library and unknown spectral 

feature. The magnitude parameter is the derived band-depth of the feature (Clark and Roush, 1984). 

Note that band-depth can be negative, which indicates an emission feature; positive values indicate an 

absorption feature. Multiple spectral features can be included for one reference material, in which case 

the output is weighted by the areas of the continuum-removed spectral features. From the two output 

values, a third output is derived: magnitude times quality (that is, the band-depth multiplied by 

correlation-coefficient, weighted by the areas of the absorption features). The three values result in three 

output images with file extensions: .fit, .depth, and .fd (fit times depth, also defined as fit*depth), where 

fit is the correlation-coefficient or other quality parameter, depth is the magnitude of the spectral feature 

of interest, and fd is the weighted fit multiplied by weighted depth. Output can be either 8-bit or 16-bit 

scaled integers.

Hooks are in place for future algorithms, both primary and support, including elevation (either 

digital elevation, lidar, or other such information) and physical constraints such as temperature and 

pressure (some materials are stable only at certain pressures, temperatures, or both, hence additional 

constraints may be applied to determine when materials might be viable options or should be excluded 

from consideration).

For a given reference material and its spectrum, multiple spectral features can be analyzed 

(fig. 1), potentially improving the spectral identification of the unknowns. In those cases, the final 

weighted fit, depth, and fd for each spectral comparison is computed by summing every one of the 

individual absorption feature fit’s, depth’s, or fd’s, then normalizing the summations (Clark and others, 

2003). Currently (2013), the weighting value for each spectral feature fit, depth, and fd is automatically 

determined by the area of the continuum defined absorption or emission feature, but planned into future 

releases, the expert system will be able to modify the weighting value of each spectral feature analyzed. 

Fuzzy logic (Clark and others, 2010) is a tool to degrade an answer as the signal-to-noise ratio 

drops because of low signal or low abundance. An expert spectroscopist may examine a spectrum and 

determine that an absorption feature may look like that from material X, but material Y is similar and 

the signal-to-noise ratio of the spectral data may not be sufficient to tell them apart. Rather than a hard 

threshold, fuzzy logic makes the identification threshold (fit, depth, or fit*depth) a variable depending 

on user defined conditions. Presently, a threshold ramp is applied (multiplied) over a defined lower 

threshold value range that linearly varies from 1.0 at the value range top to 0.0 at the value range 

bottom.
5

The instructions derived for a Tetracorder analysis can be used to solve many types of remote 

sensing problems. An ideal case in point could be a Tetracorder derived surface map of a mineral 

deposit that shows changes in wallrock lithology, offsetting faults and other structural control, and 

variations in altered rock mineralogy that controlled where late-stage fluids deposited ore. Another 

example could be oil distribution, abundance, changes in oil emulsification, and ecosystem impacts of 

offshore spills. See Clark and others (2003, 2010) for examples.

Once an expert system command file is set up by a spectroscopist, Tetracorder can be run on 

many datasets with simple setup. The support programs (included in the distribution package) create 

quick-view JPEG images for rapid assessment by a user. For example, our default Tetracorder command 

set includes 328 materials (minerals, man-made materials, vegetation, and liquid water and ice reference 

spectra; command setup 4.4a5s6), so 328 materials could need assessing for generalized mapping. The 

advantage of Tetracorder, however, is that if you are interested in only one material, then only the 

results for that material need to be examined. Clark and others (2003) illustrate how the identification 

step of Tetracorder enables this using a search for well-crystallized kaolinite. Other remote sensing 

analyses only give broad indicators of the presence of a specific material with many false positives, 

whereas Tetracorder isolates those pixels with the best answer (see well-crystallized kaolinite in fig. 2).

Figure 2. Tetracorder results for well-crystallized kaolinite. The left side of the image contain the results coded in 

red overlaid on a gray-scale image background for context, and on the right side of the image are the same 

results in white on a black background. The results are Tetracorder fit times depth (fit*depth) and gamma 

scaled.
6

Once the Tetracorder program is complete, the script that runs Tetracorder executes additional 

programs that analyze results, including a cluster analysis to produce a report of what was found. Next, 

some output images are added together so a better summary can be assessed. For example, Tetracorder 

maps a number of hematite (iron oxide) grain sizes. All the hematite grain size images are added 

together into a hematite.all image so that only one image of hematite needs to be examined. Finally, a 

program is run that auto-stretches each Tetracorder .fd image and creates a gamma-stretched GIF 

images of pixels present in white/gray on a black background (fig. 3), and a second set of images with 

the pixels present in red on a gray scale image background beside the same pixels on a black 

background (fig. 4). The gamma stretch mimics the stretch used in consumer digital camera images. 

These images can be assessed quickly using many different image viewing programs. Viewing 

Tetracorder results thus requires no specialized software unless you want to extract spectra.
7

Figure 3. The GIF format image results for well-crystallized kaolinite, gamma scaled fit*depth. This is the same 

sub-image as the right side of figure 2.
8

Figure 4. The JPEG format image results for well-crystallized kaolinite, gamma scaled fit*depth on a gray-scale 

background. This is the same sub-image as the left side of figure 2.
9

Visualization and Spectral Plots

Most computers contain image viewing programs that can display the GIF and JPEG images 

produced by Tetracorder and the post-processing software. But, specialized software is needed to link to 

the image spectrometer datacube for advanced spectral analysis of select pixels. Plotting pixel spectra 

and zooming to highlight spatial detail is a fundamental requirement while interpreting mapping results. 

It is important that mapping quality and accuracy be assessed; these programs enable a spectroscopist to 

visually roam and examine the datacube and mapping results and their use is outside the scope of this 

manual. See http://speclab.cr.usgs.gov/software.html for more details and links to some software, such 

as Kokaly (2011). Some commercial imaging software packages can also extract spectra from image 

cubes.

Part IIa—Quick Start

The instructions below require the program Tetracorder, and optionally the programs Davinci, 

GNU ppmtogif, and GNU GZIP (freeware shared under the GNU General Public License). Tetracorder 

produces the material maps for analysis and is fully self-contained. The optional programs are used for 

generating post-processing results, making assessment of results simpler. Davinci is used for numerous 

functions varying from calculating mapping statistics to refining material map output. Ppmtogif and 

GZIP will convert material maps to GIF images and are used to compress them.

The quick start steps install the Tetracorder system and included demo data for use with MSWindows® personal computers (pcs) using the downloaded file tetracorder4.4-tutorial.zip. This file also 

may be used for an UNIX/Linux® tutorial, but requires the Tetracorder source code (present within this 

zip file) to be compiled, and various included data files to be placed in specific locations in the file 

system. Installation and setup for Windows and UNIX/Linux® systems are described fully in appendixes 

1 and 2.

This demo setup uses a simple directory structure to find data and place the results. This 

familiarizes the user with Tetracorder operations and is useful for moderate scale studies. A more 

flexible, but more complex, setup is described in appendix 1 for large projects. Fig. 5 shows the inputs 

required to create and setup a mapping directory for use once Tetracorder has been installed.
10

Figure 5. Command window showing the inputs to create and set up a mapping directory for Tetracorder using 

the program tetsetup. The responses from tetsetup are shown, and the mapping program tetrun is ready to be 

started with the press of the Enter key.
11

Quick Start Steps for MS-Windows® PCs

MS Windows:

Download the file: tetracorder4.4-tutorial.zip located in the links at the U.S. Geological Survey 

(USGS) Web site, http://speclab.cr.usgs.gov/software.html.

Unzip tetracorder4.4-tutorial.zip, preferably in the root directory (C:\tetracorder4.4). This 

contains all the files (Tetracorder program, batch-scripts, data, and source code) required to map a demo 

dataset of Cuprite, Nevada using a MS-Windows® computer (see appendix 2 to install an UNIX/Linux® 

Tetracorder version for use with these files). All user commands and datasets in this basic setup are 

identical within Windows and UNIX/Linux® environments.

Optionally, install Davinci for post-processing of mapping results (see appendix 2).

Create a new mapping directory and install the required files and file structure by running 

tetsetup. The mapping directory will contain all the future generated output of the initial mapping run.

Start a command window:

(Start -> All Programs -> Accessories -> Command Prompt)

Change directory to the Tetracorder mapping area:

CD c:\tetracorder4.4\mapping

Run tetsetup with the three command line arguments:

..\tetracorder4.4.cmds.lib06\tetsetup mapping-cuprite aviris_1995 ..\..\cubes\cuprite95

The three command line arguments are:

Arg 1 - your chosen name for your mapping directory

Arg 2 - sensor with year code (e.g. aviris_1995),

Arg 3 - file system path to the image cube,

executing tetsetup with no arguments shows the options.

Change to the mapping directory: c:\tetracorder4.4\mapping\mapping-cuprite

CD mapping-cuprite

Start a mapping run

tetrun

Evaluate results.

Tetracorder output—Material maps in VICAR and ENVI® formats are generated. Special 

software is required for viewing and analysis.

Davinci assisted mapping runs—The tetrun script runs Tetracorder to generate material map 

output, then performs post-processing that will generate mapping statistics text files and convert the 

material maps into easily viewed GIF and JPEG files. In-depth analysis requires special software.

Evaluation of Results

Once Tetracorder completes generating the mapped-material images the tetrun script runs 

optional additional programs to aid in fast evaluation of results. Various statistical text files and 

mapped-material (JPEG and GIF) image files are generated for use in a quick, preliminary evaluation of 

the mapping run. These files can be opened in most text editors and image viewing programs that come 

with your computer’s operating system. A brief description of these files is provided below, but a 

common analysis flow would be to quickly scroll through the results and results.cluster statistical text 

files to pick up on the common materials mapped, while also looking for outlying materials, then 

examine the mapped-material images (either GIF or JPEG) for spatial context and material associations. 

Comprehensive analysis of the results may then proceed, using specialized remote sensing software 
12

such as the USGS Processing Routines in IDL for Spectroscopic Measurements (PRISM), PicWorks 

(PW), and Spectrum Processing Routines (SPECPR) packages, where the mapped-material images can 

be examined while spectrally linked to the image spectrometer data.

WARNING: Tetracorder finds the best match to entries in the reference spectral library, but 

not all spectral features are uniquely diagnostic, and many materials are not yet included in the 

reference library. It is up to the user and expert spectroscopist to determine the accuracy and 

uniqueness of any Tetracorder mapping results (see the “More Details” section below).

The file results is a text file that lists the number of pixels mapped for each reference material.

The file results.cluster shows clustering statics for each reference material mapped. The 

clustering algorithm is from the program Davinci and higher clustering values at a larger pixel radius 

indicate there is a greater probability that the image has significant patterns that may be of interest.

The file results.cluster.sorted shows clustering from the results.cluster file above, sorted with 

the highest cluster results at the top for each group and case, plus a subjective word to describe 

significance (from most to least significant): WOW, Great, good, maybe, none, and zero. The zero 

designation is for no pixels mapped, whereas the none designation means some pixels mapped but the 

result looks like random noise.

Next, you can view image results. In each group* and case* directory are gamma-stretched 

images saved in GIF format that can be viewed with most standard image viewers (fig. 3). These images 

are gamma-stretched (a similar algorithm to that used in digital camera images) by a Davinci program 

so details in high as well as low signal results can be seen without having to re-stretch the image. If you 

are searching for a small signal, the Davinci program can be tuned to give a stronger stretch.

Another way to view image results is to view the JPEG images in the directories results.group.*

and results.case.*. These JPEG images have the same gamma-stretched images from the above GIF 

files, but color coded in shades of red and displayed on a grey-scale background (fig. 4).

If your image is not too wide for your screen, the best of both of the above presentations are 

stored in the results.dual.* directories. Here, the red overlay on a gray-scale background shows the 

context, whereas the results on the black background are better to pick out small clusters of pixels that 

may have mapped at a low level (fig. 2).

It is critical that once you have found a material that mapped well, which you want to include 

on a map or report as found, the spectra of its type locations be extracted and examined to verify that 

the identification is correct. See the “Material-Map Output Files” section, below for additional 

details.

Part IIb—Running Tetracorder

This section covers the installation, setup, and startup of a Tetracorder mapping system of 

software and data. The Tetracorder tutorial system of programs and datasets will be set up in a simple 

file structure useful for local mapping projects (see appendix 2 for a production setup description). MSWindows® PCs can directly use this set of programs and data as installed for a fully functioning 

Tetracorder mapping system. UNIX/Linux® systems will require the compilation of supplied source 

code and placement of files as described in appendix 2.

More Details

Step 1

Download the file tetracorder4.4-tutorial.zip via the USGS Web site: 

http://speclab.cr.usgs.gov/software.html. Several zip files will be located together, including the tutorial 
13

zip file. The tutorial zip file is a stand-alone implementation of Tetracorder, and the other files are 

updates of software and data that include additional datacubes and spectral libraries that may be 

downloaded as required in the future.

Step 2

Uncompress the tutorial dataset tetracorder44-tutorial.zip into the subdirectory of choice, 

preferably c:\. This step unpacks a variety of data into a tree directory structure with a base name of 

tetracorder4.4. The significant directories are shown in Table 1. Importantly, for the user, the material 

map directory will contain all the Tetracorder output for mapping-run analysis, in this case, named 

/mapping-cuprite/.

Table 1. Example Tetracorder data structure with subdirectories and data files.

c:\tetracorder4.4\

\README.txt

\bin-pc\ (MS-Windows program directory)

(various programs and script files)

\cubes\ (image spectrometer datacubes)

cuprite95

cuprite95.hdr

\docs\ (documents)

Tetracorder44_user-guide.pdf (this file)

\mapping\ (global mapping directory to hold multiple material map directories)

To be created: \mapping-cuprite\ (material map directory ready for material run)

(various scripts used in the mapping run and directories for output)

\speclib\

\library06.conv\

\s06av95a (Material spectral library for AVIRIS 1995)

\src-local\

\specpr\ (source code for SPECPR)

\tetracorder4.4\ (source code for Tetracorder)

\tetracorder4.4.cmds.lib06\

\(various setup master files)

\usr.local.bin_tetracorder_support\

\(various executable scripts for UNIX/Linux® )

The data structure of the material map directory before running Tetracorder is listed in figure 

6A. Each mapping run requires its own material map directory, usually generated by running the 

program tetsetup. The directory may have any name; a short descriptive name works well.
14

A
15

B

Figure 6. A, the material map directory setup for the start of a mapping run and B, the material map directory with 

the additional directories and output-files after a mapping run (Microsoft Windows® ). They contain the mapping 

image and statistical output ready for analysis, clustered into subdirectory groups of related materials.

The data structure of the material map directory after running Tetracorder and the optional 

Davinci post-processing scripts are listed in figure 6B. The additional directories and files contain 

mapped output (text files and images) that will be used in the mapping analysis.

The GIF images of the mapping results (images like the right side of fig. 2) are located in each 

.\group* and .\case* directories. For example, the kaolinite wxl results are in 
16

.\group.2um\kaolwxl.fd.gif, .\results.group.2um/kaolwxl.fd.ovrly.gstr.jpg, and 

.\results.dual.group.2um/kaolwxl.fd.ovrly.lstr.jpg.

The subdirectory .\cubes contains the imaging spectrometer data (unless the command file points 

to datacubes somewhere else), .\docs contains this user manual, .\speclib contains the spectral library 

files, and .\mapping-cuprite contains files and subdirectories used by Tetracorder to produce the 

material maps. The subdirectory and file names within \data\tetracorder\ are embedded in the tutorial 

Tetracorder command files. If these names are changed, then the corresponding names in the command 

files must similarly be edited.

Using the tutorial simplifies the setup process. For most projects, the data must be calibrated, 

spectral libraries convolved, and Tetracorder command files edited to fit each application. Iterative runs 

of Tetracorder may be needed to fine tune the expert system, especially if mapping in an area that 

includes materials not in the current expert system. Advanced execution of Tetracorder is covered in 

PART III—Tetracorder Details.

Step 3

Download and install Davinci, as explained in appendix 2, if post-processing of the material 

maps is desired. This is not needed for analysis, but enables rapid viewing of the material map images 

and calculates clustering and cumulative statistics.

Step 4

Create a new mapping directory and install the required files and file structure by running the 

script tetsetup within a command window (Command Prompt). The mapping directory will contain all 

the future generated output of the initial mapping run. Tetsetup is located in the 

.\tetracorder4.4.cmds.lib06 directory. This directory has the same parent directory as the mapping

directory that will hold all the material map subdirectories (see fig. 6A). From the mapping directory, 

tetsetup is called using the indirect path command: ..\tetracorder4.4.cmds.lib06; it can also be started 

using its full path name. Tetsetup requires three command line arguments that will be used to place the 

material map directory, set the proper spectral specifications for the dataset in use, and find the imaging 

spectrometer datacube. See figure 5 for an example.

Start a command window:

(Start -> All Programs -> Accessories -> Command Prompt)

Change directory to the Tetracorder mapping area

(CD c:\tetracorder4.4\mapping)

Run tetsetup with the three command line arguments:

(..\tetracorder4.4.cmds.lib06\tetsetup mapping-cuprite aviris_1995 ..\..\cubes\cuprite95)

Note the total length of the path plus cube file name can be no more than 70 characters, or the 

name will be truncated.

Steps 5 and 6

Set the current working directory to the material map directory (mapping-cuprite) and run 

Tetracorder using the script: tetrun. Run Tetracorder to generate material map images and, if the 
17

program Davinci is installed, post-processing analysis will create statistic text files and reformat the 

material maps into GIF and JPEG formats.

Change to the mapping-run directory:

c:\tetracorder4.4\mapping\mapping-cuprite

(CD mapping-cuprite)

Start a mapping run

(tetrun)

Step 7

Evaluate the Tetracorder results.

Tetracorder Command-Scripts and Control-Files

Tetracorder, as set up in this tutorial, requires the text restart file (r1) and two command scripts 

(cmds.start.t4.4a or cmds.start.t4.4a.single, and cmd.lib.setup.t4.4a5s6 or newer). An additional script: 

tetrun, though optional, is recommended highly and completes several post-run mapping operations to 

aid in rapid analysis of the results. Each of these files may be renamed as desired and their 

implementation is described below in the section Running Tetracorder. The command scripts, which 

can contain several hundred thousand typed characters, save the user from manually typing the 

Tetracorder commands. All these files easily are edited using any text editor (but tetsetup usually is 

used) and can serve as an archive processing history of each Tetracorder run. See Part III for details on 

these files.

Running Tetracorder Directly

One also can run tetracorder directly using its “restart” file r1 to locate the material spectral 

library(ies)..

type: tetracorder r1

Tetracorder will read in a series of commands and data from the file cmds.start.t4.4a, then it will 

be directed automatically by cmds.start.t4.4a to read in additional setup data from the file 

(cmd.lib.setup.t4.4a5s6 or later). The Tetracorder commands are split into two files for the following 

reason: the cmds.start.t4.4a file has user editable entries that may change from cube to cube, such as the 

cube name and what deleted points to use. The cmd.lib.setup.t4.4a5s6 file contains the expert system 

commands to do the identifications and generally only is modified by an expert spectroscopist.

Tetracorder then performs the mapping analysis using the newly loaded instructions and will run 

until completion. This may take a while (e.g., minutes to hours) depending on the size of the datacube 

and computer speed. The processed scan lines will be listed within the command window as Tetracorder 

runs. Material map images (three files per material as set within the command file) will be created by 

Tetracorder upon completion of the mapping run. These material maps may be analyzed using image 

processing software (see appendix 2 for suggested software). The output image files have two formats, 

VICAR and ENVI®, so image processing programs that read these formats can directly read Tetracorder 

output files. The tetrun script then creates the results text file reports, gamma-stretched GIF image 

results, and side-by-side dual images JPEG results and single image JPEG results. Note that the side-by-
18

side JPEG results will fail if the combined image is wider than 32,767 pixels. Tetracorder can analyze 

images cubes as wide as 32,765 pixels as compiled for this distribution (these sizes can be increased as 

needed given the ability of the computer system to handle such large datasets).

A special case is where a single spectrum will be analyzed against a material spectral library 

using Tetracorder. The spectrum must be a data record within a SPECPR formatted spectral library file; 

no data cube is required. This spectrum can be of a material measured using a handheld or lab 

spectrometer, or a material spectrum extracted from a dataset such as a classified end-member. Start 

Tetracorder as described above but use the redirected command script <cmds.start.t4.4a.single in place 

of <cmds.start.t4.4a and follow the prompts. In this mode, Tetracorder will read a spectrum from a

SPECPR-format data file for analysis. Note the spectrum to be analyzed must have the same bandpass 

and sampling as the spectral library and the expert system must be using that library.

Material-Map Output Files

Output from Tetracorder analysis must be checked for quality and appropriateness based on a 

realistic understanding of the specific application and expected results. The goal is to derive images of 

mapped materials that are correct, comprehensive, and useful for the study at hand. This is the step 

where human knowledge is required to decide whether the results need further refinement with a new 

Tetracorder run, or if the results are satisfactory and can be used for their intended purpose. For 

example, two very different materials may have spectrally similar absorption features that may be 

confused because of an imperfect data calibration, low signal-to-noise ratio, or fundamental limits on 

the spectral uniqueness of different materials, or some combination of all of these. If a new Tetracorder 

run is required, it is crucial to understand why the initial processing stage produced the given results, 

how the selected materials spectrally competed with each other based on a given Tetracorder command 

file protocol, and what changes within the command files, data calibration, or laboratory spectra are 

needed to improve the results. When doing iterative Tetracorder runs, change a minimum number of 

factors for each run and work to understand where changes to the command file protocol affect mapping 

output. Excessive modification of the command files for the problem at hand transfers mapping results 

from the production category into new research areas that require independent verification. The goal is 

to design command files that can be used to robustly map any area regardless of location and 

environmental conditions.

Tetracorder subdivides mineral-map output into groups and cases. Using the strategy derived by 

Clark and others (2003), map groups usually are separated into 1- and 2 μm groups (the default 

configuration using the supplied command-library-setup file). Any diagnostic spectral features can be 

used in the identification of a material, but spectrally similar materials compete for the best fit within 

their own group, as defined within the command-library-setup file (i.e., materials with strong electronic 

absorptions compete in the 1-μm group, whereas materials with strong vibrational absorptions compete 

in the 2-μm group). Material-maps from each group are written to their respective group subdirectories. 

Special case analyses are then performed on the group output as defined with results written to each 

case subdirectory (e.g., case.veg.type and case.ep-cal-chl; see Clark and others, 2003).

As previously discussed, Tetracorder outputs three files for each material mapped within a 

processing group or case; a least-squares-fit image, a band-depth image, and an image of the two 

multiplied together (fit times depth). The data number (DN) range is set by the command-library-setup 

file and the numeric precision can be set to either 8- or 16-bit integers (scaled data values ranging from 

0 to 255 or 0 to 32,767, respectively). Materials identified by Tetracorder will have their pixel locations 

marked with positive DN values within their least-squares-fit, band-depth, and fit-times-depth images. 

Usually, the higher the DN values, the more robust the identification. Only the identified material’s 
19

pixels contain positive values. Image pixels for those locations within all other images are set to a DN of 

zero. The fit image is used for material identification, where pixel values for the identified material are 

the highest among all the materials tested. A DN of 255 corresponds to a weighted fit of 1.0. The banddepth image shows the relative band-depths for the nonzeroed DN pixels, where increasing band-depth 

usually is associated with increasing spectral abundance. The band-depth for DN=255 is set differently 

for each material in the expert system. For visual data analysis, we have found that the fit-times-depth 

images are very useful for characterizing mapping results. They combine the mineral identification 

strengths with spectral abundance to suggest well mapped areas.

The mineral-map output files are written in VICAR format with an ENVI® header file and may 

be analyzed directly using an imaging spectroscopy processing system, such as PW, ENVI®, or 

Hypercube (see appendix 2 under optional software for these programs). Any of these programs allow 

checks of mapping quality by visual examination of plotted pixel spectra from the material map using its 

co-linked datacube. Thresholds for image DNs can be set and DN ranges can be modified. Map 

composites of several images may be used to examine material spatial relationships. If user analysis has 

been performed by tetrun using Davinci or by clustering routines in the other image processing 

packages, spatial details can be recognized.

Spectra of surface materials can be checked visually for agreement with the names assigned by 

Tetracorder or the user may choose a name that better suits that material. For example, many minerals 

contain broad Fe2+ absorptions. Unfortunately, these absorptions overlap, and with mixtures and 

differing grain sizes it can be difficult to actually identify a specific mineralogy. Thus Fe2+

identifications usually are generic (e.g. Jadeite, Cummingtonite, Basalt_fresh, and others) and should 

not be labeled as that specific mineralogy, but something more like generic Fe2+-bearing mineral.

Another example might be when one is mapping a material that does not exist in the expert 

system library setup. For example, when mapping polar regions of Mars with MRO CRISM 

spectrometer data, Tetracorder identified scattered pixels with a 2.39-μm absorption as portlandite, a 

mineral binder in cement (present in our standard command file because of our work on the World 

Trade Center dust). A quick check of extracted spectra showed the absence of a subsidiary absorption 

expected at 1.41 μm. The Phoenix Lander actually had chemically identified perchlorate in the soils 

only a few tens of kilometers from these pixels. We took laboratory spectra of the perchlorate chemical 

reagents on hand and found several with similar 2.39-μm absorptions. It turned out that the Tetracorder 

command file we used for mapping did not have any perchlorate spectral entries. Although Tetracorder 

incorrectly labeled the material on the surface as portlandite, visual examination of extracted spectra 

potentially revealed a new category of minerals previously not identified from Martian orbit. If 

Tetracorder does not have an exact spectral match to certain surface materials in its command file, but 

the spectral match is high with a spectrally similar material, that material may be selected. Normally, 

with a lower goodness-of-fit value, no match is found and no mineral is identified. Upon investigation, 

this commonly leads to the recognition of materials not planned for in the initial Tetracorder mapping 

runs. In this way, iterative Tetracorder runs can be used to fine tune a command file to a specific 

application.

Once the material-maps are judged correct, they can be applied to the study topic. Composite 

material-maps can be assembled, data relationships can be explored within image processing and GIS 

packages, and material formation or chemical processes may be inferred. Further discussion of data 

analysis and quality control will be described in Part IV—Data Analysis.
20

Part III—Tetracorder Details

Tetracorder is a set of algorithms commanded by an expert system decision-making framework 

applicable to a wide range of spectroscopic studies (Clark and others, 2003). It is an open system 

tailored for use in applications that demand a flexible tool that yields rigorous detailed results and it is 

highly customizable. Because Tetracorder is a command driven program controlled by scripts (batch 

files) that allow customization, the setup configuration is flexible and can be made to accommodate 

requirements of the study and the processing procedures defined by investigators. Tetracorder command 

files (scripts) define all analysis steps and along with algorithm usage, control the output results. Any 

number of custom scripts can be used to control Tetracorder, but for standardized processing, a series of 

editable command scripts incorporating variable substitution and file redirection have been developed 

using the SPECPR interface (Clark, 1980, 1993). Batch processing of multiple sets of spectrometer data 

enable rapid analysis of large surface areas, the largest to date being most of the Moon’s surface. 

The Tetracorder algorithm requires imaging spectrometer data or a single material spectrum that 

will be tested against a spectral library of one or more materials, usually using a continuum-removed 

shape-matching algorithm. Each pixel of data will be tested against spectral features from each selected 

material within the spectral library. Importantly, each test may be tailored to include diagnostic spectral 

features of the particular library material, including the feature continuum unique to that material. 

Material band-depths are scaled to the pixel band-depths, and various parameter rules unique to each 

test material are used for decision making within the test.

Tetracorder Algorithms

The main Tetracorder framework is composed of algorithms and decision making (expert system 

rules), which include:

• Shape-matching (weighted goodness-of-fit over multiple absorption features).

• Comparisons of observed spectra with library spectra of materials, independently, one material at a 

time. Only diagnostic portions of each library spectra are used.

• Performing partition analyses across the spectrum using groups and cases.

• Assessing the similarity of an observed spectrum to all entries in the Tetracorder command file with 

similar diagnostic features.

• Applying “Not This Material” tests.

• Returning a “no answer” with nondetection determination.

• Uses ancillary spectral information, including reflectance level, local feature continuum slope, 

shoulderness (new since Clark and others, 2003), and band-depth.

• Applying independent threshold limits and weighting factors used on each diagnostic spectral 

feature of the observed spectrum.

• Using fuzzy logic applied to the above thresholds (new since Clark and others, 2003).

• Vegetation red edge shift detection.

The shape-matching algorithm uses a weighted least-squares goodness-of-fit test, to correlate the 

observed spectrum against a series of well-characterized library spectra, one material at a time (Clark 

and others, 2003). Each test correlates spectra over a series of wavelength intervals containing multiple 

absorption features. Nondiagnostic wavelength ranges are not included. Diagnostic absorption features 

for each library material spectrum are predefined (see cmd.libsetup.t4.4a5s6 described below) to be 

tested for existence against the reference spectrum. Their absorption band-depths are scaled during the 
21

correlation to match the observed spectrum. This allows tests of the diagnostic absorption features that 

characterize each library material spectrum, where each material has a custom selected absorption 

interval, or intervals, different from the other materials within the library (see Clark and others, 2003). 

The observed spectrum is identified as the reference material whose correlation has the highest fit value, 

or no identification is made, depending on the findings of the additional algorithms described below. 

For a history of the development of this algorithm and case studies, see Clark and others (2003).

Only diagnostic portions of the reference spectrum are used for examination. Comparison of the 

observed spectrum with the reference spectrum uses one or more spectral features where each feature 

independently is fitted with a custom continuum. Continuum end-points are selected individually for 

each spectral feature to be tested within the reference spectrum.

For multiple-material identification and for special identification procedures using the observed 

spectrum, an algorithm performs partition analyses across the spectrum using groups and cases. Because 

different photon absorption processes tend to operate in different wavelength ranges, we split the 

spectral identification into several spectral regions, which are called groups. This allows multiple 

components to be identified without the need for mixture analysis (see Clark and others, 2003). 

Procedures tailored to separate specific material groups into well-defined components with special 

analysis routines are done in case studies. These results are placed within the case subdirectories.

The assessment of similarity of an observed spectrum to all entries in the Tetracorder command 

file with similar diagnostic features is a key Tetracorder algorithm. This is the identification step. 

Tetracorder mitigates false alarms caused by spectrally similar materials by quantitatively comparing 

the degree of similarity of an unknown to a set of spectrally similar reference spectra (see Clark and 

others, 2003).

Further refinement of material identification uses “Not This Material” tests. In some cases, a 

material may have a nearly identical absorption feature as another material, but the second material has 

additional spectral features. To identify the first material, a test is made for the lack of presence of the 

second absorption (see Clark and others, 2003).

A critical Tetracorder algorithm is returning a “no answer” with nondetection determination. It is 

a frequent occurrence that a remotely sensed spectrum does not pass even the liberal thresholds 

necessary to assign any candidate detections. In other cases the constraints applied to resolve 

ambiguities results in a rejection of an unknown in every case. Tetracorder explicitly flags a spectrum as 

a "no answer" that has no similarities to entries in the library as defined in the expert system.

In the shape matching exercise performed on each library entry for an unknown, Tetracorder 

extracts all the constraints required to perform and refine detection. The identification of materials from 

their spectra is constrained by (1) the goodness of fit of a spectral feature to a reference feature, (2) 

reflectance level, (3) continuum level and slope, (4) presence or absence of key ancillary spectral 

features, and (5) shoulderness (new since Clark and others, 2003).

Every diagnostic feature defined for a library material will have a continuum set for the feature’s 

wavelength interval that normalizes the feature’s spectral response, and independent threshold limits 

will be set on variables that characterize it (see Clark and others, 2003; cmd.libsetup.t4.4a5 described 

below). Weighing factors are used to modify a material’s summed fit and depth values using multiple 

absorption features. These factors are automatically calculated using absorption feature areas. Threshold 

limits are used to deny a material identification once their values are exceeded. These limits are used 

with ancillary spectral information, including reflectance level; local feature continuum slope; and banddepth.

Setting fuzzy logic thresholds mimics the spectroscopic analyst’s idea that, as the correlation 

between imaging spectrometer data and reference spectra decreases, the confidence in the identification 
22

decreases. Rather than a hard threshold used in Clark and others (2003), where the fit was set to zero 

below the threshold, the fuzzy logic modifies the fit linearly between two thresholds. The fuzzy logic 2-

point threshold modifies the fit according to the equations in Clark and others (2010):

Fuzz = 1.0 when parameter > upper threshold t2,

Fuzz = 0.0 when parameter < lower threshold t1,

Fuzz = (p – t1) / (t2 – t1), where p is the parameter under test and t1 < p < t2

Fit = Fit x Fuzz.

An example fuzzy logic threshold could be set from 0.75 to 0.85. Then, a modified fit value 

would be 0.85 with an original fit value of 0.85 (0.85x1.0). If the fit computation was 0.8, then a 

modified fit value halfway into the fuzzy logic threshold interval would be 0.80x0.5= 0.40. All fit 

values above 0.85 would remain unchanged while all fit values below 0.75 would be set to 0.0 for 

spectral correlation using that diagnostic feature.

Vegetation red edge shift detection uses a ratio method (Clark and others, 2003). The position of 

the chlorophyll red edge absorption feature can be found by ratioing to a fixed reference spectrum 

(Clark and others, 1995; Clark, 1999). Detection of shifts a fraction of the channel-to-channel spacing is 

possible with a ratio method. The reference spectrum (unshifted) divided by the unknown (shifted) 

spectrum produces a ratio spectral feature and the spectral intensity and structure in this ratio is 

proportional to the red edge position. This special case, case 1, is done only if vegetation is detected by 

an analysis in group 3. 

Similar methods could be employed to track shifts in spectral features in other materials. For 

example, this method could be used to track temperature when an absorption band shifts wavelength 

position with temperature, like the conduction band edge in sulfur. 

Material mapping may require a few iterations when investigating new avenues of research. 

Spectra of new materials may need to be added to the command file and the decision-making mapping 

rules may need to be optimized for each new material (see spectral library command file below). Test 

runs of Tetracorder are generated and the mineral mapping quality is assessed when new additions are 

made. New mapping runs may be needed until the command file is adequately robust for the intended 

mapping purposes. Quality assessment of new investigations varies with a given application, but usually 

requires post-processing checks, through combinations of prior knowledge, field investigations, and 

manual analysis of the results (i.e., spectral extractions) and spatial relationships. The goal is to derive 

an inclusive material spectral library and a set of decision-making rules that are robust for general 

mapping in other regions and seasons, not just for use in a single scene.

Mapping Subdirectory Structure

For efficient processing, a consistent mapping subdirectory structure should be implemented, as 

illustrated in this report and in Clark and others (2003). Imaging data, spectra of materials, control 

information, and mapping results are easy to use, find, and understand later if organized in a consistent 

manner. We typically create mapping directories under project headings and label their subdirectories 

with descriptive names, such as “cuprite-try1.” The control files (Tetracorder command scripts) for that 

Tetracorder run and all initial mapping results are stored under this subdirectory tree. A new mapping 

run should be started in its own subdirectory with its control files, such as “cuprite-try2.” This way, 
23

imaging spectrometer data, material spectral libraries, and software can be separated from the modified 

mapping directories. Datacubes can be stored in large dedicated data storage areas whereas spectral 

libraries can be stored in their own subdirectories, either in a place where laboratory spectral 

investigations are stored or within their own subdirectories under the main project directory tree. 

Likewise, the Tetracorder executable and source code can be stored where other code is located, such as 

under /usr/local/bin for executables and /src/local/tetracorder4.4 for source code on UNIX/Linux®

machines or c:\tetracorder4.4\ using Windows PCs. The various files will be referenced within the 

command scripts concerning location. A suggested starting point is shown in table 1.

Imaging Spectrometer Data

Tetracorder uses one or more (as many as five) spectral libraries of materials to compare 

material spectral features against pixel spectra from imaging spectrometer data. The tutorial dataset 

supplies one spectral library, present within the libraries subdirectory, and one imaging spectrometer 

datacube, under the cubes subdirectory (table 1). The spectral libraries have been convolved to use the 

same wavelengths (sampling interval), and spectral resolution as the datacube. Each spectral library 

contains a spectrum for each reference material along with a corresponding wavelength record. 

Additional information and material descriptions (metadata) may be present within the spectral library, 

but are not required by Tetracorder (see http://speclab.cr.usgs.gov/spectral-lib.html). Spectral libraries 

are in SPECPR (USGS) format (Clark, 1993) whereas datacubes are in a subset of the JPL/NASA 

VICAR format (www-mipl.jpl.nasa.gov/external/vicar.html), or are in a subset of Exelis ENVI® format 

(www.exelisvis.com).

The datacubes can be BIL (band-interleaved-by-line) or BIP (band-interleaved-by-pixel) files in 

16 bits/pixel signed integer format for VICAR files and 16 bits/pixel signed integer, 32 bits/pixel signed 

integer, or 32 bits/pixel floating point format for ENVI® files. If both image processing systems headers 

are present within the datacube, ENVI® headers take precedence. Byte-order of the data must be in the 

format used by the present computer architecture (Intel® or IEEE®); header embedded byte-order flags 

are currently ignored within Tetracorder. 

Tetracorder limits (as currently compiled): 

Image-data size at least > 90 gigabytes (tested)

maximum cross-track pixels = 32,765

maximum spectral channels = 710

maximum scan lines = no known limits.

As setup, image-data greater than 90 gigabytes in size can be analyzed using Tetracorder 

running under 64-bit operating systems, but data arrays within the Tetracorder program can be limited in 

size by the operating system. When using the GNU gfortran compiler, customizing the number of 

spectral channels above about 1,444 (when the maximum cross track pixel is 32,765) makes a runtime 

executable less than 2 gigabytes in size. The scan line direction remains essentially unlimited. 

Increasing array sizes above these values makes the runtime executable image greater than 2 gigabytes, 

resulting in compile failure on Red Hat Enterprise Linux Server release 5.8 64-bit. It is currently (2013) 

unknown what other implementations may have this limitation.

Imaging spectrometer data must be calibrated to the same units as the reference materials in the 

spectral library for use in the Tetracorder system. For example, if the spectral library is reflectance, the 

imaging spectrometer data should be calibrated to reflectance. The Tetracorder cmd.lib.setup.t4.4a5s6 

included here uses reflectance reference spectra. If the imaging spectrometer data were not in 
24

reflectance (0 to 1.0), then thresholds will be incorrect. Care must be used when calibrating the data; 

Tetracorder utilizes fine spectral features during material identification that depend on well-calibrated 

data to maximize spectral discrimination. Lower quality data may be used, but the mapping detail will 

be degraded. Data calibration using atmospheric models (Flash, ACORN, ATREM, etc.; see Clark and 

others, 1995, 2002) will leave artifacts, such as spectral overshoots within water bands. Applying an 

atmospheric model to the calibration of data is extremely useful for a first step. To refine the calibration 

further, ground measurements of spectrally flat (homogeneous) calibration sites can be made to further 

correct the data (Clark and others, 2002).

Spectral Library Database

Tetracorder relies on matching known material spectral features to features present within image 

spectrometer data, but observed spectral features extracted from within an imaging spectrometer dataset 

also can be identified and used. Extracted spectra that are added to the material spectral library can be 

used in mapping. For example, spectra of a blue spruce tree could be extracted from an image cube, 

averaged, and added to the spectral library as a reference spectrum of blue spruce.

Presently (2013), Tetracorder utilizes spectral libraries in the USGS SPECPR format. These 

libraries can be created, examined, and modified using the USGS programs SPECPR and PRISM. The 

program SPECPR (Clark 1980, 1993) is available at http://speclab.cr.usgs.gov/software.html. PRISM 

(Kokaly 2011) is a graphics user interface (GUI) driven program that requires an Exelis IDL®

environment. PRISM runs on any machine that executes Exelis IDL® computer code 

(www.exelisvis.com) and can build a SPECPR formatted library directly or convert ENVI® spectral 

libraries into SPECPR format.

Normally, one text file (the restart file, r1) and two Tetracorder scripts (cmds.start and 

cmd.lib.setup) are used along with two material spectral libraries for the core operations. These 

filenames can be appended with custom descriptions for version control or totally renamed (the supplied 

tutorial uses cmds.start.t4.4a or cmds.start.t4.4a.single and cmd.lib.setup.t4.4a5s6 for Tetracorder 

version 4.4 setup a5). The files cmds.start and r1 are used to assign the spectral files for use, the 

mapping and output subdirectories to use, and the wavelength and scaling factor to use during the 

analysis. The file cmd.lib.setup is used to configure which algorithms, decision-making procedures, and 

material library spectra will be used. These scripts and their interactions with Tetracorder are described 

in detail in this section. Additionally, the mapping and post-processing script tetrun is available to 

further automate the analysis and is the preferred script for starting Tetracorder.

Creating/Modifying Tetracorder Script Command Files

tetsetup

This script creates and sets up the mapping directory for a Tetracorder mapping run. It creates 

the subdirectory structure, copies pertinent files into the mapping directory, and modifies several file 

scripts to run properly with the selected datasets. This setup may be performed manually, but tetsetup 

makes it faster and easier. Tetsetup is started within a command window using three command line 

arguments that are: the new mapping directory (must not presently exist), the dataset keyword to use, 

and the dataset cube. An example on windows could be:

..\tetracorder4.4.cmds.lib06\tetsetup mapping-cuprite aviris_1995 ..\..\cubes\cuprite95,
25

or on UNIX/Linux®: 

../tetracorder4.4.cmds.lib06/tetsetup mapping-cuprite aviris_1995 ../../cubes/cuprite95.

As currently written, Tetsetup must be called using the path to its parent directory in order that it 

finds all of its helper files that will be copied into the new mapping directory. The calling location can 

be anywhere on the system; however, it is usually convenient to call Tetsetup from the parent directory 

of the new (to be created) mapping directory. Importantly, the files: cmds.start.t4.4a, r1, and tetrun are 

copied into the new mapping directory where their placeholder variables are replaced with dataset 

values such as the proper deleted points list and data filenames.

tetrun

This script runs Tetracorder with additional post-processing algorithms (instead of directly 

starting Tetracorder with: “tetracorder r1”)—just enter tetrun from a command window. This script will 

start Tetracorder, execute the Tetracorder command scripts, and do post-processing via calls to 

additional Davinci scripts. Material map output files that are not already compressed within Tetracorder 

will be compressed using GZIP, several material maps will be combined into more generalized material 

maps, and quick-look versions of the mineral maps will be created. This command also will run a 

cluster analysis algorithm that generates a text file suggesting materials with common spatial 

associations.

Note that the UNIX/Linux® tetrun script preserves the coordinate system in the material map 

output files when using input data containing ENVI® headers. The windows version does not yet add the 

geometry.

For rapid visual examination of the material map results, the tetrun script generates a series of 

contrast enhanced mineral map quick-look GIF and JPEG images. These material map fit-times-depth 

images are given a gamma stretch and can be viewed in common image display programs. The GIF 

images, located within the .\group* and .\case* subdirectories, show the mapped pixels colored white 

with a black background. The JPEG images are located within separate .\results.group.* and 

.\results.case.* subdirectories and show the mapped pixels colored red overlying a gray-band image 

from the datacube. Then a side-by-side combination of the above images are located in .\results.dual* 

directories where the left side of the image is the red pixels on gray-scale results, and concatenated on 

the right side are the results on a black background (see figs. 2, 3, and 4). 

These post-processing steps require the program Davinci (see appendix 2). If the files r1 or 

cmds.start.t4.4a were renamed, their names within tetrun need to be edited to match.

r1

This text file is a SPECPR restart file and maintains the current spectral library properties for the 

Tetracorder program. It is called the “restart” file because it is used in starting and restarting the 

Tetracorder and SPECPR programs. The r1 file can be created and may be modified during use by the 

program SPECPR. Tetracorder only reads data from this file with no modification during operation. The 

r1 file may be created and edited manually using a text editor.

cmds.start.t4.4a

This command file contains user input that might change for different mapping runs with 

Tetracorder; for example, the path to the image cube file, any scale factor and offset needed to convert 
26

data values in the image cube to reflectance, and the deleted channels. This file also calls 

cmd.lib.setup.t4.4a5s6, which contains the expert system reference library setup.

The following is an example cmds.start.t4.4a file; statement explanations are enclosed in {} and 

do not appear in the command files:

CMD crt verbose=0

\#

\# TETRACORDER 4.4

\# NOTE: this is a general command file for all mapping

\#

\# However, it must be customized.

\#

\#

==[splib06]y

==[WAVEID]Y6

==[sprlb06]w

==[DIR]./

==[DELETEPTS]1t2 31t33 62 63 80t86 96 105t116 152t170 173t175 223t224 c

==[alternatelib]SMALL

==[DIRg1]group.1um/

==[DIRg2]group.2um/

==[DIRg3]group.veg/

==[DIRg4]group.ree/

==[DIRg5]group.2um-broad/

==[DIRg6]group.2.5um/

==[DIRg7]group.1.4um/

==[DIRg8]group.3um/

==[DIRg9]group.1.5um-broad/

==[DIRg10]group.ree_neod/

==[DIRg11]group.ree_samar/

==[DIRc1]case.red.edge/

==[DIRc2]case.veg.type/

==[DIRc3]case.veg/

==[DIRc4]case.veg/

==[DIRc5]case.veg/

==[DIRc6]case.ep-cal-chl/ {test case separating epidote, calcite, and chlorite}

\###############################################################

\# the following “c”s sync the restart file with the file sizes

\# then the blank line signals tetracorder to start

c

c

c

c

c

\###############################################################

history

results

[WAVEID] \# Wavelength set to use

<cmd.lib.setup.t4.4a1

c \# cube processing

cube: ../../datacubes/F100517t01p00r5_rtgc

0 -32767 0.00005 \# offset, deleted point value, scale factor

0 \# Error message toggle flag
27

10 0 \# print every 10th line with diagnostic flag= 0

e

CMD crt verbose=0

“CMD crt” sets the verbose output of Tetracorder as it parses through this command script 

(batch file) using the CMD command. Setting verbose=0 displays the maximum descriptive parsing 

output (great for details on potential run errors); verbose=2 displays the least. Parsing this short file in 

verbose mode has no effect on Tetracorder execution speed so it usually is left at the maximum verbose 

setting and not commented out (text following “\#” is a comment), as would be longer script files used 

in production efforts.

\# TETRACORDER 4.4

Lines starting with “\#” are comment lines that usually contain a brief description or note, such 

as: this file (cmd.start) is setup for running with Tetracorder version 4.4.

==[splib06]y

This line assigns the character string “y” to the variable “splib06” for use by all subsequent 

scripts within the Tetracorder system during a material mapping run.

Lines with “==[variable]value” are assignment statements with a variable name enclosed 

between [], followed by the value or character string. The line above assigns the SPECPR file 

assignment letter “y” to the variable “[splib06]”. This line is parsed and the variable set by the 

Tetracorder program. Variables can be nested. There are two different variables used in this line: the 

variable “splib06”, which is set to string “y”, and the string “y” also is a variable that was set to a 

spectral library filename in the r1 (restart) file that Tetracorder reads first upon startup.

Variables defined within this script file are used in the following script file cmd.lib.setup. The 

variables will be expanded to their values within Tetracorder and their values will be used to control 

various decisions and operations during the mapping run. Using assigned variables instead of fixed 

values allows different spectral libraries and datacubes to be analyzed without a tremendous amount of 

editing of the various command scripts. Usually, this script (cmds.start) is the only one edited during 

multiple Tetracorder runs using several flightlines of data. Using variable substitution, the other 

command (unmodified) scripts work with new data and parameters.

==[WAVEID]Y6

This line assigns the SPECPR spectral library file and wavelength record descriptor “Y6” to the 

script variable ‘WAVEID’. The SPECPR “Y” file assignment is associated with a particular spectral 

library file (using this tutorial, s06av95a), which contains a wavelength array in spectral record “6”. The 

“Y” file assignment is capitalized to notify Tetracorder that the following record number contains a 

wavelength array, rather than a data spectrum. As in the script variable discussion above, “y” is another 

variable that is assigned to s06av95a in the r1 file that Tetracorder reads upon startup.

==[DIR]./
28

The current working directory is assigned here to the present subdirectory.

==[DELETEPTS]1t2 31t33 62 63 80t86 96 105t116 152t170 173t175 223t224 c

Deleted points are spectral channels that are not to be used in processing or analysis. The 

variable “DELETPTS” is assigned the array of deleted channels, such as: “1t2 31t33 62 63 80t86 96 

105t116 152t170 173t175 223t224 c”. The letter “t” stands for to, such as 80t86 (channels 80 to 86), and 

“c” terminates deleted points input and continues program.

Note that all command lines must be less than 80 characters in length.

==[alternatelib]SMALL

The key word “SMALL” is assigned to the script variable “alternatelib”. SMALL describes the 

small wavelength set of channels, ranging from 1 to 2,171 channels. The alternative libraries SMALL, 

MEDIUM, and LARGE vary in the range of channels within each array and are explained below in the 

“cmd.lib.setup” section. Importantly, for this set of scripts, the alternative library is defined here.

==[DIRg1]group.1um/

...

==[DIRg5]group.2um-broad/

This group of lines define spectral mapping group names and assigns them to the script variables 

“[DIRg#]” that will be used in cmd.lib.setup (called in the redirection line “<cmd.lib.setup.t4.4a1” near 

the end of this script) to create mapping group subdirectories within the mapping directory. “DIRg1” 

identifies this material data entry for use during group 1 analysis. Traditionally, group.1um materials 

usually contain their most important diagnostic absorption features near 1 μm, and are grouped together 

because of similar absorption processes. Spectrally associated materials are put into groups (group.1um, 

group.2um, group.veg, etc.) so that for any given image pixel, each material in the group competes for 

the material identification within the pixel. The “best” material is selected by competition from the 

group that has spectral features in that region. Group.2um tests materials associated with absorption 

features from 2.1 to 2.4 μm. Group.veg is the vegetation mapping group; group.ree is the rare earth 

mapping group; and group.2um-broad is the 2-μm broad-feature group. Group 0 is assigned 

automatically. It is used with all other groups unless specifically set to ignore one or more groups within 

the cmd.lib.setup script using the “nogroup0” keyword.

==[DIRc1]case.red.edge/

...

==[DIRc6]case.ep-cal-chl/

These set of lines assign mapping case option names to script variables “[DIRc#]” that will be 

used to create case subdirectories within the mapping directory. Case.red.edge is a test that measures 

vegetation chlorophyll red edge variations. Case.veg.type tests various vegetation types and case.ep-calchl tests for the presence of various epidote-calcite-chlorite mineral mixtures.

\###############################################################
29

\# the following “c”s sync the restart file with the file sizes

\# then the blank line signals tetracorder to start

c

c

c

c

c

\###############################################################

This set of lines enter a set of “c”s into Tetracorder to synchronize and update the r1 (restart) 

file’s file-pointer entries with the assigned current spectral libraries maximum number of spectral 

records. Each “c” updates a particular spectral library’s letter assignment. The last line is a blank line 

that informs Tetracorder that the synchronization is complete. Note that both the Tetracorder program 

and the SPECPR program use the same r1 restart file to inform them which drive-letter is associated 

with which file-pointer entry.

history

The entry “history” assigns the history filename to history.” This file records the flow of 

commands for each material data entry used for the mapping run as they are parsed into Tetracorder. If 

there is a problem with the Tetracorder run, this file can be handy for pinpointing the problem. 

Occasionally, when trying new data with spectral responses that differ from previous datasets, a material 

will have a diagnostic absorption defined that overlaps the new deleted channel range, which varies 

based on a particular dataset. The Tetracorder run will stop at that material entry due to an undefined 

continuum end-point. The history file can be consulted to help resolve the problem. 

results

The entry “results” assigns the results filename to results.” This file describes the processing 

results of the mapping run, including the number of materials in each group, mapping run statistics, and 

the number of pixels identified for each material. It contains a useful list of findings for post-analysis of 

the mapping run.

[WAVEID]

This line expands the variable “WAVEID” here for use by Tetracorder. WAVEID is a variable 

that points to the spectrum containing the wavelength array. The assigned value from this line was set 

above in the line “==[WAVEID]Y6”, where ‘Y’ points to the assigned spectral library containing the 

wavelengths in record 6.

<cmd.lib.setup.t4.4a5s6

This line redirects data input for Tetracorder to the script “cmd.lib.setup.t4.4a1.” Once that 

input is terminated, Tetracorder input resumes at the following line below. This allows the cmd.lib.setup

script, with its extensive material description database, to be separated from this (cmds.start) file. Note 
30

that all of this scripting input can be typed manually into Tetracorder, but it would take a long time and 

is error prone.

c \# cube processing

This line sets Tetracorder via the “c” (datacube) keyword to use an image spectrometer datacube 

for material mapping. If a single spectrum was being analyzed by Tetracorder, an “s” would be entered 

at this point and a different series of command prompts would guide the user to begin the spectral 

analysis. 

cube: ../../datacubes/F100517t01p00r5_rtgc

The above line assigns the datacube file to Tetracorder.

0 -32767 0.00005 \# offset, deleted point value, scale factor

This set of numbers is assigned as the datacube offset, deleted point value, and scale factor. The 

offset is the number of bytes in the data file (from the start) occupied by the header (zero bytes in the 

above example). The deleted point or bad channel value within the example datacube is assigned the 

DN value -32,767. This is the DN pixel value that is expected in the dataset to mark the current pixel 

channel as being nonusable. The scale factor, 0.00005 in this example, scales (multiplied into) the 

integer datacube DN value to a floating point spectral range of 0.000 to 1.000. These numbers are 

dependent on the imaging spectrometer dataset used.

0

This line sets the error message flag to zero.

0

This line sets Tetracorder to print into a log file (or screen) the values calculated during analysis 

for every 10th image scanline, using a diagnostic flag set to 0.

Tetracorder now starts the mapping analysis. 

e

The last line, which must contain an e,” signals the end of data entry and exits the program. If an 

overarching script file started Tetracorder (such as the optional script file: tetrun), additional statistical 

methods and image conversion routines will be performed upon completion of Tetracorder.
31

cmds.start.t4.4a.single

This file is nearly identical to cmds.start.t4.4a, but is used for analyzing single spectra. These 

spectra can be measured using lab, field, or aircraft spectrometers and must be in SPECPR format. 

Aircraft spectra are extracted from image cube (pixel spectra) data.

cmd.lib.setup.t4.4a5s6

Cmd.lib.setup sets up the parameters for the spectral library materials chosen to test against each

pixel spectrum in the datacube. Each reference material assigned to Tetracorder has associated names 

and values for its spectral library, record number, diagnostic absorption features, mapping constraints 

and actions, output filename, and title description. “Not features” that guide special absorption feature 

handling are setup and alias variables are resolved. The material parameters within the standard 

Tetracorder command file have been empirically determined and iteratively refined through many study 

investigations.

Cmd.lib.setup is composed of three parts, a comment section that lists changes, additions, and 

usage instructions to the program with time; a setup section that assigns default values to global 

variables; and a materials knowledge base section that defines the algorithms, methods, absorption 

features, constraints, and actions used to test for each material selection.

Comment Section

The comment section gives a brief history of changes to the Tetracorder program. Major changes 

are listed with dates and short descriptions. Notes on Tetracorder’s primary functions and settings are 

mentioned here, whereas necessary file edits are highlighted where variable settings must be changed 

for new data mapping runs.

Setup Section

Discussed below are the commands and variable assignments within the setup section of 

cmd.lib.setup. They will be used within the materials knowledge base section for control of mapping 

results. Commands to Tetracorder are lines that start with a character or number or an expansion of a 

global variable, such as: [DIRg1]. Tetracorder expands the variable ‘DIRg1’ and uses its value at the 

start of the line during interpretation. Variable assignments are lines that start with “==”, such as: 

==[GLBLFITALL] 0.2 0.3. This line assigns the values “0.2” and “0.3” to the array variable 

“GLBLFITALL.” Lines (or partial lines) that contain “\#” are comments. The text following “\#” to the 

end of that line are not interpreted by Tetracorder.

Degree of Tetracorder output detail listed while running:

CMD crt verbose=2

“Verbose” sets the amount of information scrolled within the command window while 

Tetracorder is running where a higher number suppresses more output. Verbose=2 generates a low 

amount of information streaming to the screen, verbose=1 generates a moderate amount, and verbose=0 

generates the most output to the screen while Tetracorder is running.

Global fit variables:

==[GLBLFITALL]0.2 0.3
32

==[GLBLDPFIT]0.5 0.6

==[GLBLFDFIT]0.3 0.4

==[GLBLDPFITg2]0.65 0.7

The global fit variables set the default threshold of least-squares-fit “GLBLFITALL”, banddepth “GLBLDPFIT”, fit-times-depth “GLBLFDFIT”, and band-depth-for-group2 “GLBLDPFITg2”. 

When the value of fit, depth, or fit-times-depth becomes less than the threshold, the pixel value in that 

output material map image is set to zero. When two threshold values are set, a fuzzy logic ramp is used, 

instead of a hard-cut threshold. Values above the second threshold value remain unchanged. Within the 

fuzzy logic range (value 1 to value 2), values equal to the first threshold value are multiplied by 0.0, 

whereas values equal to the second threshold value are multiplied by a threshold of 1.0. Values between 

the start and ending thresholds linearly are interpolated between 0.0 and 1.0. Values below the first 

threshold value are set to 0.0. Although “GLBLDPFIT” sets the fit for most groups and cases, 

“GLBLDPFITg2” is used to set the fit threshold for group 2, which maps clays, micas, and carbonates.

Not feature variables:

==[NOTDRYVEG] [splib06] 7128 \# Dry_Long_Grass AV87-2 

W1R1Ba

==[NOTGREENVEG] [splib06] 7170 \# Fir_Tree IH91-2 

W1R1Ba

==[NOTMONTSWY] [splib06] 3270 \# Montmorillonite SWy-1 

W1R1Bb

==[NOTMONTAZ] [splib06] 3228 \# Montmorillonite SAz-1 

W1R1Bb

==[NOTMUSCOVITE1] [splib06] 3348 \# Muscovite GDS113 Ruby 

W1R1Bb

==[NOTMUSCOVITE2] [splib06] 5832 \# Muscovite CU91-250A med Al 

W2R4Nb

==[NOTNAALUNITE1] [splib06] 288 \# Alunite GDS95 Na Syn (150C) 

W2R4Na

==[NOTKALUNITE1] [splib06] 300 \# Alunite GDS97 K Syn (150C) 

W2R4Na

==[NOTKALUNITE2] [splib06] 294 \# Alunite GDS96 K Syn (250C) 

W2R4Na

==[NOTbroadFe2] [splib06] 5634 \# Chlorite+Muscovite CU93-65A 

W1R1Ba

==[NOTepidote] [splib06] 1668 \# Epidote GDS26.a 75-200um 

W1R1Bb

==[NOTgypsum] [splib06] 1986 \# Gypsum HS333.3B (Selenite) 

W1R1Ba

==[NOTjarosite] [splib06] 2568 \# Jarosite GDS99 K 200C Syn 

W1R1Ba

==[NOTCH1] [splib06] 6840 \# Plastic_PVC GDS338 White 

W1R1Fa

==[NOTDOLOMITE] [splib06] 1572 \# Dolomite HS102.3B 

W1R1Bb
33

The 15 NOT key word feature materials are defined above for use in excluding the library 

material selection if the NOT material is observed during the mapping test within the data pixel 

spectrum. The NOT feature variables (“NOTDRYVEG”, etc.) are assigned two spectrum locator values 

within these statements, which are then followed by a descriptor comment starting with “\#”. The two 

assigned values used to locate the NOT material spectrum are a SPECPR file letter (whose value is 

stored within the variable “splib06”) and spectral record number. In this case, “splib06” was assigned 

the letter “y” within the cmds.start script (i.e. ==[splib06]y). Anywhere “NOTDRYVEG” is present 

within this (cmd.lib.setup) command file, it is expanded to “y 7128”. For completeness, how 

Tetracorder handles this past this point is that SPECPR subroutines within Tetracorder translate the file 

letter into the spectral library file (using the restart control file r1) that contains the not feature material’s 

spectrum (so: y 7128, stored within the variable “NOTDRYVEG” get translated to the spectral record 

#7128 within the tutorial spectral library “/data/tetracorder4.4/libraries/s06av95a”, as seen within the 

text file r1).

Vegetation ratio variables:

==[RATIOGREENVEG] [splib06] 7260 \# Lawn_Grass GDS91 (Green) 

W1R1Ba

==[RATIOGVEG1] [splib06] 7644 \# Lawn_Grass GDS91 +const 1.0 

W1R1Ba

Green vegetation variables are assigned spectral library file and record numbers (lawn grass) for 

use in red edge vegetation studies. These two spectra are used in forming ratios with vegetation spectra 

that were shifted a set wavelength distance in the “case 1” (vegetation red edge shift) description 

section. Case 1 tests for red edge shifts within vegetation identified in the group studies.

Liboutput and Featoutput

liboutput none

featoutput none

These are variable for future use to output convolved spectral libraries and features for real time 

convolutions.

Alternative library

3 \# 3 alternate library reference spectra.

SMALL \# keyword for alternate 1: 1 to 2171 channels

MEDIUM \# keyword for alternate 2: 2172 to 4852 channels 

(future)

LARGE \# keyword for alternate 3: Future

use [alternatelib] \# use [alternatelib] for this setup

Three spectral libraries are defined but only the “SMALL” library, convolved to less than 2,172 

channels, presently is operative. The “MEDIUM” and “LARGE” libraries will be implemented in the 

future when imaging spectrometers with more spectral channels come online. The variable 

“alternatelib” is defined to SMALL within the cmds.start command script (“==[alternatelib]SMALL”).

group and case mapping selections

5 6 \# define 5 groups (0, 1, 2, 3, 4, 5) and 6 cases
34

[DIRg1] \# group 1 path

[DIRg2] \# group 2 path

[DIRg3] \# group 3 path

[DIRg4] \# group 4 path

[DIRg5] \# group 5 path

[DIRg6] \# group 6 path

[DIRg7] \# group 7 path

[DIRg8] \# group 8 path

[DIRg9] \# group 9 path

[DIRg10] \# group 10 path

[DIRg11] \# group 11 path

[DIRc1] \# case 1 path

[DIRc2] \# case 2 path

[DIRc3] \# case 3 path

[DIRc4] \# case 4 path

[DIRc5] \# case 5 path

[DIRc6] \# case 6 path

nogroup0: 3 10 11 \# groups not to include group0

\#

\# Group definitions:

\#

\# Group 0: used with all other groups

\# Group 1: electronic absorptions ~ultraviolet (UV) to ~1 micron

\# Group 2: vibrational features, typically 2–2.5 micron region

\# group 3: Vegetation and trace vegetation mapping

\# group 4: the search for rare-earth oxides

\# group 5: broad absorptions in the 2-micron region

\# group 6: 2.5-micron region

\# group 7: 1.4-micron region

\# group 8: 3-micron region

\# group 9: broad absorptions in the 1.5-micron region
35

\# group 10: rare earth elements (REE) Neodymium

\# group 11: REE Samarium

\# group 12: REE future

\# group 13: REE future

\# group 14: REE future

\# group 15: REE future

\#

BEGIN SETUP

Groups are an association of materials with similar spectral features that are used to compete 

against each other, with their results being stored in the group subdirectory. Cases test the mapping 

results within a group for special conditions and store their results into their case subdirectory. These 

groups and cases are set within the materials knowledge base section. 

Group and case mapping type associations are assigned by variable expansion into Tetracorder 

here. Comments starting with “\#” follow the global variables describing their functions. The global 

variables are set within the command file cmds.start. Library materials within each of these material 

associations (group or case) will compete for identification and material maps of the identified materials 

will be written into the named subdirectories. See Clark and others (2003) for more details. 

All groups are tested independently from each other and their test findings are unrelated, except 

for their special association with group 0. This allows multiple materials to be identified independently 

using discrete spectral features within the same observed (pixel) spectrum. Materials within group 0 

(vegetation, snow, and water) automatically are included with materials in each other group during that 

group’s testing, so that materials in both groups compete for identification, allowing group 0 materials 

to spectrally dominate the output findings, such as when lush green vegetation covers much of the pixel. 

This is the proper finding in most situations; however, if this mapping competition of group 0 materials 

with another group is not desired, it can be turned off using the “nogroup0” command as seen above. 

The line that directs groups 3, 10, and 11 will not have mapping competition with group 0.

Knowledge Base Section

The materials knowledge base section, the last section of “cmd.lib.setup”, defines the 

algorithms, methods, material (absorption) features, threshold and constraints, and actions used to map 

each material. This section of “cmd.lib.setup” usually is not modified while in production mode, but 

will need to be edited for new research. New material definitions will be added here and current material 

definitions will be modified here when new studies begin. Absorption feature end-points will require 

testing and possible custom modification when new imaging spectrometer data are used for the first 

time. This section requires quality assessment after any modifications. See also Clark and others (2003).

Material example:

\#####################################################################

group 2
36

udata: reflectance

convolve: no

preratio: none

preprocess: none

algorithm: tricorder-primary

SMALL: [splib06] 5826 d \# file ID, rec no. 1 to 2171 channels

MEDIUM: [splib06] xxxx d \# file ID, rec no. 2172 to 4852 channels

LARGE: [splib06] xxxx d \# file ID, rec no. larger_chans_future

\#=-=-=-=-=-=-=-=-=-=-=- TITLE=Kaol+Musc_intimate CU93-5C W1R1Ba

[DELETPTS]

Kaol + Musc intimate CU93-5C \# output title

 2 1 \# Number of features

Dw 2.105 2.138 2.253 2.287 ct .04 r*bd> 0.002 0.004

Ww 2.265 2.295 2.385 2.405 ct .04

\# 2.35 feature changed to WEAK 1/19/00 BWR

NOT [NOTKALUNITE2] 2 0.2r1 0.5 \# NOT Alunite, RNC 5/01

\#NOT [NOTKALUNITE2] 2 0.03a 0.7 \# NOT Alunite, feature 2, depth .49, fit .7 BWR

\#NOT [NOTKALUNITE2] 2 0.03a 0.3 \# NOT Alunite, depth .03, fit .3

\# NOT feature at wavelength 1.481 for:Syn. K-Alunite (250C) GDS96

\# Notes:

\# Feat: 1 has a weight of 

\# Feat: 2 has a weight of

constraint: FD-FIT>[GLBLFDFIT] DEPTH-FIT>[GLBLDPFITg2]

constraint: FITALL>[GLBLFITALL]

constraint: DEPTHALL> 0.04 0.06 \# added 3.7a1 - rnc

endconstraint

output=fit depth fd

kaolin+musc.intimat \# Output base file name

8 DN 255 = 0.5000

compress= zip

action: sound1

action: none

endaction

\#####################################################################

The material definition above describes a spectrum of an intimate mixture of kaolinitemuscovite. The groups, algorithms, settings, and processing are specific to this mineral entry in this 

spectral library, but may be set for use with totally new materials and procedures of mapping analysis.

group and case(as used by this spectral library)

group 0 (vegetation/water; used with all other groups)

group 1 (electronic absorptions; UV to about 1 micron)

group 2 (vibrational features; typically 2–2.5 micron region)

group 3 (vegetation and trace vegetation mapping)

group 4 (search for rare-earth oxide minerals)

group 5 (broad absorptions in the 2-micron region)

group 6 (2.5-micron region)

group 7 (1.4-micron region)

group 8 (3-micron region)

group 9 (broad absorptions in the 1.5-micron region)

group 10 REE Neodymium
37

group 11 REE Samarium

case 1 (vegetation red edge shift)

case 2 (Comparison of vegetation spectral types)

case 3 (1-micron water in vegetation strength)

case 4 (1.2-micron water in vegetation strength)

case 5 (1.5-micron water in vegetation strength)

case 6 (epidote-chlorite-calcite mixture series)

Only groups 0 through 5, 10, and 11, and cases 1 through 6 are defined and used with the present 

tutorial dataset, though the other groups are used on planets and moons within the solar system. 

Absorptions within the Earth’s atmosphere block the frequencies of light used for analysis by group 6-9 

from reaching the Earth’s surface. Traditionally, group 1 materials usually contain their most important 

diagnostic absorption features in the visible to about 1 μm wavelength range, and are grouped together 

because of similar absorption processes (e.g., electronic absorptions). Spectrally associated materials are 

assembled into groups (group 1, group 2, group 3, etc.) so that for any given image pixel, each material 

in any one group competes for the material identification with other entries in that group. The “best 

spectrally matching” material is selected from each group for that pixel’s spectrum.

udata: reflectance

“Udata” defines the type of data used in the analysis that is tested against the spectral library. 

Options are: “raw,” “radiance,” “reflectance,” and “emittance.” “Reflectance” and “emittance” data 

types currently are being used within Tetracorder, but the “raw” and “radiance” options are not 

implemented yet. In the future, one could analyze mixed radiance and reflectance data during the same 

Tetracorder run. This will require image cubes for all data types being used.

convolve: no (no effect yet)

convolve: gaussian wav= FILE-ID REC# res= FILE-ID REC#

No convolution is performed on the data yet. This command is a place holder for future 

processing enhancement where real time convolution to the sensor spectral characteristics could be 

performed. Future options to be implemented are: “no” and “gaussian wav= FILE-ID REC# res= FILEID REC#.”

Preratio & Preprocess options

preratio: none 

preratio: URATIO FILE-ID REC#

preratio: RRATIO FILE-ID REC#

URATIO = ratio to the unknown (for example, the spectrum from a pixel in an image cube). 

RRATIO = ratio to the reference library spectrum. Currently, only RRATIO is used in the 

cmd.lib.setup.t4.4a1 command file for the vegetation red edge shift in case 1.

preprocess: none 

preprocess: algorithm case # (not allowed yet)
38

Preprocessing currently is not used in the cmd.lib.setup.t4.4a1 command file, but is a 

placeholder for future applications. This option is not fully implemented yet, so use: “preprocess: none”. 

A future implementation may include curved-continuum removal with this step.

Algorithms

algorithm: tricorder-primary (shape-matching weighted goodness-of-fit)

algorithm: nvres (veg red edge position)

Algorithm options set the processing algorithm Tetracorder uses for data analysis. The 

“tricorder-primary” algorithm, which uses a modified least-squares-fit routine from Clark and others 

(2003), normally is used (Note that tricorder was the program Tetracorder’s original name). Options are: 

“tricorder-primary” (shape-matching weighted goodness-of-fit) and “nvres” (vegetation red edge 

position). Clark and others (2003) has a comprehensive description of the parameters behind the two 

algorithms with examples.

Material Spectrum

SMALL: [splib06] 5826 d

MEDIUM: [splib06] xxxx d

LARGE: [splib06] xxxx d

[DELETPTS]

The next lines in the material description (SMALL, MEDIUM, and LARGE) assign the 

spectrum library and record number, as well as the defined deleted points. The channel spaces are: 

SMALL (1 to 2,171 channels), MEDIUM (2,172 to 4,852 channels), and LARGE (undefined, for future 

use). Only the library to be used as defined by the Alternative Library directive above is required to 

have valid parameters. Such is the case here; the SMALL spectral library will be used so that its 

spectrum record number (record 5826 in the SPECPR-format spectral library) is set whereas the other 

two alternate libraries are undefined in this example. Deleted points (spectral channels) are assigned 

using the “d” option at the end of the alternate library assignment. When using the “d” option, the 

following (noncomment) line will contain a list of spectral channels, terminated with a (continue 

command) “c”, that set which bands are not to be used by the processing.

The variable “[splib06]” will be expanded to the assigned spectral library above ([splib06] 

references the SPECPR variable “y” assigned in cmds.start, which references “../libraries/s06av95a” 

assigned to “y” (iyfl) in the r1 restart file).

The deleted points variable [DELETPTS] will be expanded to “1t2 31t33 62 63 80t86 96 

105t116 152t170 173t175 223t224 c.” Channel numbers can be listed singly and as intervals using the 

(to) “t” flag. The deleted points line must be terminated with the (continue) “c” flag. Note that the list of 

deleted channels must be less than 80 characters.

For most entries that use the “tricorder-primary” algorithm, the following lines are expected in 

sequence and do not have keywords.

The next line is the output title embedded in the image vicar header.

 2 1 \# Number of Features, Number of NOT features

The above line declares the number of regular spectral features and the number of “not” features.
39

Material features

Materials are mapped using selected features. Each feature of the material can be analyzed using 

a descriptor line that contains three parts. This text line starts with specifying the importance of the 

feature—either diagnostic (D), optional (O), or weak (W). Then the continuum interval is defined, with 

pairs of starting and ending channels for the left and right continua end-points. By using pairs of 

channels to compensate for noisy data, the accuracy of spectral shape matching can increase as much as 

30 percent (Swayze and others, 2003). Finally, the descriptor-line contains optional settings that set 

thresholds that, if exceeded, reject the answer.

Continuum interval with feature

D = diagnostic feature (must be present)

O = optionally present feature

W = weak feature

D: Diagnostic features must be present in the pixel spectrum (observed spectrum). The 

absorption area for each diagnostic feature (using the library spectrum) is used to weight the feature’s fit 

value.

O: Optional features can be present in the pixel spectrum (observed spectrum). The 

absorption area for each optional feature (using the library spectrum) is used to weight the feature’s fit 

value (whether the feature exists in the pixel data or not).

W: Weak features must be present in the pixel spectrum (observed spectrum). The 

absorption area for each weak feature (using the library spectrum) is not used to weight the feature’s fit 

value.

Following start and ending continuum channel pairs

Left continuum channel1, left continuum channel 2

Right continuum channel 1, right continuum channel 2

Following options

ct value optional-value , \# continuum threshold

lct value optional-value , \# left continuum threshold

rct value optional-value , \# right continuum threshold

lct/rct> value optional-value , \# left continuum-right continuum ratio

rct/lct> value optional-value , \# right continuum-left continuum ratio

for the shoulderness arguments below:

lc=left continuum end-point

rc=right continuum end-point

bb=band bottom

and

lcbbrc = (lc-bb)/(rc-bb), bb= band bottom

rcbblc = (rc-bb)/(lc-bb), bb= band bottom
40

rcbblc, lcbbrc=left continuum, band bottom, right continuum shape

rcbblc> value optional-value \# right shoulderness > this value

rcbblc< value optional-value \# right shoulderness < this value

lcbbrc> value optional-value \# left shoulderness > this value

lcbbrc< value optional-value \# left shoulderness < this value

r*bd> value optional-value , \# reflectance times band-depth

 (NOTE: absolute band-depth for positive features)

 (values and optional values are positive real numbers)

If a single value is used, the value is a hard threshold. If two values are used, it is a fuzzy logic 

threshold.

(material example: Pyrophyl+Muscovite JH_PYRM1 W1R1Fb)

Dw 2.080 2.113 2.241 2.271 ct .04 r*bd> 0.002 0.006

NOT [NOTKALUNITE2] 2 0.2r1 0.3 \# NOT Alunite feature 2

The material example of a mixture of the minerals pyrophyllite and muscovite (id: JH_PYRM1) 

has a diagnostic wavelength feature with a continuum interval from 2.080 to 2.271 μm. The diagnostic 

“D” flag requires the feature to be present in the observed (pixel) spectrum otherwise this material will 

be rejected in the identification process. The area of this feature will be used for multiple-fit weighting. 

The other feature types are “O” (optional), which may be present and if used, the area of the feature will 

be used for multiple-fit weighting; and “W” (weak), which will be used if present, but not factored in for 

multiple-fit weighting.

The flag “w” specifies that a continuum wavelength interval will follow (one can also specify a 

“c” for channel number). The observed (pixel) continuum feature “ct” threshold must be at least 4-

percent reflectance (0.04) and the reflectance times band depth (r*bd) must be greater than a fuzzy logic 

threshold interval between 0.2 to 0.6 percent (0.002 and 0.006).

NOT features disallow the current material from being identified using the current observed 

(pixel) spectrum when the that material’s spectral feature exceeds the assigned limits. The spectrum and 

threshold parameters of the material are assigned, following the “NOT” keyword. In the present 

example, the spectral feature designated feature 2 in the mineral “Alunite GDS96 K Syn (250C)” must 

not be present in the pixel spectrum at a relative depth intensity greater than 0.20 (20 percent) and 

greater than a fit of 0.3. NOT associations can use either relative or absolute spectral feature thresholds. 

Relative depth intensities use the key letter “r” and associate the band-depth of the NOT feature (feature 

1 in the above case, thus the r1 designation) with the same band-depth feature of the observed (pixel) 

spectrum. Absolute depth intensities use the key letter “a” and use the absolute band-depth of the 

indicated “not” feature. The NOT material was expanded from the [NOTALUNITE2] variable defined 

near the beginning of this file (cmd.lib.setup) where its spectral library and record number were set. See 

Clark and others (2003) for a full discussion of “NOT Features.” If these NOT conditions are met 

within the pixel spectrum, this material will not be mapped for this pixel.
41

Shoulderness options (fig. 7) can be used to constrain a material identification as well. See Clark 

and others (2010) for a full discussion of “Shoulderness.” The advantage of shoulderness is that it holds 

to a high degree over a large range of abundances in mixtures, whereas slope and level do not.

Figure 7. Definition of shoulderness from Clark and others (2010).

Constraints

Constraints place thresholds on fit, depth, fit-times-depth, and temperature values used for 

material identification. When values are below the threshold limit, the pixel value for the selected type 

of material map is set to zero. Feature-ratios (fratio), pressure, and class values are definable, but 

presently not used. The temperature constraint is used primarily with water and snow, or other volatiles 

when mapping throughout the Solar System. All constraints may use global variables and fuzzy logic 

when appropriate. The global variables for fit (“GLBLFITALL”), depth (“GLBLDPFIT”), fit-timesdepth (“GLBLFDFIT”), and depth for group 2 (“GLBLDPFITg2”) are set in the previous section of 

“cmd.lib.setup”.

Constraint types, followed by their threshold values and operative images are listed below. 

When the constraint threshold for the reference material is greater than or equal to the Tetracorder 

calculated value for the unknown (for example, a spectrum from an image cube), the material map’s 

pixel DN is set to 0.0 for the defined image type. When the fit value is set to zero, the material is 

removed from competition for material identification. For example, when defined, if the FITALL value 

is greater than or equal to the calculated fit value of the unknown (the image cube spectrum), the pixel 

DNs for the fit, depth, and fit-times-depth mineral map images are set to 0.0. If the FD-DEPTH value is 

greater than or equal to the calculated depth value, the pixel DN for the fit-times-depth mineral map 

image is set to 0.0.

fit-threshold constraints

FITALL> value optional-value , applies to all three output images

FIT> value optional-value , applies to fit images
42

DEPTH-FIT> value optional-value , applies to depth images

FD-FIT> value optional-value , applies to fit-times-depth images

depth-threshold constraints

DEPTHALL> value optional-value , applies to all three output images

DEPTH> value optional-value , applies to depth images

FD-DEPTH> value optional-value , applies to fit-times-depth images

fit-times-depth-threshold constraints

FDALL> value optional-value , applies to all three output images

FD> value optional-value , applies to fit-times-depth images

temperature constraint

temperature t1 t2 t3 t4 \# in centigrade (future; not currently used)

If a single value is used, the value is a hard threshold. If two values are used, it is a fuzzy logic 

threshold.

(example- Pyrophyl+Muscovite JH_PYRM1 W1R1Fb)

constraint: FD-FIT>[GLBLFDFIT] DEPTH-FIT>[GLBLDPFITg2]

constraint: FITALL>[GLBLFITALL]

constraint: DEPTHALL> 0.06 0.11

endconstraint

Output

output=fit depth fd

The output line defines the type of analysis output. Options are: “fit,” “depth,” “fd,” and “none.” 

Material map images that contain least-square-fit values are generated using the ”fit” option. Material 

map band-depth images are generated with the “depth “ option and material map fit-times-depth images 

are generated by multiplying the weighted feature strengths times each “fit” by ”depth” for each pixel. 

When a material needs to compete in the test suite, but where no file output is desired if it wins, use the 

“none” setting.

kaolin+musc.intimat \# Output base file name

This line assigns the identified material output file’s base name. When “fit,” “depth,” or “fd” 

files are selected for output, their type is appended to the base name. For example, a standard “fit” 

output image for a given material in the Tetracorder command file would be named: basename.fit. 

Likewise, the other two files would be named: basename.depth and basename.fd.

8 DN 255 = 0.5000

This line sets the bit size and scaling of material output images. Bits per pixel may be set to 8 or 

16. Eight-bit pixels have a DN range of 0 to 255. No negative values are allowed. Sixteen-bit pixels 
43

have a DN range of -32,768 to 32,767, though material maps (images) are limited to the range of 0 to 

32,767.

Material map DN values are scaled using the argument following the DN. In the case of “8 DN 

255 = 0.5000”, the depth or fit*depth values (which range from 0.0 to 1.0) will be scaled into an integer 

DN range of 0 to 255, with the values between 0.0 and 0.5 being linearly interpolated to DNs between 0 

and 255, and values greater than 0.5 will be set to a DN of 255. In the case of “8 DN 255 = 1.0000”, the 

depth or fit*depth values between 0.0 and 1.0 will be scaled linearly to DNs between 0 and 255.

compress= zip

The output image is set to be compressed using GZIP.

Actions

action: sound1 \# verbally tell the answer in single-spectrum mode

action: case 1 2 3 4 5

action: none

endaction

If the target material is mapped for the tested pixel, actions guide the further program response. 

A sound bite can be played or further processing in case studies can be performed (note sound is 

hardware dependent). Cases can call additional cases so there is no fundamental limit to the number of 

algorithms that may be applied to an analysis (but limits are set at compile time).

Tetracorder Runtime Debugging

Tetracorder runtime debugging can be complex, but the source of the run failure generally 

relates to a simple error. Errors can be caused by a variety of mistakes, but the two most common are 

improper file assignments or read/write permissions, and deleted wavelength channels that are needed 

for a particular reference spectral library entry. Tetracorder loads each material entry sequentially and 

will stop at the entry where a problem occurs. The history (and optional cmds1.out) file(s) will list the 

parsed entries and will terminate at or, depending on buffered content, close to the entry with the 

problem. Once these errors are located, the corresponding script file may be corrected (edited). Once a 

mapping run has been halted by an error, the history and the optional output tetrun.out files need 

examined, and before a new run is started, they need to be deleted or renamed. Tetracorder will not 

overwrite these files and will halt again, even if the original problem has been solved. Note: Errors 

usually occur because of a recent change in the analysis setup. If a script file has been executed 

successfully previously, it is less likely to be the cause of the problem, unless it is interacting with 

recent changes. 

Other errors include: exceeding image array size limits (32 and 64 bit), improper data scaling or 

date type (image or material data), or improperly formatted command files. The most important resource 

for analyzing and correcting setup problems is the runtime log files: history, results, and if used, the 

optional tetrun.out. The last part of the log files may not have been flushed from memory until the 

Tetracorder program is terminated (when tetracorder halts due to an error, type “e” and a carriage return, 

then “x” and a carriage return repeatedly until the program exits, even if you do not see any screen 

prompts because the operation may buffer these and not show them).
44

Optional tetracorder.out and tetrun.out

If the tetracorder run is started by tetrun, tetrun redirects tetracorder output to the file 

tetracorder.out. We recommend starting tetrun with the command:

tetrun > tetrun.out

then if a problem is encountered, the tetrun.out and tetracorder.out files can be examined. Due to 

buffering, usually when an error is encountered, you may see a message “tetrun stopped” (depending on 

the operating system). When tetracorder encounters an error, redirection from the cmd files stops and 

input is returned to the keyboard. You do not see this message because output is being redirected to a 

tetracoder.out file. The solution is to type a few “e” and “x” letters with a carriage return after each 

letter. This will tell tetracorder to exit.

Hint: if you have trouble locating the Tetracorder run error, edit the cmds.start and cmd.lib.setup 

files and comment out the line: cmdverbose=0 by placing \# at the beginning of that line. That change 

will enable full diagnostic output during a run.

Image Output Files

Material map output occurs as a series of images written to separate group subdirectories. Each 

mapping group has a subdirectory. Within these subdirectories, map output files are stored, three files 

per identified material. The three files for each material are the fit, depth, and fit-times-depth images. 

Each material image may be displayed using a variety of image display software (ENVI®, PW, 

HyperCube, etc.). Each file forms a gray scale image, where the intensity of the value is displayed as a 

brightness level. These DN levels can be scaled before Tetracorder analysis in the setup script files. 

Internal VICAR and external ENVI® headers describe the mapping image size, data type, organization, 

and other parameters. Most mapping output files have been compressed using GZIP that ENVI® and 

PW decode automatically. These files must be uncompressed before using HyperCube. Additional 

material map output files can be generated after Tetracorder execution by script analysis of the initial 

output. This includes spatial, statistical, and classification output.

References

Clark, R.N., 1980, A large scale interactive one dimensional array processing system: Publications of 

the Astronomical Society of the Pacific, v. 92, p. 221–224.

Clark, R.N., 1993, SPECtrum processing routines user's manual version 3 (program SPECPR): U.S. 

Geological Survey Open-File Report 93–595, 228 p.

Clark, R.N., and Roush, T.L., 1984, Reflectance spectroscopy—Quantitative analysis techniques for 

remote sensing applications: Journal of Geophysical Research, v. 89, p. 6329‒6340.

Clark, R.N., Swayze, G.A., Heidebrecht, K., Green, R.O., and Goetz, A.F.H., 1995, Calibration to 

surface reflectance of terrestrial imaging spectrometry data—Comparison of methods: Summaries of 

the Fifth Annual JPL Airborne Earth Science Workshop, JPL Publication 95-1, vol. 1, 

January 23‒-26, p. 41‒42.

Clark, R.N., 1999, Spectroscopy of rocks and minerals and principles of spectroscopy, chap. 1 of Rencz, 

A.N., ed., Manual of remote sensing: New York, Wiley, p. 3‒58.

Clark, R.N., Green, R.O, Swayze, G.A., Meeker, G., Sutley, S., Hoefen, T.M., Livo, K.E., Plumlee, G., 

Pavri, B., Sarture, C., Wilson, S., Hageman, P., Lamothe, P., Vance, J.S., Boardman, J., Brownfield, 
45

I., Gent, C., Morath, L.C., Taggart, J., Theodorakos, P.M., and Adams, M., 2001, Environmental 

studies of the World Trade Center area after the September 11, 2001 attack. U. S. Geological Survey 

Open-File Report 01–0429, 260 p., accessed 12/12/13, at http://pubs.usgs.gov/of/2001/ofr-01-0429/.

Clark, R., Swayze, G., Livo, E., Kokaly, R., King, T.V.V., Dalton, B., Vance, S., Rockwell, B., Hoefen, 

T., and McDougal, R., 2002, Surface reflectance calibration of terrestrial imaging spectroscopy 

data—A tutorial using AVIRIS, in Green, R.O., ed., Proceedings of the 11th JPL Airborne Earth 

Science Workshop: JPL Publication 03-4, p. 43-63. (Also available at 

ftp://popo.jpl.nasa.gov/pub/docs/workshops/02_docs/2002_Clark_web.pdf)

Clark, R.N., Swayze, G.A., Livo, K.E., Kokaly, R.F., Sutley, S.J., Dalton, J.B., McDougal, R.R., and 

Gent, C.A. 2003, Imaging spectroscopy—Earth and planetary remote sensing with the USGS 

Tetracorder and expert systems: Journal of Geophysical Research, v. 108 no. E12, 5131, p. 5-1‒5-44, 

(Also available at http://dx.doi.org/10.1029/2002JE001847.), accessed 12/12/13, at 

http://speclab.cr.usgs.gov/PAPERS/tetracorder.

Clark, R.N., Swayze, G.A., Hoefen, T.M., Green, R.O., Livo, K.E., Meeker, G., Sutley, S., Plumlee, G., 

Pavri, B., Sarture, C., Boardman, J., Brownfield, I., and Morath, L.C., 2006, Environmental mapping 

of the World Trade Center area with imaging spectroscopy after the September 11, 2001 attack, chap. 

4 of Gaffney, Jeff, and Marley, N.A., eds., Urban aerosols and their impacts-Lessons learned from the 

World Trade Center tragedy: Oxford University Press, American Chemical Society, Symposium 

Series 919, p. 66‒83, plates 4.1‒4.6.

Clark, R.N., Swayze, G.A., Wise, R., Livo, E., Hoefen, T., Kokaly, R., and Sutley, S.J., 2007, USGS 

digital spectral library splib06a: U.S. Geological Survey Data Series 231, [variously paged], accessed 

12/12/13, at http://speclab.cr.usgs.gov/spectral-lib.html.

Clark, R.N., 2009, Detection of adsorbed water and hydroxyl on the Moon. Science 23 October 2009, 

v. 326, no. 5952, p. 562‒564.

Clark, R.N., Swayze, G.A., Leifer, I., Livo, K.E., Kokaly, R., Hoefen, T., Lundeen, S., Eastwood, M., 

Green, R.O., Pearson, N., Sarture, C., McCubbin, I., Roberts, D., Bradley, E., Steele, D., Ryan, T., 

Dominguez, R., and the Air borne Visible/Infrared Imaging Spectrometer (AVIRIS) Team, 2010, A 

method for quantitative mapping of thick oil spills using imaging spectroscopy: U.S. Geological 

Survey Open-File Report 2010–1167, 51 p., accessed 12/12/13, at http://pubs.usgs.gov/of/2010/1167/

Clark, R.N., Cruikshank, D.P., Jaumann, R., Brown, R.H., Curchin, J.M., Hoefen, T.M., Stephan, K., 

Dalle Ore, C.M., Buratti, B.J., Filacchione, G., Baines, K.H., and Nicholson, P.D., 2012, The 

composition of Iapetus—Mapping results from Cassini VIMS: Icarus, v. 218, p. 831–860.

Karnieli, A., Kokaly, R.F., West, N, and Clark, R.N., 2001, Remote sensing of biological soil crusts, 

chap. 31 of Belnap, J., and Lange, O.L., eds., Biological soil crusts—Structure, function, and 

managements: Berlin, Springer-Verlag, Ecological Studies, v. 150, p. 431–455.

King, T.V.V., Clark, R.N., and Swayze, G.A., 2000, Applications of imaging spectroscopy data—A 

case study at Summitville Colorado, in Kuehn, F., King, T., Hoerig, B., and Pieters, D., eds., Remote 

sensing for site characterization: Berlin, Springer-Verlag, p 164–185.

Kokaly, R.F., Despain, D.G., Clark, R.N., and Livo, K.E., 2003, Mapping the biology of Yellowstone 

National Park using imaging spectroscopy: Remote Sensing of Environment, v. 84, p. 437–456.

Kokaly, R.F., Despain, D.G., Clark, R.N., and Livo, K.E., 2007, Spectral analysis of absorption features 

for mapping vegetation cover and microbial communities in Yellowstone National Park using 

AVIRIS data, chap. N of Morgan, L.A., ed., Integrated geoscience studies in the greater Yellowstone 

Area—Volcanic, tectonic, and hydrothermal processes in the Yellowstone geoecosystem: U.S. 

Geological Survey Professional Paper 1717, p. 463-489. (Also available at 

http://pubs.usgs.gov/pp/1717/downloads/pdf/p1717N.pdf)
46

Kokaly, R.F., 2011, PRISM—Processing routines in IDL for spectroscopic measurements (installation 

manual and user's guide, version 1.0): U.S. Geological Survey Open-File Report 2011–1155, 432 p. 

(Also available at http://pubs.usgs.gov/of/2011/1155/.)

Swayze, G.A., Clark, R.N., Goetz, A.F.H., Chrien, T.G., and Gorelick, N.S., 2003, Effects of 

spectrometer bandpass, sampling, and signal-to-noise ratio on spectral identification using the 

Tetracorder algorithm: Journal of Geophysical Research, v. 108, no. E9, 5105, 30 p. (Also available at 

http://dx.doi.org/10.1029/2002JE001975.)

Swayze, G.A., Kokaly, R.F., Higgins, C.T., Clinkenbeard, J.P., Clark, R.N., Lowers, H.A., and Sutley, 

S.J., 2009, Mapping potentially asbestos-bearing rocks using imaging spectroscopy: Geology, v. 37, 

no. 8, p. 763–766.

Speclab - USGS Spectroscopy Laboratory website. http://speclab.cr.usgs.gov/software.html.

Appendixes

Appendix 1—Tetracorder Description and Getting Help

Appendix 1 describes the basic functioning and system requirements for Tetracorder and how to 

get help.

About Tetracorder

Tetracorder is supplied as an executable program for 32-bit Windows®-XP and later systems, 

and is supplied as source code that must be compiled for all other operating systems. Appendix 2 

describes the installation of Tetracorder and where to download source code and compilation 

instructions.

Tetracorder runs on 32-bit Windows®-XP, 32- and 64-bit Windows®-7 systems, 32- and 64-bit 

Linux, and UNIX® computers. Imaging spectrometer data files are limited to 2 gigabytes in size per run 

using 32-bit compilers and machines. Using 64-bit machines, dataset size is limited only by compiler 

and operating system constraints that are much greater than 4GB. Image-cubes larger than 90 gigabytes 

have been analyzed on 64-bit Ubuntu and Red-Hat® Linux workstations with the program compiled 

using the 64-bit GNU gcc with the GFORTRAN compiler. Tetracorder’s speed performance may be 

limited by available RAM, cpu speed, and disc I/O speed. To process an image cube of tens to hundreds 

of gigabytes, Tetracorder needs less than 2 gigabytes of computer RAM. The supplied Windows®-7 64-

bit compiled executable program does not have a 4-gigabyte data limit, whereas the supplied 

Windows®-XP 32-bit version has a 2 gigabyte limit. The supplied source code is used for both 32-bit 

and 64-bit versions.

It is worth noting that for 32-bit computer systems, imaging spectrometer data files larger than 2 

gigabytes may be broken into segments smaller than 2 gigabytes then run through (32-bit) Tetracorder. 

The segmented output material maps can then be recombined. Tetracorder operates only on individual 

pixel spectra and does not use spatial relationships between adjacent pixels in the identification process.

Getting Help

Software and extensive spectroscopy information (including spectral libraries) are available from 

the USGS Web site http://speclab.cr.usgs.gov. Example AVIRIS imaging spectrometer datasets are 
47

available from the JPL/NASA Web site http://aviris.jpl.nasa.gov under the “Data” tab, then “Free Data” 

bullet.

Appendix 2—Tetracorder Installation Procedures

Appendix 2 describes the installation procedures for Windows®, Linux, and UNIX® machines.

Tetracorder Download and Installation

The Tetracorder Download Directory can be found on the following Web site: 

html://speclab.cr.usgs.gov/software.html

Check the instructions in the AAA.README.txt files in each download directory for latest 

instructions. The instructions below only are current as of the time of this writing (2013).

Several packages are available to download: the abbreviated tutorial package and several 

full featured packages.

tetracorder4.4-tutorial.zip (full Tetracorder tutorial package for MS-Windows®)

Tetracorder4.4-tutorial.zip contains the directories listed below.

bin-pc (MS-Windows® executable programs)

cubes (imaging spectroscopy datasets)

docs (Tetracorder documentation)

speclib (material spectral libraries)

src-local (Tetracorder source code)

tetracorder4.4.cmds.lib06 (Tetracorder mapping directory setup programs)

usr.local.bin_tetracorder_support (UNIX/Linux® executable programs)

Tetracorder4.4-tutorial.zip contains an abbreviated subset of all the above packages. It contains 

all files necessary to run Tetracorder, including all program files, a small imaging spectrometer datacube 

and associated material spectral library, all source code, and documentation. Under MS-Windows®, 

unzip it anywhere on the file system and it is ready to run. Under UNIX/Linux®, the program files need 

to be setup as described below (or in the README files in the download directory).

The Tetracorder software system may be later enhanced for use with a variety of data by further 

downloading additional material spectral-libraries (speclib), and datacubes (cubes).

Under UNIX/Linux® and for a large project structure under MS-Windows®, the downloaded 

packages are placed in fixed positions within the computer’s file system. Uncompress the packages 

within their parent directories listed below (uncompress the download files with GZIP (for .gzip files) or 

a zip program (for zip files) and follow the instructions in the AAA.READ.txt files.

Note: the programs Tetracorder and SPECPR are supplied as executable programs for 

Microsoft Windows, located in the download package: bin-pc, and as source code for UNIX/Linux® 

operating systems in the download package: src-local. UNIX/Linux® compilation of Tetracorder 
48

requires SPECPR to be compiled first as many subroutines from SPECPR are used in Tetracorder. See 

html://speclab.cr.usgs.gov/software.html.

File Structure: UNIX/Linux® and Large MS-Windows® Projects

bin-pc: any directory within the system path for MS-Windows® computers (bin-pc is not used 

by UNIX/Linux® machines). It is suggested that c:\usr\local\bin-pc be used, elsewise edit the top of the 

tetsetup.bat file to set its variable assignment “set binpc=” to the selected directory. The parent directory 

would be: c:\usr\local\. This directory contains MS-Windows® executable programs and scripts.

cubes: any directory within the system. It is suggested that datacubes for a project be stored 

together or close to each other, such as in a directory: /data/project_name/cubes/ (parent directory is: 

/data/project_name/). The filename and path will be used as an argument in the tetsetup command.

docs: any directory within the system. It is suggested that the Tetracorder documents directory 

be located near the Tetracorder mapping directory setup programs, such as /info/tetracorder/docs/ 

(parent directory is: /info/tetracorder/).

speclib: place the package in /speclib/ under the root directory (parent directory is: /). 

This directory contains the material spectral libraries. On UNIX/Linux® machines, it could be placed 

anywhere and a symbolic link /speclib added to point to the directory's location.

src-local: place the package in /src/local/(tetracorder & SPECPR)/ (parent directory is: 

/src/local/). This is the source code for the programs Tetracorder and SPECPR.

tetracorder4.4.cmds.lib06: place the package in 

/info/tetracorder/tetracorder4.4.cmds.lib06/ (parent directory is: / info/tetracorder/). This contains the 

setup program and accessory scripts and files that create, copy and edit directories and files into a new 

mapping directory structure.

usr.local.bin_tetracorder_support: place programs in this directory into /usr/local/bin/. 

This directory contains UNIX/Linux® executable programs and scripts and needs to be in the system 

path.

Further information for compiling, setup, and editing these Tetracorder system packages is 

included as AAA.READ.txt files within each package.

Appendix 3—Optional Software

Optional software is required for preprocessing the data and for data analysis after a material 

mapping run is completed. Software normally is required to calibrate the image spectrometer data, 

convert laboratory and field spectra to a common format and spectral resolution, and for visualization of 

images and plots of pixel spectra.

Spectral processing can be performed using the USGS spectral processing program “SPECPR” 

(Clark, 1993; html://speclab.cr.usgs.gov/software.html) and the image/spectral data processing program 

“Davinci”, to generate data for use with Tetracorder. Tetracorder incorporates many of SPECPR’s 

program subroutines for data handling and I/O and so is integrated with the spectral data format of 
49

SPECPR. Davinci also understands the SPECPR data format, reads and writes Vicar, and reads ENVI®

image data formats. A simple Davinci script (included here) also generates ENVI® headers.

Note: SPECPR requires X-window functions to plot spectra. Xming®, Cygwin®-Xwin Server, 

or other software supplies this functionality for Windows computers.

Optional Programs Installation—Windows® PCs

download packages

Download these additional packages. They will be installed using the directions below.

Davinci http://davinci.asu.edu/ (select the “Download” link)

GZIP (Windows only) http://www.gnu.org/software/gzip/ (select either the http or ftp 

server, and choose a Windows executable version of GZIP, such as: “gzip-1.2.4.msdos.exe”).

ppmtogif (Windows only)

http://gnuwin32.sourceforge.net/packages/netpbm.htm (select “Binaries Zip”, and save “netpbm10.27-bin.zip” to a temporary subdirectory, such as: “c:\tmp”).

Xming® or Cygwin®-XWin Server (Windows only)

Xming®: http://www.straightrunning.com

Cygwin®-XWin Server: http://x.cygwin.com

Either of these packages provides an X-server window management system that runs 

under Microsoft Windows®. This is for use with SPECPR only. Tetracorder is nongraphical so it does 

not use X-window software, but SPECPR requires an X-window server if graphic screen plots are to be 

displayed.

(Note: Tetracorder and SPECPR come compiled for Microsoft Windows®, ready to use in the 

download: tetracorder4.4-tutorial.zip described in Appendix 2.)

Davinci—Windows Install

Davinci is a spectral math processing package initially started at USGS and then fully 

developed by ASU. It is used to perform math operations on sample, field, and image spectral data and 

is called by Tetracorder’s controlling batch files to perform post-processing data analysis.

Download and install the Windows-Davinci package using the default installation 

settings. Tetracorder batch-files expect Davinci program files to be there. By following the download 

instructions, Davinci will be installed at:

Windows®-7 - C:\Program Files (x86)\Davinci\

Windows®-XP - C:\PROGRA~1\Davinci\

Davinci will be called for data processing automatically during the mapping run.

GZIP—Windows Install

Download and install the Windows-gzip package. Usually, a single executable file, such as: 

“gzip-1.2.4.msdos.exe,” is downloaded. Rename this file to “gzip.exe” and place it into the Tetracorder 
50

bin-pc directory alongside tetracorder.exe (i.e.: “bin-pc\gzip.exe”). Tetracorder batch-files will find 

“gzip” using the system environment’s “PATH” variable or by the definitions within the startup scripts.

Ppmtogif—Windows Install

Download to a temporary directory, the Windows - “netpbm” package that contains the 

program “ppmtogif” (i.e., save to:. “c:\tmp\netpbm-10.27-bin.zip”). Unzip “netpbm-10.27-bin.zip”. This 

will create a series of nested subdirectories. Copy the program file “ppmtogif.exe” and its DLL library 

“libnetpbm10.dll” to the “bin-pc” directory.

copy to bin-pc:

“ppmtogif.exe”

“libnetpbm10.dll”

This program converts Davinci ppm output images to the GIF format. If “ppmtogif.exe” is not 

installed, tetrun runs to completion, but the section where material maps are copied to GIF format is not 

performed. JPEG images are still formed from the material maps and may be used instead.

Xming—Windows Install

Download and install Xming® (www.straightrunning.com) or Cygwin®-XWin Server 

(x.cygwin.com) if spectral plots using SPECPR are desired. Follow the installation directions.

Start the X-Window server before starting SPEPCR, then start SPEPCR using the supplied 

specpr.bat batch file, present in the “bin-pc” Tetracorder directory, or by copying the specpr shortcut (in

bin-pc) to the screen wallpaper and editing its properties setting to point to “specpr.bat.”

The default “specpr.bat” is set to:

set DISPLAY=localhost:0

specpr.exe r1 –gxterm –

To start SPEPCR and X-Window talking, edit either the system “host” file (preferred) or 

“specpr.bat”

Edit “hosts” for normal X-Window access

edit the “localhost” setting within the “hosts” file at:

“C:\WINDOWS\system32\drivers\etc\hosts”(Windows®-XP)

To be:

127.0.0.1 localhost

(no spaces before 127.0.0.1)

or edit “specpr.bat”

set DISPLAY=127.0.0.1:0)

specpr.exe r1 –gxterm –
51

Optional Programs Installation—LINUX and UNIX®

Note that Linux comes with GZIP, ppmtogif, and an X-window server installed. Also, 

Tetracorder and SPECPR are supplied as source code in the download package: src-local described in 

Appendix 2.

download packages

Download this additional package. It will be installed using the directions below.

Davinci http://davinci.asu.edu/ (select the “Download” link)

Davinci—UNIX/Linux® Install

Davinci is a spectral and image cube math processing package initially started at USGS 

and then fully developed by ASU. It is used to perform math operations on sample, field, and image 

spectral data and is called by Tetracorder’s controlling batch files to perform post-processing data 

analysis.

Download and install the Davinci package using the default installation settings. 

Tetracorder batch-files expect Davinci program files to be there. By following the download 

instructions, Davinci will be installed at:

“/usr/local/bin/”

Davinci will be called for data processing automatically during the mapping run.

Note that Linux comes with GZIP, ppmtogif, and X-window installed. For UNIX® machines or 

Linux distributions without GZIP or ppmtogif, download the source code, compile it, name the file 

“gzip” or “ppmtogif”, and place the executable(s) in a directory in the system “PATH”, such as 

“/usr/local/bin/.”

Appendix 4—Data and Spectral Libraries

Appendix 4 describes the optional data and spectral libraries.

Additional image spectrometer data can be downloaded at: http://aviris.jpl.nasa.gov

Additional material spectral libraries can be downloaded at: 

http://speclab.cr.usgs.gov/spectral-lib.html
Livo and Clark—The Tetracorder User Guide—Version 4.4—Open-Report Report 2013–1300 

ISSN 2331-1258 (online)

http://dx.doi.org/10.3133/ofr20131300