View_SPECPR Software, Installation Procedure, and User’s Guide (Version
1.1)
By Raymond F. Kokaly
This document describes the installation procedure and use
of the “View_SPECPR” IDL
(Interactive Data Language) program to display the contents of SPECPR (SPECtrum
Processing Routines) files within ENVI (ENvironment for Visualizing Images). SPECPR files are used by earth-remote-sensing
scientists and planetary scientists for storing spectra collected by
laboratory, field, and remote sensing instruments. An example is the U.S. Geological Survey (USGS)
spectral library that contains thousands of spectra of minerals, vegetation,
and man-made materials (Clark and others, 2003). SPECPR files contain reflectance data and
associated wavelength and spectral resolution data, as well as meta data on the
time and date of collection and spectrometer settings. Furthermore, the SPECPR file automatically
tracks changes to data records through its “history” functions. For more details on the format and content of
SPECPR files, see Clark (1993). For more details on ENVI, see RSI (2004). This program was designed for full ENVI
4.1/IDL6.1 licenses on Windows XP operating systems and requires the installation
of the iTools components of IDL6.1; however, this program should work with full
licenses on UNIX/LINUX systems and “runtime” licenses of ENVI on Windows XP
operating systems. This software has not
been tested with ENVI licenses on Apple Mac Operating Systems.
1. Download
the routines from the following website: http://pubs.usgs.gov/of/2005/1348/downloads/
2.
Unzip the “view_specpr.zip” file to the
top level of the C-drive (C:\); this should create a new folder C:\view_specpr. Copy the IDL program files (that is, all
files with the .pro extension) within the “view_specpr” folder to your ENVI
“save_add” directory (for installations of ENVI 4.1, the save_add directory is
commonly in the following location: C:\RSI\IDL61\products\ENVI41\save_add\). These IDL procedure files, listed in table 1,
are text files that contain the program code.
They may be viewed within the IDL development environment or by opening
them with a program that can view ASCII text files.
Table 1. IDL procedure files that comprise the View_SPECPR software.
|
Filename
|
|
basename.pro
|
|
check_specpr_file_size.pro
|
|
convert_seconds_to_hourminsec.pro
|
|
create_datestrings.pro
|
|
create_specpr_listing.pro
|
|
decompose_bits.pro
|
|
function_specprlistgui.pro
|
|
read_all_specpr_records.pro
|
|
read_specpr.pro
|
|
read_specpr_header.pro
|
|
read_specpr_record_list.pro
|
|
split_string.pro
|
|
view_specpr.pro
|
|
widget_specpr_text.pro
|
3. Add
new entries to your ENVI menu by inserting the following text, highlighted in blue, into your ENVI menu configuration file just after
the lines that specify the “Window” menu and just before the lines at the end
of that file that specify the “Help” menu item.
On a typical installation of ENVI 4.1, the ENVI menu configuration file
is named C:\RSI\IDL61\products\ENVI41\menu\envi.men).
0
{Window}
1 {Window Finder} {widget controller list}
{envi_menu_event}
1 {Start New Display Window} {display window}
{envi_menu_event} {separator}
1 {Start New Vector Window} {vector window}
{envi_menu_event}
1 {Start New Plot Window} {new window0}
{envi_menu_event}
1 {Available Files List} {available files
list} {envi_menu_event} {separator}
1 {Available Bands List} {available bands
list} {envi_menu_event}
1 {Available Vectors List} {available vectors
list} {envi_menu_event}
1 {Mouse Button Descriptions} {mouse
descriptions} {envi_menu_event} {}
1 {Display Information} {display information}
{envi_menu_event}
1 {Cursor Location/Value} {cursor location}
{envi_menu_event}
1 {Point Collection} {point collection}
{envi_menu_event}
1 {Maximize Open Displays} {sort displays}
{envi_menu_event} {separator}
1 {Link Displays} {link displays}
{envi_menu_event}
1 {Close All Display Windows} {close all
displays} {envi_menu_event} {}
1 {Close All Plot Windows} {close all plot
windows} {envi_menu_event}
--------------------------- INSERT TEXT FOLLOWING
THIS LINE--------------------
0 {User Functions}
1 {View SPECPR File} { } {view_specpr}
--------------------------- INSERT TEXT PRECEEDING
THIS LINE-------------------
0
{Help}
1 {Start ENVI Online Help} {envi help}
{envi_menu_event}
1 {Mouse Button Descriptions} {mouse
descriptions} {envi_menu_event}
1 {What's New in ENVI 4.1} {envi whats new}
{envi_menu_event} {separator}
1 {About
ENVI} {about envi} {envi_menu_event
4. Start
the ENVI program. The main menu bar
should look like figure 1. There should
be one option under the “User Functions” menu item when you click on it, as
shown in figure 2.
Figure 1. ENVI menu bar with new "User Functions" option.
Figure 2. ENVI menu bar with new SPECPR file viewing option.
To initiate the widget program, click the “View SPECPR
File” option under the “User Functions” item on the ENVI menu bar. Figure 3 shows the main program control
widget that will appear.
Figure 3. ENVI widget that controls viewing of SPECPR files.
1.
Select the input SPECPR file by clicking on the
“Select SPECPR File” button at the top left corner of the widget. A dialog widget (fig. 4) appears, in which
the SPECPR file can be selected.
Figure 4. Selecting a SPECPR file.
2. In
the View_SPECPR control window (fig. 3), click the “List Selected SPECPR File”
button. Figure 5 shows an example of the
file listing that appears after following the first two steps. Each line in the list shows the record number
in the left column, the record title in the second column, and the number of
data channels or text characters in the third column. If the record is a data
record, the date the data were collected is shown in the right column;
otherwise, the text records do not have an associated collection date, and this
column is blank for text records. If the
spectrum’s data collection date was not set in the header of the SPECPR data
record when it was added to the SPECPR file, the column shows the text “no date
set”. Note: Not all record numbers are
listed. The file listing shows only the
beginning record of the set of fixed length records in which a spectrum is
stored; the listing does not show “continuation records” that are used when the
data length exceeds the length of the first record. For more details on record lengths and
continuation records see Clark (1993). For example, records 1 to 6 are listed in figure
5. However, the next record listed is
record 8. This is because record 6 has
480 channels of data that require two records for storage. The listing does not show record 7, which is
merely a continuation record. The next
spectrum stored in the SPECPR file, after record 6, is listed next-- in this
case record 8.
Figure 5. An example listing of the contents of a SPECPR file.
The scroll bar on the right-hand side of the list in figure
5 can be used to scroll through the listing of records in the SPECPR file. The user also can type a record number in the
box to the right of the “Selected Record Number =” label. The view in the list box will jump to the
area of the SPECPR file that contains the closest record to the number input by
the user.
To output a text listing of the SPECPR file, the user can click
the “Save List” button in the bottom left corner of the widget. This will open a file selection widget so the
user can set the name of a file that will hold a plain text listing of the records
in the previously selected and listed SPECPR file.
1.
Setting the data record. The user must click on the data record for
which the spectral plot is desired or enter the record number in the text box
next to the “Selected Record Number =” label.
Figure 6 shows an example of clicking on record number 53. Once a data record is selected, the text box
next to the selected record number shows the value encoded in the SPECPR record
for the wavelength record. The user can click
the “<-- set wavelength record to that associated with selected record
listed above” button to use this as the wavelength record. Note: In some SPECPR records the wavelength
record is not set to the correct record number; in such cases, the user will
have to set the wavelength record as described in Step 2.
Figure 6. Setting the data record.
2. Setting
the wavelength record. Before plotting,
the user must set the record number that corresponds to the wavelengths of the
channels of the spectrometer for which data will be plotted. The user can type this record number in the
box to the right of the “Wavelength Record =” label. Using the example in figure 5, the number “6”
could be entered into the box in order to select record 6, “Wavelengths USGS
Denver Beckman STD 1x”, as the wavelength record. After the user clicks enter
or moves the cursor out of the text box, the record number entered will be
accepted if it corresponds to a record number in the list. Alternatively, the wavelength record can be
set using the wavelength record value encoded in the header of the data record by
clicking the button labeled “<-- set wavelength record to that associated
with selected record listed above”. Figure
7 shows an example of setting the wavelength to record number 6.
Figure 7. Setting the wavelength record.
If the user enters a number that does not correspond to a
listed record number, then the message shown in figure 8 appears, and the value
in the wavelength record field is set to a default value of 1. The user must
then enter the correct wavelength record.
This could happen if the record number is mistyped or if the wavelength
record value in the header is not set correctly.
Figure 8. Warning message following an error in wavelength record selection.
3. Plotting
the data. The user must click the “Plot
Selected Record” button in order to make the plot appear. If the number of channels in the wavelength
record set in step 2 does not match the number of channels in the data record, set
in step 1, then a warning box will appear, and no spectrum will be
plotted. Figure 9 shows an example of
plotting record 53 of the example SPECPR file using record 6 as the wavelength
record. The plotted spectrum contains
all the valid data in the wavelength and data records; however, the channels
that have the SPECPR deleted point value (-1.23e+34) are not
represented in the plot. Text describing
the SPECPR file and record that correspond to the plotted spectrum appears
beneath the plot. Note: The plotting
function requires the installation of the “iTools” routines distributed by
IDL/ENVI; the iTools routines usually are installed by default. Using the built-in functions of the iPlot
routine of the iTools toolbox, the user may change axes limits, change axes
labels, annotate the plot, etc. Consult
the IDL documentation on iTools and iPlot for more information.
Figure 9. Plotting data records.
4. Overplotting
data. The user may repeat step 1 and click
the “Overplot Selected Record” button in order to overlay other measurements that
have the same previously specified wavelength record. Alternatively, the user may enter a new
wavelength record and new data record (repeating steps 1 and 2) and click the
“Overplot Selected Record” button. This
can be repeated to plot as many records as desired. Figure 10 shows the widget state after
selecting a new wavelength and data record.
Note: The data will be overplotted on the last plot created or in the
last window that the user has clicked in or interacted with. For example, if the user has created two plot
windows and wishes to overplot a spectrum in the first window created, the user
can then “left-click” on the first plot window and then click the “Overplot
Selected Record” button in the main program widget.
Figure 10. Selecting new wavelength and data records.
Figure 11 shows an example of overplotting the
reflectance spectrum of an aspen leaf, which was measured with a different
spectrometer. The new spectrum is shown
in a different color, and the text describing the SPECPR file and record of
this overplotted spectrum is put below the text describing the previously
plotted spectrum. While any number of
spectra can be overplotted, eventually there will not be enough room below the
plot for the descriptive text, and that text will not appear in the iPlot
widget. Note: The user also may select
and list the contents of another SPECPR file and overplot a data record from it
by choosing wavelength and data records from the new listing and clicking the
“Overplot Selected Record” button.
Figure 11. Overplotting data records.
For a selected record, further information about the
record may be obtained by clicking on the “Show Text/Manual History/DESCRIPT of
Record” button in the bottom right corner of the widget. There are three different responses,
dependent on the type of record selected:
1.
Data record.
If the selected record is a data record, for example record 10722 in figure
10, information from the data record header will be displayed as shown in figure
12.
Figure 12. Header information from a data record.
2. Text
record. If the selected record is a text
record, for example record 1 in figure 5, the text information will be
displayed, as shown in figure 13.
Figure 13. Text information from a text record.
3. DESCRIPT
record. If the selected record is a description
(DESCRIPT) found in published USGS spectral library SPECPR files, an Internet
Explorer window should open and reveal the contents of the HTML file that
describes the spectral library entry. An
example of the html information for the DESCRIPT record 47 in figure 5 is shown
in figure 14. For more information on
DESCRIPT records and the USGS Spectral Library, see Clark and others (2003). Note: Photos referred to in the html DESCRIPT
records may not appear, since the locations of these photos on each user’s
computer may be different. If the folders
containing the photos of samples in the spectral library are placed in the same
directory as the spectral library SPECPR file, then these images should appear
correctly in the browser window.
Figure 14. Example of detailed information from a spectral library DESCRIPT
record.
The “Help file” (this document) can be opened by clicking
on the “Help” menu item at the top of the main program widget (see fig. 3) and
choosing the “Help on View_SPECPR” option that appears. Select the “View_SPECPR_help.htm” document in
the “view_specpr” folder extracted from the zip file. This should be located at C:/view_specr/view_SPECPR_help.htm,
if the user followed the instructions in the “Installation of IDL Routines”
section of this document. An Internet
Explorer window should appear with an html version of this document.
The program can be closed by clicking on the “File” menu
item in the top left corner of the widget (see fig. 3) and choosing the “Quit”
option that appears. Note: The main
widget and all child widgets (plot windows and text information boxes) will close
when quitting the program.
This section describes selected functions of the iPlot
tool in ENVI/IDL. For comprehensive
information on the tool, consult the documentation provided by RSI for your
ENVI/IDL version number.
This feature of iPlot allows the user to export the
contents of the plot window to an encapsulated postscript (eps) file. The advantage offered by the use of this
function is that the individual vector elements of the plot (such as the font
of the title, the thickness of the x-axis, or the color of the plot line) can
be manipulated when the eps file is imported into a program such as Adobe Illustrator. To start the export process, click the export
option under the file menu of the iPlot window (see fig. 15).
Figure 15. Exporting the plot to an encapsulated postscript file.
1.
Select the export destination as “To a File” and
click the “Next” button (see fig. 16).
Figure
16. Exporting the plot to an encapsulated postscript file
– step 1.
2. Select
the export item as the “Window” by clicking on it and click the “Next” button
(see fig. 17).
Figure 17. Exporting the plot to an encapsulated postscript file – step 2.
3. Set
the export file type as “Encapsulated Postscript (*.eps)”. Make sure the “Graphics format” is set to
“Vector” and not to “Bitmap.” Set the
output filename and click the “Finish” button (see fig. 18).
Figure 18. Exporting the plot to an encapsulated postscript file – step 3.
This feature of iPlot allows the user to export a spectrum’s
wavelength or reflectance values to an ASCII
text file. The advantage offered by
the use of this function is that the exported data can be read into other
programs. Note: This function allows you
to export the data displayed in the plot window, which may differ from the data
stored in the SPECPR record, because “deleted points” are removed from the data
array before plotting to the iPlot window.
Deleted points are data points with values of -1.23e+34 (see
the SPECPR documentation; Clark, 1993). To start the export process, click the export
option under the file menu of the iPlot window (see fig. 15).
1.
Select the export destination as “To a File” and
click the “Next” button (see fig. 16).
2.
Select the export item as the “X” or “Y” by
selecting it and click the “Next” button (see fig. 19). By selecting “X” you will export the
wavelength data. By selecting “Y” you
will export the reflectance data.
Figure 19. Exporting data to an ASCII text file – step 2.
3. Make
sure the export file type is set to “ASCII Text (*.txt)”. Set the output filename and click the “Finish”
button (see fig. 20).
Figure 20. Exporting data to an ASCII text file – step 3.
September 12,
2005. Original release to
public.
This program was designed for full ENVI 4.1/IDL6.1
licenses on Windows operating systems and requires the installation of the iTools
components of IDL6.1.
Clark, R.N., 1993, SPECtrum
Processing Routines User's Manual Version 3 (program SPECPR), U.S. Geological
Survey, Open File Report 93-595, 210 pages. The SPECPR program is available online
at http://speclab.cr.usgs.gov.
Clark, R.N., Swayze, G.A., Wise, R., Livo, K.E., Hoefen, T.M.,
Kokaly, R.F., and Sutley, S.J., 2003, USGS Digital Spectral Library splib05a,
USGS Open File Report 03-395. Digital SPECPR
files of this library are available online at http://speclab.cr.usgs.gov.
RSI, 2004, ENVI User’s Guide, ENVI 4.1 September 2004
Edition, Research Systems Inc., Boulder, Colorado,
1150 pages.
