View_SPECPR Software, Installation Procedure, and User’s Guide (Version 1.1)
By Raymond F. Kokaly
Open-File Report 2005-1348
Gale A. Norton, Secretary
P. Patrick Leahy, Acting Director
U.S. Geological Survey,
Revised and reprinted: 2005
For product and ordering information:
World Wide Web: http://www.usgs.gov/pubprod
Telephone: 1-888-ASK-USGS
For more information on the USGS—the Federal source for
science about the Earth,
its natural and living resources, natural hazards, and the environment:
World Wide Web: http://www.usgs.gov
Telephone: 1-888-ASK-USGS
Suggested citation:
Kokaly, R.F., 2005, View_SPECPR Software, Installation Procedure, and User’s
Guide: U.S. Geological Survey Open-File Report 2005-1348, 18 p.
Any use of trade, product, or firm names is for descriptive
purposes only and does not imply
endorsement by the U.S. Government.
Although this report is in the public domain, permission
must be secured from the individual
copyright owners to reproduce any copyrighted material contained within this
report.
Running the program to view SPECPR files
Function 1 – Listing the contents of a SPECPR file.
Function 2 – Navigating through the file listing.
Function 3 – Saving the list of the SPECPR file.
Function 4 – Plotting the data from selected records.
Function 6 – Viewing the “Help file”.
Function 7 – Quitting the program.
Function 1. “Export to encapsulated postscript”
Function 2. “Export to ASCII text”
1.
ENVI menu bar with new
"User Functions" option.
2. ENVI menu bar with new SPECPR file viewing
option.
3. ENVI widget that controls viewing of SPECPR
files.
5.
An example listing of the
contents of a SPECPR file.
7. Setting the wavelength record.
8. Warning message following an error in
wavelength record selection.
10. Selecting new wavelength and data records.
11. Overplotting data records.
12. Header information from a data record.
13. Text information from a text record.
14. Example of detailed information from a
spectral library DESCRIPT record.
15. Exporting the plot to an encapsulated
postscript file.
16. Exporting the plot to an encapsulated
postscript file – step 1.
17. Exporting the plot to an encapsulated
postscript file – step 2.
18. Exporting the plot to an encapsulated
postscript file – step 3.
19. Exporting data to an ASCII text file – step
2.
20. Exporting data to an ASCII text file – step
3.
1.
IDL procedure files that comprise the View_SPECPR software.
View_SPECPR Software, Installation Procedure, and User’s Guide (Version
1.1)
By Raymond F. Kokaly[1]
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
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
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;
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.
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., 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.,
[1]
Raymond F. Kokaly, USGS, MS 964