View_SPECPR Software, Installation Procedure, and User’s Guide (Version 1.1)

By Raymond F. Kokaly

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Open-File Report 2005-1348

 

 

 

 

 

 

 

 

 

U.S. Department of the Interior

U.S. Geological Survey

U.S. Department of the Interior

Gale A. Norton, Secretary

U.S. Geological Survey

P. Patrick Leahy, Acting Director

U.S. Geological Survey, Reston, Virginia 2005
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.


Contents

Introduction. 1

Installation of IDL Routines. 1

Running the program to view SPECPR files. 3

Function 1 – Listing the contents of a SPECPR file. 4

Function 2 – Navigating through the file listing. 6

Function 3 – Saving the list of the SPECPR file. 6

Function 4 – Plotting the data from selected records. 6

Function 5 – Showing the header information in data records, text information in text records, and html information in DESCRIPT records. 11

Function 6 – Viewing the “Help file”. 13

Function 7 – Quitting the program. 14

iPlot Functions. 14

Function 1. “Export to encapsulated postscript” 14

Function 2. “Export to ASCII text” 16

Release Notes. 18

References Cited. 18

 

Figures

1.  ENVI menu bar with new "User Functions" option. 3

2.  ENVI menu bar with new SPECPR file viewing option. 3

3.  ENVI widget that controls viewing of SPECPR files. 4

4.  Selecting a SPECPR file. 5

5.  An example listing of the contents of a SPECPR file. 6

6.  Setting the data record. 7

7.  Setting the wavelength record. 8

8.  Warning message following an error in wavelength record selection. 8

9.  Plotting data records. 9

10.  Selecting new wavelength and data records. 10

11.  Overplotting data records. 11

12.  Header information from a data record. 12

13.  Text information from a text record. 12

14.  Example of detailed information from a spectral library DESCRIPT record. 13

15.  Exporting the plot to an encapsulated postscript file. 14

16.  Exporting the plot to an encapsulated postscript file – step 1. 15

17.  Exporting the plot to an encapsulated postscript file – step 2. 15

18.  Exporting the plot to an encapsulated postscript file – step 3. 16

19.  Exporting data to an ASCII text file – step 2. 17

20.  Exporting data to an ASCII text file – step 3. 17

 

Tables

1. IDL procedure files that comprise the View_SPECPR software. 2


View_SPECPR Software, Installation Procedure, and User’s Guide (Version 1.1)

By Raymond F. Kokaly[1]

 

Introduction

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.

 

 

Installation of IDL Routines

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.

 

 

Running the program to view SPECPR files

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.

 

 

Function 1 – Listing the contents of a SPECPR file.

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.

 

 

Function 2 – Navigating through the file listing.

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.

Function 3 – Saving the list of the SPECPR file.

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.

Function 4 – Plotting the data from selected records.

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.

 

 

Function 5 – Showing the header information in data records, text information in text records, and html information in DESCRIPT 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.

 

 

Function 6 – Viewing the “Help file”.

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.

Function 7 – Quitting the program.

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.

 

 

iPlot Functions

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.

Function 1. “Export to encapsulated postscript”

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.

 

 

Function 2. “Export to ASCII text”

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.

 

 


Release Notes

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. 

 

 

References Cited

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.



[1] Raymond F. Kokaly, USGS, MS 964 Box 25046, Denver Federal Center, Denver CO 80225, USA. raymond@usgs.gov