ENVI Reference Guide - Harris Geospatial · ESRI ®, ArcGIS® ... ENVI Reference Guide 3 Contents...
Transcript of ENVI Reference Guide - Harris Geospatial · ESRI ®, ArcGIS® ... ENVI Reference Guide 3 Contents...
ENVI Version 4.7August, 2009 EditionCopyright © ITT Visual Information SolutionsAll Rights Reserved
ENVI Reference Guide
20REF47DOC
Restricted Rights NoticeThe IDL®, IDL Advanced Math and Stats™, ENVI®, ENVI Zoom™, and ENVI® EX software programs and the accompanying procedures, functions, and documentation described herein are sold under license agreement. Their use, duplication, and disclosure are subject to the restrictions stated in the license agreement. ITT Visual Information Solutions reserves the right to make changes to this document at any time and without notice.
Limitation of WarrantyITT Visual Information Solutions makes no warranties, either express or implied, as to any matter not expressly set forth in the license agreement, including without limitation the condition of the software, merchantability, or fitness for any particular purpose.
ITT Visual Information Solutions shall not be liable for any direct, consequential, or other damages suffered by the Licensee or any others resulting from use of the software packages or their documentation.
Permission to Reproduce this ManualIf you are a licensed user of these products, ITT Visual Information Solutions grants you a limited, nontransferable license to reproduce this particular document provided such copies are for your use only and are not sold or distributed to third parties. All such copies must contain the title page and this notice page in their entirety.
Export Control InformationThis software and associated documentation are subject to U.S. export controls including the United States Export Administration Regulations. The recipient is responsible for ensuring compliance with all applicable U.S. export control laws and regulations. These laws include restrictions on destinations, end users, and end use.
AcknowledgmentsENVI® and IDL® are registered trademarks of ITT Corporation, registered in the United States Patent and Trademark Office. ION™, ION Script™, ION Java™, and ENVI Zoom™ are trademarks of ITT Visual Information Solutions.
ESRI®, ArcGIS®, ArcView®, and ArcInfo® are registered trademarks of ESRI.
Portions of this work are Copyright © 2009 ESRI. All rights reserved.
PowerPoint® and Windows® are registered trademarks of Microsoft Corporation in the United States and/or other countries.
Macintosh® is a registered trademark of is a trademark of Apple Inc., registered in the U.S. and other countries.
UNIX® is a registered trademark of The Open Group.
Adobe Illustrator® and Adobe PDF® Print Engine are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
Numerical Recipes™ is a trademark of Numerical Recipes Software. Numerical Recipes routines are used by permission.
GRG2™ is a trademark of Windward Technologies, Inc. The GRG2 software for nonlinear optimization is used by permission.
NCSA Hierarchical Data Format (HDF) Software Library and Utilities. Copyright © 1988-2001, The Board of Trustees of the University of Illinois. All rights reserved.
NCSA HDF5 (Hierarchical Data Format 5) Software Library and Utilities. Copyright © 1998-2002, by the Board of Trustees of the University of Illinois. All rights reserved.
CDF Library. Copyright © 2002, National Space Science Data Center, NASA/Goddard Space Flight Center.
NetCDF Library. Copyright © 1993-1999, University Corporation for Atmospheric Research/Unidata.
HDF EOS Library. Copyright © 1996, Hughes and Applied Research Corporation.
SMACC. Copyright © 2000-2004, Spectral Sciences, Inc. and ITT Visual Information Solutions. All rights reserved.
This software is based in part on the work of the Independent JPEG Group.
Portions of this software are copyrighted by DataDirect Technologies, © 1991-2003.
BandMax®. Copyright © 2003, The Galileo Group Inc.
Portions of this computer program are copyright © 1995-2008 Celartem, Inc., doing business as LizardTech. All rights reserved. MrSID is protected by U.S. Patent No. 5,710,835. Foreign Patents Pending.
Portions of this software were developed using Unisearch’s Kakadu software, for which ITT has a commercial license. Kakadu Software. Copyright © 2001. The University of New South Wales, UNSW, Sydney NSW 2052, Australia, and Unisearch Ltd, Australia.
This product includes software developed by the Apache Software Foundation (www.apache.org/).
MODTRAN is licensed from the United States of America under U.S. Patent No. 5,315,513 and U.S. Patent No. 5,884,226.
QUAC and FLAASH are licensed from Spectral Sciences, Inc. under U.S. Patent No. 6,909,815 and U.S. Patent No. 7,046,859 B2.
Portions of this software are copyrighted by Merge Technologies Incorporated.
Support Vector Machine (SVM) is based on the LIBSVM library written by Chih-Chung Chang and Chih-Jen Lin (www.csie.ntu.edu.tw/~cjlin/libsvm), adapted by ITT Visual Information Solutions for remote sensing image supervised classification purposes.
IDL Wavelet Toolkit Copyright © 2002, Christopher Torrence.
IMSL is a trademark of Visual Numerics, Inc. Copyright © 1970-2006 by Visual Numerics, Inc. All Rights Reserved.
Other trademarks and registered trademarks are the property of the respective trademark holders.
Contents
Chapter 1Overview .......................................................................................................... 11How to Use this Reference Section .............................................................................................. 12Alphabetic List of ENVI Library Routines .................................................................................. 16Functional List of ENVI Library Routines ................................................................................... 28Common Keywords ...................................................................................................................... 34Quick Reference of ENVI Variable Codes ................................................................................... 36Chapter 2ENVI Routines ................................................................................................. 39ADAPT_FILT_DOIT ................................................................................................................... 40AIRSAR_HEADER_DOIT .......................................................................................................... 44AIRSAR_PED_HEIGHT_DOIT .................................................................................................. 46AIRSAR_PHASE_IMAGE_DOIT .............................................................................................. 48AIRSAR_POLSIG_DOIT ............................................................................................................ 50AIRSAR_SCATTER_DOIT ........................................................................................................ 53AIRSAR_SYNTH_DOIT ............................................................................................................. 56ASPECT_DOIT ............................................................................................................................ 59AUTO_WID_MNG ...................................................................................................................... 61BAD_DATA_DOIT ..................................................................................................................... 62CF_DOIT ...................................................................................................................................... 64CLASS_CONFUSION_DOIT ..................................................................................................... 66CLASS_CS_DOIT ....................................................................................................................... 70CLASS_DOIT .............................................................................................................................. 72
ENVI Reference Guide 3
4
CLASS_MAJORITY_DOIT ........................................................................................................ 81CLASS_RULE_DOIT .................................................................................................................. 83CLASS_STATS_DOIT ................................................................................................................ 85COM_CLASS_DOIT ................................................................................................................... 89CONTINUUM_REMOVE_DOIT ............................................................................................... 91CONV_DOIT ............................................................................................................................... 93CONVERT_DOIT ........................................................................................................................ 96CONVERT_INPLACE_DOIT ..................................................................................................... 98CROSS_TRACK_CORRECTION_DOIT ................................................................................. 100DARK_SUB_DOIT .................................................................................................................... 103DECOR_DOIT ........................................................................................................................... 105DEM_BAD_DATA_DOIT ........................................................................................................ 107DESKEW_DOIT ........................................................................................................................ 109DESTRIPE_DOIT ...................................................................................................................... 111DISP_GET_LOCATION ........................................................................................................... 113DISP_GOTO .............................................................................................................................. 115DISP_OUT_IMG ........................................................................................................................ 117ELINE_CAL_DOIT ................................................................................................................... 120EMITTANCE_CALC_DOIT ..................................................................................................... 122ENVI ........................................................................................................................................... 124ENVIZOOM ............................................................................................................................... 125ENVI_ACE_DOIT ..................................................................................................................... 126ENVI_ADD_PROJECTION ...................................................................................................... 129ENVI_ASSIGN_HEADER_VALUE ........................................................................................ 130ENVI_AUTO_TIE_POINTS_DOIT .......................................................................................... 132ENVI_AVHRR_CALIBRATE_DOIT ....................................................................................... 136ENVI_AVHRR_GEOMETRY_DOIT ....................................................................................... 138ENVI_AVHRR_WARP_DOIT .................................................................................................. 140ENVI_BANDMAX_SELECT_BANDS .................................................................................... 144ENVI_BATCH_EXIT ................................................................................................................ 147ENVI_BATCH_INIT ................................................................................................................. 148ENVI_BATCH_STATUS_WINDOW ...................................................................................... 149ENVI_BUFFER_ZONE_DOIT ................................................................................................. 151ENVI_CAL_DOIT ..................................................................................................................... 153ENVI_CEM_DOIT .................................................................................................................... 155ENVI_CENTER ......................................................................................................................... 158ENVI_CLOSE_DISPLAY ......................................................................................................... 159ENVI_CLOVER_DOIT ............................................................................................................. 160ENVI_COLLECT_SPECTRA ................................................................................................... 162ENVI_COMPUTE_SUN_ANGLES .......................................................................................... 164ENVI_CONVERT_FILE_COORDINATES ............................................................................. 166ENVI_CONVERT_FILE_MAP_PROJECTION ....................................................................... 168ENVI_CONVERT_LIDAR_DATA_DOIT ............................................................................... 172
Contents ENVI Reference Guide
5
ENVI_CONVERT_PROJECTION_COORDINATES .............................................................. 175ENVI_CREATE_ROI ................................................................................................................ 177ENVI_CUBE_3D_DOIT ............................................................................................................ 179ENVI_DEFAULT_STRETCH_CREATE ................................................................................. 181ENVI_DEFINE_MENU_BUTTON .......................................................................................... 183ENVI_DEFINE_ROI .................................................................................................................. 188ENVI_DELETE_ROIS .............................................................................................................. 190ENVI_DISP_QUERY ................................................................................................................ 191ENVI_DISPLAY_BANDS ........................................................................................................ 194ENVI_DOIT ............................................................................................................................... 196ENVI_ENTER_DATA ............................................................................................................... 198ENVI_ENVISAT_GEOREF_DOIT .......................................................................................... 204ENVI_EVF_CLOSE .................................................................................................................. 206ENVI_EVF_DEFINE_ADD_RECORD .................................................................................... 207ENVI_EVF_DEFINE_CLOSE .................................................................................................. 211ENVI_EVF_DEFINE_INIT ....................................................................................................... 212ENVI_EVF_INFO ...................................................................................................................... 214ENVI_EVF_OPEN ..................................................................................................................... 216ENVI_EVF_READ_RECORD .................................................................................................. 217ENVI_EVF_TO_SHAPEFILE ................................................................................................... 219ENVI_FILE_MNG ..................................................................................................................... 221ENVI_FILE_QUERY ................................................................................................................ 222ENVI_FILE_TYPE .................................................................................................................... 228ENVI_FILTER_DOIT ................................................................................................................ 231ENVI_FX_DOIT ........................................................................................................................ 233ENVI_GEOREF_FROM_GLT_DOIT ...................................................................................... 240ENVI_GET_CONFIGURATION_VALUES ............................................................................ 243ENVI_GET_DATA .................................................................................................................... 244ENVI_GET_DISPLAY_NUMBERS ......................................................................................... 246ENVI_GET_FILE_IDS .............................................................................................................. 247ENVI_GET_HEADER_VALUE ............................................................................................... 248ENVI_GET_IMAGE .................................................................................................................. 251ENVI_GET_MAP_INFO ........................................................................................................... 253ENVI_GET_PATH .................................................................................................................... 254ENVI_GET_PROJECTION ....................................................................................................... 255ENVI_GET_RGB_TRIPLETS .................................................................................................. 257ENVI_GET_ROI ........................................................................................................................ 258ENVI_GET_ROI_DATA ........................................................................................................... 259ENVI_GET_ROI_DIMS_PTR ................................................................................................... 261ENVI_GET_ROI_IDS ................................................................................................................ 262ENVI_GET_ROI_INFORMATION .......................................................................................... 264ENVI_GET_SLICE .................................................................................................................... 266ENVI_GET_STATISTICS ......................................................................................................... 267
ENVI Reference Guide Contents
6
ENVI_GET_TILE ...................................................................................................................... 269ENVI_GLT_DOIT ..................................................................................................................... 271ENVI_GRID_DOIT ................................................................................................................... 273ENVI_GS_SHARPEN_DOIT .................................................................................................... 276ENVI_ICA_DOIT ...................................................................................................................... 279ENVI_ICA_INV_DOIT ............................................................................................................. 283ENVI_INFO_WID ..................................................................................................................... 286ENVI_INIT_TILE ...................................................................................................................... 287ENVI_IO_ERROR ..................................................................................................................... 289ENVI_LAYER_STACKING_DOIT .......................................................................................... 290ENVI_MAP_INFO_CREATE ................................................................................................... 294ENVI_MASK_APPLY_DOIT ................................................................................................... 298ENVI_NEURAL_NET_DOIT ................................................................................................... 300ENVI_OPEN_DATA_FILE ....................................................................................................... 304ENVI_OPEN_FILE .................................................................................................................... 310ENVI_OSP_DOIT ...................................................................................................................... 311ENVI_OUTPUT_TO_EXTERNAL_FORMAT ........................................................................ 314ENVI_PC_SHARPEN_DOIT .................................................................................................... 317ENVI_PICKFILE ....................................................................................................................... 319ENVI_PLOT_DATA .................................................................................................................. 321ENVI_PROJ_CREATE .............................................................................................................. 323ENVI_QUAC_DOIT .................................................................................................................. 328ENVI_QUERY_VERSION ........................................................................................................ 330ENVI_RADARSAT_GEOREF_DOIT ...................................................................................... 331ENVI_READ_COLS .................................................................................................................. 333ENVI_REGISTER_DOIT .......................................................................................................... 335ENVI_REPORT_ERROR .......................................................................................................... 340ENVI_REPORT_INC ................................................................................................................ 341ENVI_REPORT_INIT ............................................................................................................... 342ENVI_REPORT_STAT ............................................................................................................. 344ENVI_RESAMPLE_SPECTRA ................................................................................................ 346ENVI_RESTORE_ROIS ............................................................................................................ 348ENVI_ROI_TO_IMAGE_DOIT ................................................................................................ 349ENVI_RXD_DOIT ..................................................................................................................... 351ENVI_SAVE_ROIS ................................................................................................................... 353ENVI_SEAWIFS_GEOMETRY_DOIT .................................................................................... 354ENVI_SEAWIFS_GEOREF_DOIT .......................................................................................... 356ENVI_SEGMENT_DOIT .......................................................................................................... 359ENVI_SELECT .......................................................................................................................... 361ENVI_SENSOR_TYPE ............................................................................................................. 365ENVI_SET_INHERITANCE ..................................................................................................... 367ENVI_SETUP_HEAD ............................................................................................................... 370ENVI_SMACC_DOIT ............................................................................................................... 378
Contents ENVI Reference Guide
7
ENVI_SPECTRAL_RESAMPLING_DOIT .............................................................................. 381ENVI_STATS_DOIT ................................................................................................................. 383ENVI_SUBSPACE_BACKGROUND_STATS_DOIT ............................................................ 388ENVI_SUM_DATA_DOIT ....................................................................................................... 391ENVI_SVM_DOIT .................................................................................................................... 394ENVI_SYNTHETIC_COLOR_DOIT ....................................................................................... 398ENVI_TCIMF_DOIT ................................................................................................................. 400ENVI_TCIMF_MF_DOIT ......................................................................................................... 403ENVI_THERMAL_CORRECT_DOIT ..................................................................................... 406ENVI_TILE_DONE ................................................................................................................... 408ENVI_TOGGLE_CATCH ......................................................................................................... 409ENVI_TRANSLATE_PROJECTION_NAME .......................................................................... 410ENVI_TRANSLATE_PROJECTION_UNITS .......................................................................... 411ENVI_USER_DEFINED_ANNOTATION ............................................................................... 412ENVI_VEG_INDEX_AVAILABLE_INDICES ....................................................................... 419ENVI_VEG_INDEX_DOIT ...................................................................................................... 421ENVI_VEG_SUPPRESS_DOIT ................................................................................................ 423ENVI_WRITE_COSMOSKYMED_METADATA .................................................................. 425ENVI_WRITE_DBF_FILE ........................................................................................................ 426ENVI_WRITE_ENVI_FILE ...................................................................................................... 427ENVI_WRITE_FILE_HEADER ............................................................................................... 435ENVI_WRITE_STATISTICS .................................................................................................... 436FFT_DOIT .................................................................................................................................. 438FFT_INV_DOIT ......................................................................................................................... 440GAINOFF_DOIT ....................................................................................................................... 443GEN_IMAGE_DOIT ................................................................................................................. 445HANDLE_VALUE .................................................................................................................... 448HIST_EXPORT_DOIT .............................................................................................................. 449MAGIC_MEM_CHECK ............................................................................................................ 452MATCH_FILTER_DOIT ........................................................................................................... 454MATCH_FILTER_MT_DOIT ................................................................................................... 457MATH_DOIT ............................................................................................................................. 460MNF_DOIT ................................................................................................................................ 462MNF_INV_DOIT ....................................................................................................................... 465MORPH_DOIT .......................................................................................................................... 466MOSAIC_DOIT ......................................................................................................................... 468MUNSELL_DOIT ...................................................................................................................... 472MUNSELL_INV_DOIT ............................................................................................................. 474NDVI_DOIT ............................................................................................................................... 477RADAR_INC_ANGLE_DOIT .................................................................................................. 480RATIO_DOIT ............................................................................................................................ 482RESIZE_DOIT ........................................................................................................................... 484RGB_GET_BANDS ................................................................................................................... 486
ENVI Reference Guide Contents
8
RGB_ITRANS_DOIT ................................................................................................................ 488RGB_TRANS_DOIT ................................................................................................................. 490ROC_CURVE_DOIT ................................................................................................................. 492ROI_THRESH_DOIT ................................................................................................................ 495ROTATE_DOIT ......................................................................................................................... 497RTV_DOIT ................................................................................................................................. 499SAT_STRETCH_DOIT ............................................................................................................. 501SHARPEN_DOIT ...................................................................................................................... 503SIRC_HEADER_DOIT .............................................................................................................. 506SIRC_MULTILOOK_DOIT ...................................................................................................... 509SIRC_PED_HEIGHT_DOIT ..................................................................................................... 512SIRC_PHASE_IMAGE_DOIT .................................................................................................. 515SIRC_POLSIG_DOIT ................................................................................................................ 518SIRC_SYNTH_DOIT ................................................................................................................ 521SLICE_DOIT .............................................................................................................................. 525SLT2GND_DOIT ....................................................................................................................... 526SPECTRAL_FEATURE_DOIT ................................................................................................. 528STRETCH_DOIT ....................................................................................................................... 530TASCAP_DOIT ......................................................................................................................... 533TEXTURE_COOCCUR_DOIT ................................................................................................. 535TEXTURE_STATS_DOIT ........................................................................................................ 538TIMS_CAL_DOIT ..................................................................................................................... 540TMCAL_DOIT ........................................................................................................................... 542TOPO_DOIT .............................................................................................................................. 546TOPO_FEATURE_DOIT .......................................................................................................... 549PC_ROTATE .............................................................................................................................. 553PPI_DOIT ................................................................................................................................... 556VAX_IEEE_DOIT ..................................................................................................................... 559WIDGET_AUTO_BASE ........................................................................................................... 561WIDGET_EDIT ......................................................................................................................... 563WIDGET_GEO .......................................................................................................................... 566WIDGET_MAP .......................................................................................................................... 568WIDGET_MENU ....................................................................................................................... 570WIDGET_MULTI ...................................................................................................................... 572WIDGET_OUTF ........................................................................................................................ 575WIDGET_OUTFM .................................................................................................................... 577WIDGET_PARAM .................................................................................................................... 579WIDGET_PMENU .................................................................................................................... 582WIDGET_RGB .......................................................................................................................... 584WIDGET_SLABEL ................................................................................................................... 586WIDGET_SLIST ........................................................................................................................ 588WIDGET_SSLIDER .................................................................................................................. 590WIDGET_STRING .................................................................................................................... 593
Contents ENVI Reference Guide
9
WIDGET_SUBSET .................................................................................................................... 595WIDGET_TOGGLE .................................................................................................................. 597UNMIX_DOIT ........................................................................................................................... 599
Index ............................................................................................................... 601
ENVI Reference Guide Contents
10
Contents ENVI Reference Guide
Chapter 1
Overview
This chapter covers the following topics:
How to Use this Reference Section . . . . . . . 12Alphabetic List of ENVI Library Routines . 16Functional List of ENVI Library Routines . 28
Common Keywords . . . . . . . . . . . . . . . . . . . 34Quick Reference of ENVI Variable Codes . 36
ENVI Reference Guide 11
12 Chapter 1: Overview
How to Use this Reference Section
All of ENVI’s routines are documented alphabetically in this chapter. A description of each routine follows its name. Beneath the general description of the routine are a number of sections that describe the syntax for the routine, its arguments (if any), its keywords (if any), and an example of using the routine. These sections are described below.
Syntax
The “Syntax” section shows the proper syntax for calling the function or procedure. The following table lists the elements used in ENVI and IDL syntax listings:
Element Description
[ ] (Square brackets) Indicates that the contents are optional. Do not include the brackets in your call.
[ ] (Italicized square brackets)
Indicates that the square brackets are part of the statement (used to define an array)
Argument Arguments are shown in italics, and you must specify them in the order listed.
KEYWORD Keywords are all caps, and you can specify them in any order. For functions, you must contain all arguments and keywords within parentheses.
/KEYWORD Indicates a Boolean keyword. Those that are already set by default are shown in the Syntax sections as [KEYWORD=0], indicating that you must explicitly disable (turn off) the default behavior.
Italics Indicates arguments, expressions, or statements for which you must provide values
{ } (Braces) • Indicates that you must choose one of the values they contain
• Encloses a list of possible values, separated by vertical lines ( | )
• Encloses useful information about a keyword
• Defines an IDL structure (this is the only case in which the braces are included in the call)
' ' (Single quotes) When using the ENVI_DOIT procedure, surround the processing routine that follows with single quotes.
[, Value1, ... , Valuen] Indicates that you can specify any number of values
[, Value1, ... , Value8] Indicates the maximum number of values that you can specify
Table 1-1: Elements of ENVI and IDL Syntax
How to Use this Reference Section ENVI Reference Guide
Chapter 1: Overview 13
Elements of Syntax
Square Brackets ( [] )
• Content between square brackets is optional. Pay close attention to the grouping of square brackets. Consider the following examples:
ROUTINE_NAME, Value1 [, Value2] [, Value3]: You must include Value1. You do not have to include Value2 or Value3. You can specify Value2 and Value3 independently.
ROUTINE_NAME, Value1 [, Value2, Value3]: You must include Value1. You do not have to include Value2 or Value3, but you must include both Value2 and Value3, or neither.
ROUTINE_NAME [, Value1 [, Value2]]: You can specify Value1 without specifying Value2, but if you specify Value2, you must also specify Value1.
• Do not include square brackets in your statement unless the brackets are italicized. Consider the following syntax:
Result = KRIG2D( Z [, X, Y] [, BOUNDS=[xmin, ymin, xmax, ymax]] )
An example of a valid statement is:
R = KRIG2D( Z, X, Y, BOUNDS=[0,0,1,1] )
• Note that when [, Value1, ... , Valuen] is listed, you can specify any number of arguments. When an explicit number is listed, as in [, Value1, ... , Value8], you can specify only as many arguments as are listed.
Braces ( {} )
• For certain keywords, a list of the possible values is provided. This list is enclosed in braces, and the choices are separated by a vertical line ( | ). Do not include the braces in your statement. For example, consider the following syntax:
READ_JPEG [, TRUE={1 | 2 | 3 }]
In this example, you must choose either 1, 2, or 3. An example of a valid statement is:
READ_JPEG, TRUE=1
• Braces are used to enclose the allowable range for a keyword value. Unless otherwise noted, provided ranges are inclusive. Consider the following syntax:
Result = CVTTOBM( Array [, THRESHOLD=value{0 to 255}] )
An example of a valid statement is:
Result = CVTTOBM( A, THRESHOLD=150 )
• Braces are also used to provide useful information about a keyword. For example:
[, LABEL=n{label every nth gridline}]
Do not include the braces or their content in your statement.
• Certain keywords are prefaced by X, Y, or Z. Braces are used for these keywords to indicate that you must choose one of the values it contains. For example, [{X | Y}RANGE=array] indicates that you can specify either XRANGE=array or YRANGE=array.
ENVI Reference Guide How to Use this Reference Section
14 Chapter 1: Overview
• Note that in ENVI and IDL, braces are used to define structures. When defining a structure, you do want to include the braces in your statement.
Italics
• Italicized words are arguments, expressions, or statements for which you must provide values. The value you provide can be a numerical value, such as 10, an expression, such as DIST(100), or a named variable. For keywords that expect a string value, the syntax is listed as KEYWORD=string. The value you provide can be a string, such as 'Hello' (enclosed in single quotation marks), or a variable that holds a string value.
Procedures
Procedures have the syntax:
PROCEDURE_NAME, Argument [, Optional_Arguments]
where PROCEDURE_NAME is the name of the procedure, Argument is a required parameter, and Optional_Argument is an optional parameter to the procedure. Note that the square brackets around optional arguments are not used in the actual call to the procedure; they are simply used to denote the optional nature of the arguments within this document.
Functions
Functions have the syntax:
Result = FUNCTION_NAME(Argument [, Optional_Arguments])
where Result is the returned value of the function, FUNCTION_NAME is the name of the function, Argument is a required parameter, and Optional_Argument is an optional parameter. Note that the square brackets around optional arguments are not used in the actual call to the function; they are simply used to denote the optional nature of the arguments within this document. Note that you should supply all arguments and keyword arguments to functions within the parentheses that follow the function’s name.
You do not always have to use functions in assignment statements (i.e., A=SIN(10.2)). You can use them just like any other IDL expression. For example, you could print the result of SIN(10.2) by entering the following command:
PRINT, SIN(10.2)
Arguments
The Arguments section describes each valid argument to the routine. Note that these arguments are positional parameters that you must supply in the order indicated by the routine’s syntax.
Named Variables
Often, arguments and keywords that contain values upon return from the function or procedure (output arguments) are described as accepting named variables. A named variable is a valid IDL variable name. You do not need to define this variable before using it as an output argument or with a keyword. Note, however, that when an argument or keyword calls for a named variable, you can only use a named variable; sending an expression causes an error.
How to Use this Reference Section ENVI Reference Guide
Chapter 1: Overview 15
Keywords
The Keywords section describes each valid keyword argument to the routine. Note that keyword arguments are formal parameters that you can supply in any order.
Supply keyword arguments to ENVI routines by including the keyword name followed by an equal sign (“=”) and the value to which the keyword should be set. For example, to set the filename to ENVI_SETUP_HEAD, set the FNAME keyword to a string containing the desired filename.
ENVI_SETUP_HEAD, FNAME='test.img'
Note that you can abbreviate keywords to their shortest unique length. However, this is not recommended, since adding a new keyword may make the abbreviation invalid.
Setting Keywords
When the documentation for a keyword says something similar to, “Set this keyword to enable logarithmic plotting,” the keyword is simply a switch that turns an option on or off. Usually, setting such keywords equal to 1 turns on the option. Explicitly setting the keyword to 0 (or not including the keyword) turns off the option.
You can use a shortcut to set a keyword equal to 1 without the usual syntax. Simply preface it with a slash character (“/”). For example, set the OPEN keyword to ENVI_SETUP_HEAD as follows:
ENVI_SETUP_HEAD, FNAME=FNAME, /OPEN
Boolean keywords that are already set by default are shown in the Syntax sections as [KEYWORD=0], indicating that you must explicitly disable (turn off) the default behavior.
Examples
Most routines have an example that demonstrates how the function or procedure is used. These code fragments are designed to serve as examples for your own programs.
ENVI Reference Guide How to Use this Reference Section
16 Chapter 1: Overview
Alphabetic List of ENVI Library Routines
The following is a list of all library routines included in ENVI, in alphabetical order.
Routine Name Description
ADAPT_FILT_DOIT Perform adaptive filtering.
AIRSAR_HEADER_DOIT Read an Airborne Synthetic Aperture Radar (AIRSAR) header.
AIRSAR_PED_HEIGHT_DOIT Calculate pedestal height images from an AIRSAR compressed stoked matrix.
AIRSAR_PHASE_IMAGE_DOIT Calculate phase images from an AIRSAR compressed stokes matrix.
AIRSAR_POLSIG_DOIT Calculate polarization signatures from an AIRSAR compressed stokes matrix.
AIRSAR_SCATTER_DOIT Calculate scatter classification for an AIRSAR compressed stokes matrix.
AIRSAR_SYNTH_DOIT Synthesize AIRSAR images.
ASPECT_DOIT Make aspect corrections to Landsat Multispectral Scanner (MSS) image data.
AUTO_WID_MNG Automatically perform event handling for ENVI compound widgets.
BAD_DATA_DOIT Remove bad data lines.
CF_DOIT Create an output file to disk or memory from bands in the Available Bands List.
CLASS_CONFUSION_DOIT Compute a classification confusion matrix.
CLASS_CS_DOIT Clump or sieve a classification image.
CLASS_DOIT Perform supervised classification.
CLASS_MAJORITY_DOIT Perform majority or minority analysis on a classification image.
CLASS_RULE_DOIT Classify rule images.
CLASS_STATS_DOIT Calculate class statistics.
COM_CLASS_DOIT Combine classes.
CONTINUUM_REMOVE_DOIT Perform Continuum Removal.
CONV_DOIT Perform convolution filtering.
Table 1-2: Alphabetic List of ENVI Routines
Alphabetic List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 17
CONVERT_DOIT Convert interleave type.
CONVERT_INPLACE_DOIT Convert in place between storage types.
CROSS_TRACK_CORRECTION_DOIT Remove variation in the cross-track illumination of an image.
DARK_SUB_DOIT Perform dark subtraction.
DECOR_DOIT Perform saturation stretch.
DEM_BAD_DATA_DOIT Correct bad data points in digital elevation models (DEMs).
DESKEW_DOIT Deskew MSS data.
DESTRIPE_DOIT Destripe image data.
DISP_GET_LOCATION Return the x,y location of a selected pixel.
DISP_GOTO Move the cursor to a specified location.
DISP_OUT_IMG Output to Postscript.
ELINE_CAL_DOIT Perform empirical line Calibration.
EMITTANCE_CALC_DOIT Convert emissivity.
ENVI Restore base ENVI save files (.sav) for batch mode.
ENVIZOOM Restore ENVI Zoom save files (.sav).
ENVI_ACE_DOIT Perform Adaptive Coherence Estimator target detection analysis.
ENVI_ADD_PROJECTION Add a projection to ENVI.
ENVI_ASSIGN_HEADER_VALUE Set user-defined header values.
ENVI_AUTO_TIE_POINTS_DOIT Automatically calculate tie points for two images, making fully automatic image registration possible.
ENVI_AVHRR_CALIBRATE_DOIT Calibrate Advanced Very High Resolution Radiometer (AVHRR) data or compute AVHRR sea surface temperature (SST).
ENVI_AVHRR_GEOMETRY_DOIT Compute the AVHRR geometry (latitude and longitude), solar zenith angles, and sensor zenith angles for each pixel.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
ENVI Reference Guide Alphabetic List of ENVI Library Routines
18 Chapter 1: Overview
ENVI_AVHRR_WARP_DOIT Warp AVHRR data or resulting AVHRR data products.
ENVI_BANDMAX_SELECT_BANDS Perform the BandMax background suppression algorithm to derive a subset of significant bands using input target and background spectra.
ENVI_BATCH_EXIT Exit ENVI from the non-menu batch mode.
ENVI_BATCH_INIT Initialize ENVI from the non-menu batch mode.
ENVI_BATCH_STATUS_WINDOW Enable and disable the ENVI batch status window.
ENVI_BUFFER_ZONE_DOIT Create a buffer zone image from a classification image.
ENVI_CAL_DOIT Spectrally calibrate images using flat field or internal average relative reflectance (IARR).
ENVI_CEM_DOIT Perform Constrained Energy Minimization target detection analysis.
ENVI_CENTER Return the centering offsets for a widget.
ENVI_CLOSE_DISPLAY Close a display group.
ENVI_CLOVER_DOIT Overlay classes.
ENVI_COLLECT_SPECTRA Perform Endmember Collection.
ENVI_COMPUTE_SUN_ANGLES Compute sun angles.
ENVI_CONVERT_FILE_COORDINATES Convert between map and pixel coordinates.
ENVI_CONVERT_FILE_MAP_PROJECTION Convert a file from its current map projection to an output projection.
ENVI_CONVERT_LIDAR_DATA_DOIT Read a light detection and ranging (LIDAR) data file in log ASCII standard (LAS) format and convert it to either an ENVI image file or an ENVI vector file (EVF).
ENVI_CONVERT_PROJECTION_COORDINATES
Convert map coordinates between projections.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
Alphabetic List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 19
ENVI_CREATE_ROI Create a new Region of Interest (ROI).
ENVI_CUBE_3D_DOIT Build a 3D image cube.
ENVI_DEFAULT_STRETCH_CREATE Return an ENVI default stretch structure.
ENVI_DEFINE_MENU_BUTTON Add buttons to the ENVI menu system automatically from a user-defined routine in a .pro or .sav file within the save_add directory.
ENVI_DEFINE_ROI Add pixels to an ROI.
ENVI_DELETE_ROIS Delete ROIs.
ENVI_DISP_QUERY Return display group information.
ENVI_DISPLAY_BANDS Display an image in a display group.
ENVI_DOIT Use this interface for all of the ENVI processing (_DOIT) routines.
ENVI_ENTER_DATA Enter an image into memory as an ENVI file.
ENVI_ENVISAT_GEOREF_DOIT Georeference Advanced Along-Track Scanning Radiometer (AATSR)-, Advanced Synthetic Aperture Radar (ASAR)-, and Medium Resolution Imaging Spectrometer (MERIS)-format Environmental Satellite (ENVISAT) data.
ENVI_EVF_CLOSE Close an EVF.
ENVI_EVF_DEFINE_ADD_RECORD Add a record to a new EVF.
ENVI_EVF_DEFINE_CLOSE Close an EVF ID for editing.
ENVI_EVF_DEFINE_INIT Create a new EVF ID.
ENVI_EVF_INFO Return information about an EVF.
ENVI_EVF_OPEN Open an EVF and return an EVF ID.
ENVI_EVF_READ_RECORD Read EVF records into an IDL variable.
ENVI_EVF_TO_SHAPEFILE Output an EVF to shapefile format.
ENVI_FILE_MNG Close or delete ENVI files.
ENVI_FILE_QUERY Return information about a data file.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
ENVI Reference Guide Alphabetic List of ENVI Library Routines
20 Chapter 1: Overview
ENVI_FILE_TYPE Translate between a file type code and description.
ENVI_FILTER_DOIT Build a Fast Fourier Transform (FFT) filter.
ENVI_FX_DOIT Perform ENVI Feature Extraction on an image. This procedure is only available if you have both ENVI and ENVI EX installed and licensed.
ENVI_GEOREF_FROM_GLT_DOIT Georeference an associated image with the geographic lookup table (GLT) file output from GLT_DOIT.
ENVI_GET_CONFIGURATION_VALUES Return the current setting for ENVI configuration items.
ENVI_GET_DATA Return spatial image data from a file.
ENVI_GET_DISPLAY_NUMBERS Return a list of display numbers.
ENVI_GET_FILE_IDS Return all file IDs for all open files.
ENVI_GET_HEADER_VALUE Return user-defined values.
ENVI_GET_IMAGE Return spatial image data from a display group.
ENVI_GET_MAP_INFO Return map information from a display group.
ENVI_GET_PATH Return the path where the current version of ENVI is installed.
ENVI_GET_PROJECTION Return projection information.
ENVI_GET_RGB_TRIPLETS Return RGB triplets for graphics color index.
ENVI_GET_ROI Return ROI pixel addresses as 1D subscripts.
ENVI_GET_ROI_DATA Return image data associated with an ROI.
ENVI_GET_ROI_DIMS_PTR Return DIMS ROI pointer for use with the DIMS variable.
ENVI_GET_ROI_IDS Return ROI IDs.
ENVI_GET_ROI_INFORMATION Return information associated with defined ROIs.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
Alphabetic List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 21
ENVI_GET_SLICE Return a spectral slice from an image.
ENVI_GET_STATISTICS Return values from an ENVI statistics file.
ENVI_GET_TILE Return one spatial or spectral tile of image data.
ENVI_GLT_DOIT Build a GLT from input geometry.
ENVI_GRID_DOIT Convert irregularly gridded points to raster image.
ENVI_GS_SHARPEN_DOIT Perform Gram-Schmidt spectral sharpening.
ENVI_ICA_DOIT Perform forward Independent Components transform.
ENVI_ICA_INV_DOIT Perform inverse Independent Components transform.
ENVI_INFO_WID Display text data in a “report” widget.
ENVI_INIT_TILE Initialize tile processing and return the tile ID.
ENVI_IO_ERROR Report input/output processing errors.
ENVI_LAYER_STACKING_DOIT Build a new multi-band file from georeferenced images of various pixel sizes, extents, and projections.
ENVI_MAP_INFO_CREATE Return map information.
ENVI_MASK_APPLY_DOIT Apply a mask to a file.
ENVI_NEURAL_NET_DOIT Perform classification using a neural net method.
ENVI_OPEN_DATA_FILE Open an external (non-ENVI) image file.
ENVI_OPEN_FILE Open an ENVI file.
ENVI_OSP_DOIT Perform Orthogonal Subspace Projection target detection analysis.
ENVI_OUTPUT_TO_EXTERNAL_FORMAT Output image data to an external (non-ENVI) format.
ENVI_PC_SHARPEN_DOIT Perform principal components spectral sharpening.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
ENVI Reference Guide Alphabetic List of ENVI Library Routines
22 Chapter 1: Overview
ENVI_PICKFILE Use this widget to select a filename from disk.
ENVI_PLOT_DATA Create an x,y plot.
ENVI_PROJ_CREATE Create ENVI projection information.
ENVI_QUERY_VERSION Return the current version of ENVI.
ENVI_RADARSAT_GEOREF_DOIT Extract embedded geolocation points from a processed Radarsat file.
ENVI_READ_COLS Read ASCII column data.
ENVI_REGISTER_DOIT Warp image data.
ENVI_REPORT_ERROR Report error message strings through the standard ENVI error reporting mechanism.
ENVI_REPORT_INC Set the status report increment.
ENVI_REPORT_INIT Initialize and end a status report.
ENVI_REPORT_STAT Update status report widget with percent complete.
ENVI_RESAMPLE_SPECTRA Spectrally resample individual spectra.
ENVI_RESTORE_ROIS Restore saved ROIs.
ENVI_ROI_TO_IMAGE_DOIT Create a classification image from ROIs.
ENVI_RXD_DOIT Perform Reed-Xiaoli anomaly detection on a multispectral or hyperspectral image.
ENVI_SAVE_ROIS Save ROIs.
ENVI_SEAWIFS_GEOMETRY_DOIT Calculate the geometry for Hierarchical Data Format (HDF) and Committee on Earth Observation Satellites (CEOS)-format Sea-viewing Wide Field-of-view Sensors (SeaWiFS) data.
ENVI_SEAWIFS_GEOREF_DOIT Georeference HDF and CEOS-format SeaWiFS data.
ENVI_SEGMENT_DOIT Segment a classification image into unique spatially contiguous “blobs.”
ENVI_SELECT Use this widget to select an open ENVI file or band.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
Alphabetic List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 23
ENVI_SENSOR_TYPE Translate between sensor type code and description.
ENVI_SET_INHERITANCE Return the ENVI inheritance structure.
ENVI_SETUP_HEAD Write an ENVI header file for an image.
ENVI_SMACC_DOIT Perform Sequential Maximum Angle Convex Cone (SMACC) processing on an input file.
ENVI_SPECTRAL_RESAMPLING_DOIT Spectrally resample image or spectral library files.
ENVI_STATS_DOIT Calculate statistics from a data file.
ENVI_SUBSPACE_BACKGROUND_STATS_DOIT
Remove anomalous pixels prior to running statistics-based spectral detection methods.
ENVI_SUM_DATA_DOIT Calculate a number of statistical parameters on a set of bands.
ENVI_SVM_DOIT Perform supervised image classification using a support vector machine (SVM).
ENVI_SYNTHETIC_COLOR_DOIT Calculate synthetic color image.
ENVI_TCIMF_DOIT Perform Target-Constrained Interference-Minimized Filter target analysis.
ENVI_TCIMF_MF_DOIT Perform Mixture Tuned Target-Constrained Interference-Minimized Filter target detection analysis.
ENVI_THERMAL_CORRECT_DOIT Perform thermal infrared atmospheric correction.
ENVI_TILE_DONE Complete tile processing.
ENVI_TOGGLE_CATCH Toggle the ENVI error catching mechanism on and off.
ENVI_TRANSLATE_PROJECTION_NAME Convert projection names.
ENVI_TRANSLATE_PROJECTION_UNITS Translate projection units.
ENVI_USER_DEFINED_ANNOTATION Create an ENVI annotation file or append items to an existing annotation file.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
ENVI Reference Guide Alphabetic List of ENVI Library Routines
24 Chapter 1: Overview
ENVI_VEG_INDEX_AVAILABLE_INDICES Determine the number of vegetation indices that you can calculate on an input data file.
ENVI_VEG_INDEX_DOIT Calculate vegetation indices from a spectral input image.
ENVI_VEG_SUPPRESS_DOIT Suppress vegetation spectral signatures.
ENVI_WRITE_COSMOSKYMED_METADATA
Write the metadata from a COSMO-SkyMed data file to XML.
ENVI_WRITE_DBF_FILE Output an EVF attribute file to DBF format.
ENVI_WRITE_ENVI_FILE Convert an IDL image array to an ENVI image.
ENVI_WRITE_FILE_HEADER Write/re-write an ENVI header file to preserve changes to user-defined header values.
ENVI_WRITE_STATISTICS Write an ENVI statistics file.
FFT_DOIT Perform FFT filtering.
FFT_INV_DOIT Apply FFT filter and perform inverse FFT.
GAINOFF_DOIT Apply gain and offset to each input band.
GEN_IMAGE_DOIT Generate test images.
HANDLE_VALUE Get and set handle values.
HIST_EXPORT_DOIT Output images using an applied lookup table (LUT).
MAGIC_MEM_CHECK Clear out the necessary memory cache for in-memory functions.
MATCH_FILTER_DOIT Perform Matched Filtering.
MATCH_FILTER_MT_DOIT Perform Mixture Tuned Matched Filtering (MTMF).
MATH_DOIT Perform Band Math.
MNF_DOIT Perform Minimum Noise Fraction (MNF) transform.
MNF_INV_DOIT Perform inverse MNF transform.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
Alphabetic List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 25
MORPH_DOIT Perform morphological filtering.
MOSAIC_DOIT Mosaic image bands or band combinations.
MUNSELL_DOIT Convert RGB image to Munsell coordinates.
MUNSELL_INV_DOIT Calculate RGB image from Munsell coordinates.
NDVI_DOIT Create a normalized difference vegetation index (NDVI).
PC_ROTATE Calculate principal components rotation.
PPI_DOIT Calculate Pixel Purity Index (PPI).
RADAR_INC_ANGLE_DOIT Calculate incidence angle image from radar.
RATIO_DOIT Calculate band ratios.
RESIZE_DOIT Spatially resize data.
RGB_GET_BANDS Display a dialog for selecting three bands from the Available Bands List.
RGB_ITRANS_DOIT Perform inverse color transform.
RGB_TRANS_DOIT Perform forward color transform.
ROC_CURVE_DOIT Calculate receiver operating characteristic (ROC) curves.
ROI_THRESH_DOIT Create a threshold ROI.
ROTATE_DOIT Rotate images.
RTV_DOIT Perform raster-to-vector conversion.
SAT_STRETCH_DOIT Perform saturation stretch.
SHARPEN_DOIT Perform image sharpening.
SIRC_HEADER_DOIT Read a Shuttle Imaging Radar-C (SIR-C) header.
SIRC_MULTILOOK_DOIT Multilook SIR-C images.
SIRC_PED_HEIGHT_DOIT Calculate pedestal height images from a SIR-C compressed data products file.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
ENVI Reference Guide Alphabetic List of ENVI Library Routines
26 Chapter 1: Overview
SIRC_PHASE_IMAGE_DOIT Calculate phase images from a SIR-C compressed data products file.
SIRC_POLSIG_DOIT Calculate polarization signatures from a SIR-C compressed data products file.
SIRC_SYNTH_DOIT Synthesize SIR-C images.
SLICE_DOIT Output a vertical or horizontal spectral slice to a file.
SLT2GND_DOIT Convert slant-to-ground range.
SPECTRAL_FEATURE_DOIT Perform Spectral Feature Fitting (SFF).
STRETCH_DOIT Perform a contrast stretch of image data.
TASCAP_DOIT Create Tasseled Cap vegetation and soil indices.
TEXTURE_COOCCUR_DOIT Calculate co-occurrence texture measures.
TEXTURE_STATS_DOIT Calculate occurrence texture measures.
TIMS_CAL_DOIT Calibrate Thermal Infrared Multispectral Scanner (TIMS) data to radiance.
TMCAL_DOIT Calibrate Landsat MSS, TM, and ETM+ data to radiance or reflectance.
TOPO_DOIT Perform topographic modeling of DEMs.
TOPO_FEATURE_DOIT Create a topographic feature classification image.
UNMIX_DOIT Perform Linear Spectral Unmixing.
VAX_IEEE_DOIT Perform VAX Institute of Electrical and Electronic Engineers (IEEE) floating-point conversion.
WIDGET_AUTO_BASE Create a base widget for auto-managed events.
WIDGET_EDIT Create a compound widget used to edit multiple values from lists.
WIDGET_GEO Create a compound widget used to specify latitude and longitude values.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
Alphabetic List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 27
NoteAll of the batch mode examples assume that the core ENVI save files (.sav) have been restored. For more information on restoring the core ENVI save files (.sav) see “Overview of Batch Mode” in the ENVI Programmer’s Guide.
WIDGET_MAP Create a compound widget that allows you to input and edit map coordinates and projections.
WIDGET_MENU Create a widget with a menu of exclusive and non-exclusive items.
WIDGET_MULTI Create a widget used to select multiple items from a list.
WIDGET_OUTF Create a menu used to select an output filename.
WIDGET_OUTFM Create a menu used to select an output filename with the option to save the result to memory.
WIDGET_PARAM Create a widget used for entering numeric parameters.
WIDGET_PMENU Create a widget with a drop-down list.
WIDGET_RGB Create a widget used to modify an RGB color value with the option of using other color space models.
WIDGET_SLABEL Create a widget used to display a text message with scroll bars.
WIDGET_SLIST Create a widget with a list.
WIDGET_SSLIDER Create a widget used to set a numeric value with a slider.
WIDGET_STRING Create a widget used to enter a text string.
WIDGET_SUBSET Create a widget with a Spatial Subset button, which displays ENVI’s Select Spatial Subset dialog.
WIDGET_TOGGLE Create a widget with a toggle button.
Routine Name Description
Table 1-2: Alphabetic List of ENVI Routines (Continued)
ENVI Reference Guide Alphabetic List of ENVI Library Routines
28 Chapter 1: Overview
Functional List of ENVI Library Routines
The following is a list of the most commonly used routines included in ENVI, categorized by functionality.
Batch Mode
File Input and Management
Routine Name Usage
ENVI Restore base ENVI save files (.sav) for batch mode.
ENVI_BATCH_EXIT Exit ENVI from the non-menu batch mode.
ENVI_BATCH_INIT Initialize ENVI from the non-menu batch mode.
ENVI_BATCH_STATUS_WINDOW Enable and disable the ENVI batch status window.
Table 1-3: Batch Mode Routines
Routine Name Usage
ENVI_FILE_MNG Close or delete ENVI files.
ENVI_GET_FILE_IDS Return all file IDs for all open files.
ENVI_GET_PATH Return the path where the current version of ENVI is installed.
ENVI_OPEN_DATA_FILE Open an external (non-ENVI) image file.
ENVI_OPEN_FILE Open an ENVI file.
ENVI_PICKFILE Use this widget to select a filename from disk.
ENVI_SELECT Use this widget to select an open ENVI file or band.
Table 1-4: File Input and Management Routines
Functional List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 29
File Information
File Output
Reading Image Data (Non-Tiled)
Routine Name Usage
ENVI_FILE_QUERY Return information about a data file.
ENVI_FILE_TYPE Translate between a file type code and description.
ENVI_SENSOR_TYPE Translate between sensor type code and description.
ENVI_SET_INHERITANCE Return the ENVI inheritance structure.
Table 1-5: File Information Routines
Routine Name Usage
CF_DOIT Create an output file to disk or memory from bands in the Available Bands List.
ENVI_ENTER_DATA Enter an image into memory as an ENVI file.
ENVI_OUTPUT_TO_EXTERNAL_FORMAT
Output image data to an external (non-ENVI) format.
ENVI_SETUP_HEAD Write an ENVI header file for an image.
SLICE_DOIT Output a vertical or horizontal spectral slice to a file.
Table 1-6: File Output Routines
Routine Name Usage
ENVI_GET_DATA Return spatial image data from a file.
ENVI_GET_IMAGE Return spatial image data from a display group.
ENVI_GET_SLICE Return a spectral slice from an image.
Table 1-7: Reading Image Data (Non-Tiled) Routines
ENVI Reference Guide Functional List of ENVI Library Routines
30 Chapter 1: Overview
ROI Processing
Tiling
Reporting
Routine Name Usage
ENVI_CREATE_ROI Create a new ROI.
ENVI_DEFINE_ROI Add pixels to an ROI.
ENVI_DELETE_ROIS Delete ROIs.
ENVI_GET_ROI Return ROI pixel addresses as 1D subscripts.
ENVI_GET_ROI_DATA Return image data associated with an ROI.
ENVI_GET_ROI_DIMS_PTR Return DIMS ROI pointer for use with the DIMS variable.
ENVI_GET_ROI_IDS Return ROI IDs.
ENVI_RESTORE_ROIS Restore saved ROIs.
ENVI_SAVE_ROIS Saves ROIs.
Table 1-8: ROI Processing Routines
Routine Name Usage
ENVI_GET_TILE Return one spatial or spectral tile of image data.
ENVI_INIT_TILE Initialize tile processing and return the tile ID.
ENVI_TILE_DONE Complete tile processing.
Table 1-9: Tiling Routines
Routine Name Usage
ENVI_REPORT_INC Set the status report increment.
ENVI_REPORT_INIT Initialize and end a status report.
ENVI_REPORT_STAT Update status report widget with percent complete.
Table 1-10: Reporting Routines
Functional List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 31
Map Information
Widgets
Routine Name Usage
ENVI_ADD_PROJECTION Add a projection to ENVI.
ENVI_AUTO_TIE_POINTS_DOIT Automatically calculate tie points for two images, making fully automatic image registration possible.
ENVI_CONVERT_FILE_COORDINATES
Convert between map and pixel coordinates.
ENVI_CONVERT_FILE_MAP_PROJECTION
Convert a file from its current map projection to an output projection.
ENVI_CONVERT_PROJECTION_COORDINATES
Convert map coordinates between projections.
ENVI_GET_PROJECTION Return projection information.
ENVI_MAP_INFO_CREATE Return map information.
ENVI_PROJ_CREATE Create ENVI projection information.
ENVI_RADARSAT_GEOREF_DOIT Extract embedded geolocation points from a processed Radarsat file.
ENVI_TRANSLATE_PROJECTION_NAME
Convert projection names.
ENVI_TRANSLATE_PROJECTION_UNITS
Translate projection units.
Table 1-11: Map Information Routines
Routine Name Usage
AUTO_WID_MNG Automatically perform event handling for ENVI compound widgets.
ENVI_CENTER Return the centering offsets for a widget.
ENVI_COLLECT_SPECTRA Perform Endmember Collection.
ENVI_DEFINE_MENU_BUTTON Add buttons to the ENVI menu system automatically from a user-defined routine in a .pro or .sav file within the save_add directory.
Table 1-12: Widget Routines
ENVI Reference Guide Functional List of ENVI Library Routines
32 Chapter 1: Overview
ENVI_INFO_WID Display text data in a “report” widget.
ENVI_PICKFILE Use this widget to select a filename from disk.
ENVI_SELECT Use this widget to select an open ENVI file or band.
RGB_GET_BANDS Display a dialog for selecting three bands from the Available Bands List.
WIDGET_AUTO_BASE Create a base widget for auto-managed events.
WIDGET_EDIT Create a compound widget used to edit multiple values from lists.
WIDGET_GEO Create a compound widget used to specify latitude and longitude values.
WIDGET_MAP Create a compound widget that allows you to input and edit map coordinates and projections.
WIDGET_MENU Create a widget with a menu of exclusive and non-exclusive items.
WIDGET_MULTI Create a widget used to select multiple items from a list.
WIDGET_OUTF Create a menu used to select an output filename.
WIDGET_OUTFM Create a menu used to select an output filename with the option to save the result to memory.
WIDGET_PARAM Create a widget used for entering numeric parameters.
WIDGET_PMENU Create a widget with a drop-down list.
WIDGET_RGB Create a widget used to modify an RGB color value with the option of using other color space models.
WIDGET_SLABEL Create a widget used to display a text message with scroll bars.
WIDGET_SLIST Create a widget with a list.
WIDGET_SSLIDER Create a widget used to set a numeric value with a slider.
WIDGET_STRING Create a widget used to enter a text string.
WIDGET_SUBSET Create a widget with a Spatial Subset button, which displays ENVI’s Select Spatial Subset dialog.
Routine Name Usage
Table 1-12: Widget Routines (Continued)
Functional List of ENVI Library Routines ENVI Reference Guide
Chapter 1: Overview 33
Image Displays
Vector Processing
WIDGET_TOGGLE Create a widget with a toggle button.
Routine Name Usage
DISP_GET_LOCATION Return the x,y location of a selected pixel.
DISP_GOTO Move the cursor to a specified location.
ENVI_CLOSE_DISPLAY Close a display group.
ENVI_DISP_QUERY Return display group information.
ENVI_DISPLAY_BANDS Display an image in a display group.
ENVI_GET_DISPLAY_NUMBERS Return a list of display numbers.
ENVI_GET_IMAGE Return spatial image data from a display group.
Table 1-13: Image Display Routines
Routine Name Usage
ENVI_EVF_CLOSE Close an EVF.
ENVI_EVF_DEFINE_ADD_RECORD
Add a record to a new EVF.
ENVI_EVF_DEFINE_CLOSE Close an EVF ID for editing.
ENVI_EVF_DEFINE_INIT Create a new EVF ID.
ENVI_EVF_INFO Return information about an EVF file.
ENVI_EVF_OPEN Open an EVF file and return an EVF ID.
ENVI_EVF_READ_RECORD Read EVF records into an IDL variable.
ENVI_EVF_TO_SHAPEFILE Output an EVF to shapefile format.
ENVI_WRITE_COSMOSKYMED_METADATA
Output an EVF attribute file to DBF format.
Table 1-14: Vector Processing Routines
Routine Name Usage
Table 1-12: Widget Routines (Continued)
ENVI Reference Guide Functional List of ENVI Library Routines
34 Chapter 1: Overview
Common Keywords
Several keywords are common to nearly every ENVI library routine. These keywords control basic file input and output for processing. Definitions for several common keywords are provided below. These keywords are mandatory in most cases, but some of them are optional for certain routines.
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).
• DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
You cannot define DIMS as a pointer to a region of interest (ROI) in any of ENVI’s _DOIT library routines. Using the following example code with a _DOIT library routine will result in an error message when you run the program:
roi_ids = ENVI_GET_ROI_IDS()roi_dims = ENVI_GET_ROI_DIMS_PTR(roi_ids[0])dims= [roi_dims,0,0,0,0]
FID
The file ID (FID) is a long-integer scalar with a value greater than 0. An invalid FID has a value of -1. The FID is provided as a named variable by one of several ENVI routines used to open or select a file. Often, the FID is returned from the keyword R_FID in the procedure ENVI_OPEN_FILE. All file processing using ENVI’s routines is accomplished by referring to its FID. If you work directly with the file in IDL, the FID is not equivalent to a logical unit number (LUN).
IN_MEMORY
Set this keyword to specify that output should be stored in memory. If you do not set IN_MEMORY, output will be stored on disk and you must specify OUT_NAME (see below).
Common Keywords ENVI Reference Guide
Chapter 1: Overview 35
M_FID
Use this keyword to specify the file ID of the mask file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. M_FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
M_POS
Use this keyword to specify the band position of the mask band. M_POS is a long integer with a value greater than or equal to 0.
OUT_BNAME
Use this keyword to specify a string array of output band names.
OUT_NAME
Use this keyword to specify a string with the output filename for the resulting data. If you set the keyword IN_MEMORY, you do not need to specify OUT_NAME.
POS
Use this keyword to specify an array of band positions, indicating the band numbers on which to perform the operation. This keyword indicates the spectral subset of bands to use in processing. POS is an array of long integers, ranging from 0 to the number of bands minus 1. Specify bands starting with zero (Band 1=0, Band 2=1, etc.) For example, to process only Bands 3 and 4 of a multi-band file, POS=[2, 3].
POS is typically used with individual files. The example code below for ENVI_STATS_DOIT illustrates the use of POS for a single file with four bands of data:
pos=[0,1,2,3]envi_doit, 'envi_stats_doit', dims=dims, fid=fid, pos=pos, $comp_flag=3, dmin=dmin, dmax=dmax, mean=mean, stdv=stdv, hist=hist
But what if you need to create an output file consisting of data from different bands, each from different files? Library routines such as CF_DOIT and ENVI_LAYER_STACKING_DOIT can accomplish this, but they use the POS keyword differently. Suppose you have four files, test1, test2, test3, and test4, with corresponding FIDs of fid1, fid2, fid3, and fid4, respectively. In the following example, you want Band 3 from test1 in the first position, Band 2 from test2 in the second position, Band 6 from test3 in the third position, and Band 4 from test4 in the fourth position. The code should be as follows:
fid_array = [fid1,fid2,fid3,fid4]pos=[2,1,5,3]envi_doit, ’cf_doit’, dims=dims, fid=fid_arrayout_name=’test_composite_file’
R_FID
ENVI library routines that result in new images also have an R_FID, or “returned FID.” This is simply a named variable containing the file ID to access the processed data. Specifying this keyword saves you the step of opening the new file from disk.
ENVI Reference Guide Common Keywords
36 Chapter 1: Overview
Quick Reference of ENVI Variable Codes
Many of the ENVI library routines use integer values (or codes) to define the state of variables, data, or images. These codes are often encountered in routines such as ENVI_FILE_QUERY, ENVI_SETUP_HEAD, ENVI_INIT_TILE, and ENVI_PROJ_CREATE, although their definitions are the same in all library routines. The following lists provide a quick reference of the codes for the most commonly used variables, including the projection type code and required parameters for defining a new projection in batch mode.
Data Type
See “Data Types” in Chapter 3 of Building IDL Applications for more details.
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
Interleave
• 0: Band sequential (BSQ)
• 1: Band interleaved by line (BIL)
• 2: Band interleaved by pixel (BIP)
Default Stretch
• 0: No stretch
• 1: Percent linear
• 2: Linear range
• 3: Gaussian
• 4: Equalize
• 5: Square foot
Quick Reference of ENVI Variable Codes ENVI Reference Guide
Chapter 1: Overview 37
Byte Swap
• 0: Data file is the same byte order as the current processor
• 1: Data file has a different byte order than the current processor
Projection Units
• 0: Meters
• 1: Kilometers
• 2: Feet
• 3: Yards
• 4: Miles
• 5: Nautical miles
• 6: Degrees
• 7: Minutes
• 8: Seconds
• 9: Radians
• 10: Acres
• 11: Hectares
• Others: Use ENVI_TRANSLATE_PROJECTION_UNITS
Projection Type
• 0: Arbitrary [no parameters required]
• 1: Geographic lat/lon [no parameters required]
• 2: UTM [zone number]
• 3: Transverse Mercator [a, b, lat0, lon0, x0, y0, k0, [datum]]
• 4: Lambert Conformal Conic [a, b, lat0, lon0, x0, y0, sp1, sp2]
• 6: Hotine Oblique Mercator B [a, b, lat0, lon0, azimuth, x0, y0, k0]
• 7: Stereographic (ellipsoid) [a, b, lat0, lon0, x0, y0, k0]
• 8: State Plane [zone number]
• 9: Albers Conical Equal Area [a, b, lat0, lon0, x0, y0, sp1, sp2]
• 10: Polyconic [a, b, lat0, lon0, x0, y0]
• 11: Lambert Azimuthal Equal Area [a, b, lat0, lon0, x0, y0]
• 12: Azimuthal Equidistant [r, lat0, lon0, x0, y0]
• 13: Gnomonic [r, lat0, lon0, x0, y0]
• 14: Orthographic [r, lat0, lon0, x0, y0]
ENVI Reference Guide Quick Reference of ENVI Variable Codes
38 Chapter 1: Overview
• 15: General Vertical Nearside Perspective [r, lat0, lon0, x0, y0, height]
• 16: Sinusoidal [r, lon0, x0, y0]
• 17: Equirectangular / Equidistant Cylindrical [r, lat0, lon0, x0, y0]
• 18: Miller Cylindrical [r, lon0, x0, y0]
• 19: Van der Griten [r, lat0, lon0, x0, y0]
• 20: Mercator [a, b, lat0, lon0, x0, y0]
• 21: Robinson [r, lon0, x0, y0]
• 25: Mollweide [r, lon0, x0, y0]
• 27: Hammer [r, lon0, x0, y0]
• 31: Polar Stereographic [a, b, lat0, lon0, x0, y0]
• 33: Equidistant Conic A [a, b, lat0, lon0, x0, y0, sp1]
• 34: Equidistant Conic B [a, b, lat0, lon0, x0, y0, sp1, sp2]
• 35: Stereographic (sphere) [r, lat0, lon0, x0, y0]
• 36: Lambert Azimuthal Equal Area (sphere) [r, lat0, lon0, x0, y0]
• 99: User Defined [a, b, lat0, lon0, x0, y0, [additional parameters] ]
Quick Reference of ENVI Variable Codes ENVI Reference Guide
Chapter 2
ENVI Routines
This chapter describes ENVI library routines in alphabetical order.
ENVI Reference Guide 39
40 Chapter 2: ENVI Routines
ADAPT_FILT_DOIT
Use this procedure to perform adaptive filtering, including the Lee filter, localized sigma filter, and bit error removal.
Syntax
ENVI_DOIT, 'ADAPT_FILT_DOIT', ADD_MEAN=floating point, [, CMAX=floating point] [, CU=floating point], DAMP=floating point, DIMS=array, FID=file ID, /IN_MEMORY, KX=integer, METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7}, MULT_MEAN=floating point, NLOOK=integer, NOISE_TYPE={0 | 1 | 2}, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, /REPLACE, SIGMA=value, TOL=value, VMAX=value, VMIN=value
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
ADD_MEAN
Use this keyword to specify a variable that contains the additive noise mean. ADD_MEAN is a floating-point number. Use this keyword only when using the Lee filter (METHOD=0) and when NOISE_TYPE=2.
CMAX (optional)Use this keyword only when using the Enhanced Lee filter (METHOD=6) or Enhanced Frost (METHOD=7). Set this keyword to a floating-point value that represents the coefficient of variation cutoff for heterogeneous areas.
CU (optional)Use this keyword only when using the Enhanced Lee filter (METHOD=6) or Enhanced Frost (METHOD=7). Set this keyword to a floating-point value that represents the coefficient of variation cutoff for homogenous areas.
ADAPT_FILT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 41
DAMP
Use this keyword to specify the filter damping factor. DAMP is a floating-point number greater than or equal to 0. If you set DAMP to 0, the filter performs like an averaging filter. Use this keyword only when using the Frost filter (METHOD=3).
KX
Use this keyword to specify a square kernel size. KX is an integer greater than or equal to 3.
METHOD
Use this keyword to specify the type of filter. Choose one of the following:
• 0: Lee
• 1: Bit error removal
• 2: Localized sigma
• 3: Frost
• 4: Gamma
• 5: Kuan
• 6: Enhanced Lee
• 7: Enhanced Frost
MULT_MEAN
Use this keyword to specify a variable that contains the multiplicative noise mean. MULT_MEAN is a floating-point number. Use this keyword only when using the Lee filter (METHOD=0) and when NOISE_TYPE=1 or 2.
NLOOK
Use this keyword to specify a variable that contains the number of looks for the data. NLOOK is an integer. Use this keyword only when using the gamma and Kuan filters, METHOD=4 and METHOD=5, respectively.
NOISE_TYPE
Use this keyword to specify the type of noise. Set NOISE_TYPE to one of the following integer values:
• 0: Additive noise
• 1: Multiplicative noise
• 2: Both
REPLACE
Set this keyword to replace bit errors with the local average. Use this keyword only when METHOD=1.
ENVI Reference Guide ADAPT_FILT_DOIT
42 Chapter 2: ENVI Routines
SIGMA
Use this keyword to specify a sigma value when METHOD=0, or a sigma factor when METHOD=1 or 2.
TOL
Use this keyword to specify the maximum standard deviation tolerance. Use only when METHOD=1.
VMAX
Use this keyword to specify the maximum value for valid data. Use only when METHOD=1.
VMIN
Use this keyword to specify the minimum value for valid data. Use only when METHOD=1.
Example
pro example_adapt_filt_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bonnrsat.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) kx = 5 sigma = .5 method = 0 mult_mean = 1. noise_type = 1 out_name = 'testimg' ; ; Call the "doit" ; envi_doit, 'adapt_filt_doit', fid=fid, pos=pos, $ dims=dims, out_name=out_name, kx=kx, sigma=sigma, $ noise_type=noise_type, mult_mean=mult_mean, $ method=method, in_memory=0 ;
ADAPT_FILT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 43
; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide ADAPT_FILT_DOIT
44 Chapter 2: ENVI Routines
AIRSAR_HEADER_DOIT
Use this procedure to read AIRSAR and TOPSAR header information used by other AIRSAR procedures. The procedure returns a value of 1 if the specified file is an AIRSAR file. Otherwise, it returns a value of 0. You can view more AIRSAR information by setting optional keywords.
Syntax
ENVI_DOIT, 'AIRSAR_HEADER_DOIT' [, BAND={0 | 1 | 2}], FILENAME=string [, GENFAC=variable], NAME=string [, NL=variable] [, NS=variable] [, OFFSET=variable]
Keywords
BAND (optional)Use this keyword to specify a named variable that contains the band number for the file specified by FILENAME. Set BAND to 0, 1, or 2 to specify C, L, or P, respectively.
FILENAME
Use this keyword to specify the filename of the AIRSAR file.
GENFAC (optional)Use this keyword to specify a named variable that contains the COMP SCALE FACTOR for the band.
NAME
Use this keyword to specify an AIRSAR filename.
NL (optional)Use this keyword to specify a named variable that contains the number of lines in the AIRSAR image.
NS (optional)Use this keyword to specify a named variable that contains the number of samples per line in the AIRSAR image.
OFFSET (optional)Use this keyword to specify a named variable that contains the offset for the file specified by FILENAME.
Example
pro example_airsar_header_doit ; ; First restore all the base save files. ;
AIRSAR_HEADER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 45
envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; filename = 'indvc.dat' ; ; Call the "doit" ; envi_doit, 'airsar_header_doit', $ filename=filename, ns=ns, nl=nl, $ offset=offset, genfac=genfac, $ band=band ; ; Print the result ; print, 'ns = ', ns print, 'nl = ', nl print, 'offset = ', offset print, 'genfac = ', genfac print, 'band = ', band ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide AIRSAR_HEADER_DOIT
46 Chapter 2: ENVI Routines
AIRSAR_PED_HEIGHT_DOIT
Use this procedure to calculate pedestal height images from an AIRSAR compressed stokes matrix.
Syntax
ENVI_DOIT, 'AIRSAR_PED_HEIGHT_DOIT', DIMS=array, FNAME=string array, FNL=integer, FNS=integer, GENFAC=array, /IN_MEMORY, OFFSET=array, OUT_BNAME=string array, OUT_NAME=string, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
FNAME
Use this keyword to specify a string array of compressed stokes matrix file names for C, L and/or P bands, respectively. If you do not use a file, set the array element to ''.
FNL
Use this keyword to specify the number of lines in the AIRSAR image.
FNS
Use this keyword to specify the number of samples per line in the AIRSAR image.
GENFAC
Use this keyword to specify an array of COMP SCALE FACTORS for each of the files specified by FNAME.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
Example
pro example_airsar_ped_height_doit ; ; First restore all the base save files.
AIRSAR_PED_HEIGHT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 47
; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = ['indvc.dat', $ 'indvl.dat', $ 'indvp.dat'] fns = 1024 fnl = 1224 out_type = 0 out_name = 'testimg' offset = [30720, 30720, 30720] genfac = [18.1776, 6.51427, 1.63261] ; ; Call the "doit" ; envi_doit, 'airsar_ped_height_doit', $ fname=fname, offset=offset, $ fns=fns, fnl=fnl, dims=dims, $ out_name=out_name, genfac=genfac, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide AIRSAR_PED_HEIGHT_DOIT
48 Chapter 2: ENVI Routines
AIRSAR_PHASE_IMAGE_DOIT
Use this procedure to calculate phase images from an AIRSAR compressed stokes matrix.
Syntax
ENVI_DOIT, 'AIRSAR_PHASE_IMAGE_DOIT' [, /DEGREES], DIMS=array, FNAME=string array, FNL=integer, FNS=integer, GENFAC=array, /IN_MEMORY, OFFSET=array, OUT_BNAME=string array, OUT_NAME=string, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
DEGREES (optional)Set this keyword to output the phase images in degrees. The default is radians.
FNAME
Use this keyword to specify a string array of compressed stokes matrix filenames for C, L or P bands. A phase image will be calculated for each element in FNAME.
FNL
Use this keyword to specify the number of lines in the AIRSAR image.
FNS
Use this keyword to specify the number of samples per line in the AIRSAR image.
GENFAC
Use this keyword to specify an array of COMP SCALE FACTORS for each of the files specified by FNAME.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
AIRSAR_PHASE_IMAGE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 49
Example
pro example_airsar_phase_image_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the input and output file names ; out_name = 'testimg' fname = ['indvc.dat', $ 'indvl.dat', $ 'indvp.dat'] ; ; Set the keywords ; fns = 1024 fnl = 1224 out_type = 0 offset = [30720, 30720, 30720] genfac = [18.1776, 6.51427, 1.63261] out_bname = ['Phase:indvc.dat', $ 'Phase:indvl.dat', $ 'Phase:indvp.dat'] ; ; Call the "doit" ; envi_doit, 'airsar_phase_image_doit', fname=fname, $ offset=offset, dims=dims, out_name=out_name, $ out_bname=out_bname, /degrees, genfac=genfac,$ in_memory=0, fns=fns, fnl=fnl, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide AIRSAR_PHASE_IMAGE_DOIT
50 Chapter 2: ENVI Routines
AIRSAR_POLSIG_DOIT
Use this procedure to calculate polarization signatures from an AIRSAR compressed stokes matrix.
Syntax
ENVI_DOIT, 'AIRSAR_POLSIG_DOIT', BANDS=array, BFNAME=string array, FNAME=string array, FNL=integer, FNS=integer, GENFAC=array, /IN_MEMORY, OFFSET=array, OUT_BNAME=string array, OUT_NAME=string, R_FID=variable, ROI_ID=array
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
BANDS
Use this keyword to specify a three-element array of ones and zeros, indicating whether you used the C, L, or P bands. A value of 1 indicates you used that band. BANDS must be three elements long, regardless of the size of FNAME.
BFNAME
Use this keyword to specify a three-element string array, where each element specifies C, L and P annotations for the header description. BFNAME must be three elements long, regardless of the size of FNAME.
FNAME
Use this keyword to specify a string array of compressed stokes matrix file names for C, L and/or P bands, respectively. If you did not use a file, set the array element to ''.
FNL
Use this keyword to specify the number of lines in the AIRSAR image.
FNS
Use this keyword to specify the number of samples per line in the AIRSAR image.
GENFAC
Use this keyword to specify an array of COMP SCALE FACTORS for each of the files specified by FNAME.
AIRSAR_POLSIG_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 51
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
ROI_ID
Use this keyword to specify an array of ROI IDs returned from a call to ENVI_GET_ROI_IDS. Each ID in the array will use the corresponding ROI to calculate both a co-polarization and cross-polarization image.
Example
forward_function envi_get_roi_ids
pro example_airsar_polsig_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = ['indvc.dat', $ 'indvl.dat', $ 'indvp.dat'] fns = 1024 fnl = 1224 out_type = 0 out_name = 'testimg' offset = [30720, 30720, 30720] genfac = [18.1776, 6.51427, 1.63261] out_bname = ['CP:indvc.stk', 'XP:indvc.stk', $ 'CP:indvl.stk', 'XP:indvl.stk', $ 'CP:indvp.stk', 'XP:indvp.stk'] ; ; Restore the presaved polsig ROI ; envi_restore_rois, 'indv.roi' roi_id = envi_get_roi_ids(ns=fns, nl=fnl) roi_id = [roi_id, roi_id, roi_id] ; ; Call the "doit" ; envi_doit, 'airsar_polsig_doit', fname=fname, $ offset=offset, roi_id=roi_id, $ out_name=out_name, out_bname=out_bname, $ genfac=genfac, in_memory=0, fns=fns, $ fnl=fnl, bands=[1,1,1], bfname=fname, $ out_type=out_type, r_fid=r_fid ; ; Exit ENVI
ENVI Reference Guide AIRSAR_POLSIG_DOIT
52 Chapter 2: ENVI Routines
; envi_batch_exitend
AIRSAR_POLSIG_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 53
AIRSAR_SCATTER_DOIT
Use this procedure to classify an AIRSAR image based on the scattering.
Syntax
ENVI_DOIT, 'AIRSAR_SCATTER_DOIT', CLASS_NAMES=string array, DIMS=array, FNAME=string array, FNL=integer, FNS=integer, GENFAC=array, /IN_MEMORY, KX=integer, KY=integer, LOOKUP=array, METHOD={0 | 1}, OFFSET=array, OUT_BNAME=string array, OUT_NAME=string, R_FID=variable, /RULE_IN_MEMORY, RULE_OUT_BNAME=string array, RULE_OUT_NAME=string, RULE_R_FID=variable, XSTART=value, YSTART=value
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
CLASS_NAMES
Use this keyword to specify names for each output class. CLASS_NAMES is an array of strings with num_classes+1 elements. Remember to set Class 0 to “Unclassified.”
FNAME
Use this keyword to specify a string array of compressed stokes matrix file names for C, L, and P bands. You must specify all bands for this function.
FNL
Use this keyword to specify the number of lines in the AIRSAR image.
FNS
Use this keyword to specify the number of samples per line in the AIRSAR image.
GENFAC
Use this keyword to specify an array of COMP SCALE FACTORS for each of the files specified by FNAME.
KX
Set this keyword to specify the x size, in pixels, of the averaging box.
ENVI Reference Guide AIRSAR_SCATTER_DOIT
54 Chapter 2: ENVI Routines
KY
Set this keyword to specify the y size, in pixels, of the averaging box.
LOOKUP
Use this keyword to specify an array of color table values for the classification image. Each output class can have a unique color triplet [r, g, b]. LOOKUP is a byte array of size (3, num_classes+1). Remember that Class 0 must also have a color triplet (commonly black [0, 0, 0]).
METHOD
Set this keyword to a value of 0 to compute scattering only. Or, set it to a value of 1 to classify the data based on the scattering mechanism. For a minimum-rule decision, the class (or band) with the smallest value becomes the selected class.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
RULE_IN_MEMORY
Set this keyword to store output rule images in memory.
RULE_OUT_BNAME
Use this keyword to specify a string array that contains the output band names for the rule image.
RULE_OUT_NAME
Use this keyword to specify an output filename for the rule image. If this item is present, the rule image is automatically saved.
RULE_R_FID
Use this keyword to specify a named variable that contains the file ID for the rule image. This file ID can be used to access the data.
XSTART
Use this keyword to specify the x offset of the input file. Set to 0 for no offset.
YSTART
Use this keyword to specify the y offset of the input file. Set to 0 for no offset.
Example
pro example_airsar_scatter_doit ; ; First restore all the base save files. ;
AIRSAR_SCATTER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 55
envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = ['indvc.dat', $ 'indvl.dat', $ 'indvp.dat'] fns = 1024 fnl = 1224 out_type = 0 out_name = 'testimg' offset = [30720, 30720, 30720] genfac = [18.1776, 6.51427, 1.63261] dims = [-1, 0, fns-1, 0, fnl-1] class_names = [$ 'Unclassified', $ 'No vegetation', $ 'Low vegetation', $ 'Dihedral Low vegetation', $ 'Forest', $ 'Dihedral Forest', $ 'Medium Vegetation', $ 'Dihedral Medium Vegetation', $ 'Urban'] lookup = [$ [ 0, 0, 0], [255, 0, 0], $ [ 0,255, 0], [ 0, 0,255], $ [255,255, 0], [255, 0, 255], $ [0, 255, 255], [128, 255, 0], $ [128, 0, 255]] ; ; Call the "doit" ; envi_doit, 'airsar_scatter_doit', $ fname=fname, offset=offset, $ fns=fns, fnl=fnl, dims=dims, $ kx=3, ky=3, class_name=class_names, $ lookup=lookup, method=1, xstart=0, $ ystart=0, out_name=out_name, $ genfac=genfac, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide AIRSAR_SCATTER_DOIT
56 Chapter 2: ENVI Routines
AIRSAR_SYNTH_DOIT
Use this procedure to synthesize an AIRSAR image from a compressed stokes matrix.
Syntax
ENVI_DOIT, 'AIRSAR_SYNTH_DOIT', COMBO=array, DIMS=array, /DO_SQRT, FNAME=string array, FNL=integer, FNS=integer, GENFAC=array, /IN_MEMORY [, MAX_VAL=value], OFFSET=array, OUT_NAME=string, OUT_DT={1 | 4}, R_FID=variable, /SIGMA_ZERO, /STDMULT, TOTAL_POWER=array, XFAC=value, YFAC=value
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
DIMS
IN_MEMORY
OUT_NAME
COMBO
Use this keyword to specify a 5 x n array of ellipticity and orientation angles for each image synthesized. The format for the array is:
• [0, i]: Transmit ellipticity for ith image
• [1, i]: Transmit orientation for ith image
• [2, i]: Receive ellipticity for ith image
• [3, i]: Receive orientation for ith image
• [4, i]: Stokes band number (0=C, 1=L, 2=P)
DO_SQRT
Set this keyword to calculate the square root of the data before converting to byte. Use this keyword when OUT_DT=1 (byte).
FNAME
Use this keyword to specify a three-element string array of compressed stokes matrix file names for C, L, and P bands, respectively. If you do not use a file, set the array element to ' '.
FNL
Use this keyword to specify the number of lines in the AIRSAR image.
FNS
Use this keyword to specify the number of samples per line in the AIRSAR image.
AIRSAR_SYNTH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 57
GENFAC
Use this keyword to specify an array of COMP SCALE FACTORS for each of the files specified by FNAME.
MAX_VAL (optional)Use this keyword to set a maximum value for output data.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 4: Floating-point (32 bits)
R_FID
Use this keyword to specify a named variable that contains the file ID for the processed data. You can use this file ID to access the processed data.
SIGMA_ZERO
Set this keyword to convert the output values to sigma zero, 10*log10(data).
STDMULT
Set this keyword to specify the standard deviation multiplier for byte output data types. Plus and minus the STDMULT determines the output minimum and maximum.
TOTAL_POWER
Use this keyword to specify a three-element array of ones and zeros indicating whether the total power should be computed for the C, L, and P bands. A value of 1 causes the synthesis of the total power image.
XFAC
Use this keyword to specify an x subsampling factor used to compute image data statistics prior to the conversion to byte. Use this keyword when OUT_DT=1 (byte).
YFAC
Use this keyword to specify a y subsampling factor used to compute image data statistics prior to the conversion to byte. Use this keyword when OUT_DT=1 (byte).
Example
pro example_airsar_synth_doit
ENVI Reference Guide AIRSAR_SYNTH_DOIT
58 Chapter 2: ENVI Routines
; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = ['indvc.dat', $ 'indvl.dat', $ 'indvp.dat'] fns = 1024 fnl = 1224 out_type = 0 out_name = 'testimg' offset = [30720, 30720, 30720] genfac = [18.1776, 6.51427, 1.63261] dims = [-1, 0, fns-1, 0, fnl-1] combo = [[0.,0.,0.,0.,0], $ [0.,0.,0.,0.,1], $ [0.,0.,0.,0.,2]] total_power = lonarr(3) + 1 ; ; Call the "doit" ; envi_doit, 'airsar_synth_doit', $ fname=fname, offset=offset, $ fns=fns, fnl=fnl, dims=dims, $ combo=combo, out_name=out_name, $ total_power=total_power, out_dt=4, $ genfac=genfac, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
AIRSAR_SYNTH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 59
ASPECT_DOIT
Use this procedure to make aspect corrections to Landsat MSS image data.
Syntax
ENVI_DOIT, 'ASPECT_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for a definition of these keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
Example
pro example_aspect_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; aspect correction on all samples ; and bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb)
ENVI Reference Guide ASPECT_DOIT
60 Chapter 2: ENVI Routines
out_name = 'testimg' ; ; Perform the aspect correction ; envi_doit, 'aspect_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ASPECT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 61
AUTO_WID_MNG
Use this function to automatically perform event handling of ENVI compound widgets, without the need to write an event-handling procedure. The function returns an anonymous structure whose tag names are defined by the user values (UVALUE) of the widgets being managed. AUTO_WID_MNG automatically creates OK and Cancel buttons on the widget unless you set the optional keyword NO_BUTTONS. In all cases, if you click OK, the field result.accept (where result is the name of the structure returned by AUTO_WID_MNG) is set to 1. Otherwise, if you click Cancel, then result.accept is set to 0.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
Result = AUTO_WID_MNG(Base [, COLUMN_BASE=widget ID] [, /NO_BUTTONS])
Arguments
Base
This is the widget ID of the base widget.
Keywords
COLUMN_BASE (optional)Set this keyword to the widget ID of the base that will hold the Accept and Cancel buttons. The default is to use the base widget specified by the Base argument.
NO_BUTTONS (optional)Set this keyword to cause the widget to exit on the first event.
ENVI Reference Guide AUTO_WID_MNG
62 Chapter 2: ENVI Routines
BAD_DATA_DOIT
Use this procedure to remove bad data lines from an image by averaging adjacent lines.
Syntax
ENVI_DOIT, 'BAD_DATA_DOIT', BAD_LINES=array, DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, WIDTH=integer
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
BAD_LINES
Use this keyword to specify an array of line numbers to replace. Note that line numbers start with 0. BAD_LINES is an array of long integers.
WIDTH
Use this keyword to specify how many lines above and below the bad line to use in averaging. The total number of lines averaged is 2 * WIDTH. This keyword is a long integer greater than or equal to 1.
Example
pro example_bad_data_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file
BAD_DATA_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 63
; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; aspect correction on all samples ; and bands in the file. We will ; correct lines 100, 120 and 167 ; for bad data (these lines actually ; contain valid data but are being ; used for the example). ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' bad_lines = [100L, 120, 167] ; ; Perform the bad data correction. ; Use a width of one to correct ; for the bad lines. ; envi_doit, 'bad_data_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, width=1, $ bad_lines=bad_lines, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide BAD_DATA_DOIT
64 Chapter 2: ENVI Routines
CF_DOIT
Use this routine to create a new ENVI-format file from existing ENVI files. The images that are incorporated into the new file can be any combination of open ENVI files on disk or in memory, and you can save the resulting file to disk or memory. CF_DOIT is equivalent to selecting File Save File As ENVI Standard from the ENVI main menu bar.
Syntax
ENVI_DOIT, 'CF_DOIT', DIMS=array, FID=array of file IDs, /IN_MEMORY, OUT_BNAME=string array, OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}, OUT_NAME=string, POS =array, /REMOVE, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
FID
Use this keyword to specify a 1D array (vector) of file IDs.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
CF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 65
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
REMOVE
Set this keyword to delete input files that are completely contained in the new output file from either disk or memory. WARNING: use this keyword with great caution; files deleted in this manner cannot be restored.
Example
pro example_cf_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords ; envi_file_query, fid, dims=dims, nb=nb t_fid = lonarr(nb) + fid pos = lindgen(nb) out_name = 'testimg' ; ; Create the new output file. Do not ; remove the input file after the ; new file has been created. ; envi_doit, 'cf_doit', $ fid=t_fid, pos=pos, dims=dims, $ remove=0, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide CF_DOIT
66 Chapter 2: ENVI Routines
CLASS_CONFUSION_DOIT
Use this procedure to compute the confusion matrix, commission, omission, accuracy, and kappa coefficient, between a classification image and its ground truth. You can specify ground truth as a classification image using the GTFID keyword, or as an ROI using the ROI_IDS keyword.
Syntax
ENVI_DOIT, 'CLASS_CONFUSION_DOIT' [, ACCURACY=variable], CALC_PERCENT={0 | 1 | 2} | CFID=file ID, CLASS_PTR=value [, COMMISSION=variable], CPOS=array, DIMS=array, GT_NAMES=array, GT_PTR=value, GTDIMS=array, GTFID=file ID, GTPOS=integer [, KAPPA_COEFF=variable] [, MATRIX=variable] [, OMISSION=variable], ROI_IDS=variable [, /RPT_COMMISSION] [, RULE_OUT_BNAME=string array] [, RULE_OUT_NAME=string] [, /RULE_IN_MEMORY] [, /TO_SCREEN]
Keywords
ACCURACY (optional)
Use this keyword to specify a named variable that contains the accuracy between the classification image and the ground truth.
CALC_PERCENT
Set this keyword to one of the following values to specify units for the confusion matrix:
• 0: Output the confusion matrix in pixel counts
• 1: Output the confusion matrix in percent
• 2: Output both types of confusion matrix
CFID
Use this keyword to specify the file ID of the classification file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. CFID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
CLASS_PTR
Use this keyword to specify which classes in the classification image match the ground truth ROIs or the ground truth classes specified by GT_PTR. The number of elements of CLASS_PTR must equal the number of ROIs when using ROIs, or the number of elements of CLASS_PTR must equal the number of elements of GT_PTR when using a ground truth classification image.
COMMISSION (optional)
Use this keyword to specify a named variable that contains the commission array between the classification image and the ground truth.
CLASS_CONFUSION_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 67
CPOS
Use this keyword to specify an array of band positions for the classification image, indicating the band numbers on which to perform the operation. CPOS is an array of long integers, ranging from 0 to the number of bands minus 1.
DIMS
See “Common Keywords” on page 34 for the definition of this keyword.
GT_NAMES
Use this keyword to specify names for each ground truth class. GT_NAMES is an array of strings with the same number of elements as GT_PTR or ROI_IDS, depending on which type of ground truth you use.
GT_PTR
Use this keyword to specify which classes in the ground truth image match the classification classes. You do not need this keyword if you use ROIs for ground truth. The number of elements of GT_PTR must equal the number of elements of CLASS_PTR.
GTDIMS
Use this keyword to specify the spatial dimensions of the ground truth image on which to perform the operation. This keyword is not needed if you use ROIs for ground truth. GTDIMS is a five-element array of long integers with the following definitions:
• DIMS[0]: Unused for this function, set to -1
• DIMS[1]: The starting x pixel (0)
• DIMS[2]: The ending x pixel
• DIMS[3]: The starting y pixel (0)
• DIMS[4]: The ending y pixel
Note that the dimensions you specify must be within the classification image, including the first pixel offsets.
GTFID
Use this keyword to specify the file ID of the ground truth file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. GTFID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
GTPOS
Use this keyword to specify the band position for the ground truth image band, indicating the band numbers on which to perform the operation. You do not need this keyword if you use ROIs for ground truth. GTPOS is an array of long integers, ranging from 0 to the number of bands minus 1.
ENVI Reference Guide CLASS_CONFUSION_DOIT
68 Chapter 2: ENVI Routines
KAPPA_COEFF (optional)
Use this keyword to specify a named variable that contains the kappa coefficient between the classification image and the ground truth.
MATRIX (optional)
Use this keyword to specify a named variable that contains the confusion matrix (in pixel counts) between the classification image and the ground truth.
OMISSION (optional)
Use this keyword to specify a named variable that contains the omission array between the classification image and the ground truth.
ROI_IDS
Use this keyword to specify the ROI IDs for the ground truth. This keyword is not needed if you use a ground truth image. Use the keyword GTFID in this case. The number of ROI_IDS must be equal to the number of elements in the CLASS_PTR array.
RPT_COMMISSION (optional)
Set this keyword to report the commission to the screen.
RULE_OUT_BNAME (optional)
Use this keyword to specify a string array that contains the output band names for the rule image.
RULE_OUT_NAME (optional)
Use this keyword to specify an output filename for the rule image. If this item is present, the rule image is automatically saved.
RULE_IN_MEMORY (optional)
Set this keyword to store output rule images in memory.
TO_SCREEN (optional)
Set this keyword to report the confusion matrix to the screen.
Example
forward_function envi_get_roi_idspro example_class_confusion_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file
CLASS_CONFUSION_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 69
; envi_open_file, 'bhtm_class', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Restore the ground truth ROIs ; envi_restore_rois, 'bhtm_nd.roi' roi_ids = envi_get_roi_ids(fid=fid) ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, nb=nb, $ num_classes=num_classes pos = [0] out_name = 'testimg' class_ptr = lindgen(n_elements(roi_ids)) + 1 ; ; Call the doit ; envi_doit, 'class_confusion_doit', $ cfid=fid, cpos=pos, dims=dims, $ roi_ids=roi_ids, class_ptr=class_ptr, $ /rpt_commission, to_screen=0, $ calc_percent=0, commission=commission, $ omission=omission, matrix=matrix, $ kappa_coeff=kappa_coeff, accuracy=accuracy ; print, commission print, omission print, matrix print, kappa_coeff print, accuracy ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide CLASS_CONFUSION_DOIT
70 Chapter 2: ENVI Routines
CLASS_CS_DOIT
Use this procedure to clump or sieve a classification image. The sieve operation uses a blob technique to eliminate all blobs smaller than SIEVE_MIN. The clump process uses the morphological operators dilate and erode.
Syntax
ENVI_DOIT, 'CLASS_CS_DOIT', DIMS=array, DKERN=value, /EIGHT, EKERN=value, FID=file ID, /IN_MEMORY, METHOD={0 | 1}, ORDER=value, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, SIEVE_MIN=value
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
DKERN
Use only with the clump method. This is the dilate kernel used for the classification clump. This kernel is passed to the IDL morphology procedures.
EIGHT
Use only with the sieve method. If you set this keyword, the sieve function searches the eight-neighbor region around a pixel, rather than the four-neighbor region, for continuous blobs. The four-neighbor region around a pixel consists of two adjacent horizontal and two adjacent vertical neighbors. The eight-neighbor region around a pixel consists of all the immediately adjacent pixels.
EKERN
Use only with the clump method. This is the erode kernel used for the classification clump. This kernel is passed to the IDL morphology routines.
METHOD
Set this keyword to a value of 0 to use the clump method, or to 1 to use the sieve method.
CLASS_CS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 71
ORDER
Use this keyword to specify the order in which clump or sieve is applied to the classification image. If you do not specify this keyword, the classes are processed from first to last.
SIEVE_MIN
Use only with the sieve method. Use this keyword to specify the minimum size of a blob to keep. All blobs smaller than this value will be removed. Set the EIGHT keyword to specify the pixel neighbors from which to build blobs.
Example
pro example_class_cs_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtm_sam.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, $ num_classes=num_classes pos = [0] out_name = 'testimg' dkern = bytarr(3,3) + 1b ekern = dkern order = bindgen(num_classes) ; ; Call the doit ; envi_doit, 'class_cs_doit', fid=fid, $ pos=pos, dims=dims, order=order, $ dkern=dkern, ekern=ekern, method=0, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide CLASS_CS_DOIT
72 Chapter 2: ENVI Routines
CLASS_DOIT
Use this procedure to perform supervised classification using the parallelepiped, minimum distance, maximum likelihood, Spectral Angle Mapper (SAM), Spectral Information Divergence (SID), Mahalanobis, or Binary Encoding methods, or unsupervised classification using ISODATA or K-Means. All classification methods use a combination of common keywords and those for specific classification methods. The METHOD keyword is used to select the supervised or unsupervised classification technique.
Syntax
ENVI_DOIT, 'CLASS_DOIT', CLASS_NAMES=string array, DIMS=array, FID=file ID, /IN_MEMORY, LOOKUP=array [, M_FID=file ID] [, M_POS=value], METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8} [, OUT_BNAME=string], OUT_NAME=string, POS=array [, R_FID=variable]
Keywords for any supervised classification method:
MEAN=array [, RULE_FID=file ID] [, /RULE_IN_MEMORY] [, RULE_OUT_BNAME=string array] [, RULE_OUT_NAME=string]
Keywords for parallelepiped classification:
STDV=array [, STD_MULT=value]
Keywords for minimum distance classification:
[, DATA_SCALE=floating point], STDV=array [, STD_MULT=value] [, THRESH=value]
Keywords for maximum likelihood classification:
COV=array, DATA_SCALE=floating point, STDV=array [, THRESH=value]
Keywords for SAM classification:
[, THRESH=value]
Keywords for SID classification:
[, THRESH=value]
Keywords for Mahalanobis classification:
COV=array, NPTS=value [, THRESH=value]
Keywords for Binary Encoding classification:
[, THRESH=value]
Keywords for any unsupervised classification method:
ITERATIONS=integer [, ITERATIONS=value] [, THRESH=value]
Keywords for K-Means classification:
CHANGE_THRESH=floating point{0.0 to 1.0}, NUM_CLASSES=integer
CLASS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 73
Keywords for ISODATA classification:
CHANGE_THRESH=floating point{0.0 to 1.0}, ISO_MERGE_DIST=floating point, ISO_MERGE_PAIRS=value, ISO_MIN_PIXELS=value, ISO_SPLIT_SMULT=floating point, ISO_SPLIT_STD=floating point, MIN_CLASSES=integer, NUM_CLASSES=integer
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY
M_FID (optional)
M_POS (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
CLASS_NAMES
Use this keyword to specify names for each output class for the supervised classification methods (the unsupervised methods generate their own CLASS_NAMES based on the color of the class). CLASS_NAMES is an array of strings with num_classes+1 elements. The first element (Class 0) is “Unclassified.” The order of the other classes is determined by the order of the classification data specified in the keyword MEAN.
LOOKUP
Use this keyword to specify an array of long integers representing class RGB values for the supervised methods only (the unsupervised methods generate their own LOOKUP based on the number of output classes). The LOOKUP array contains an RGB triplet for the “Unclassified” class plus one RGB triplet for each output class. The “Unclassified” class typically uses the RGB triplet [0, 0, 0] for black. The dimensions of the array are [3, num_classes+1], and the RGB triplet is ordered [r, g , b]. LOOKUP[*, 0] is the “Unclassified” class, and the order of the other classes is determined by the order of the classification data in keyword MEAN.
METHOD
Set this keyword equal to one of the following values to specify the classification method:
• 0: Parallelepiped (supervised)
• 1: Minimum distance (supervised)
ENVI Reference Guide CLASS_DOIT
74 Chapter 2: ENVI Routines
• 2: Maximum likelihood (supervised)
• 3: SAM (supervised)
• 4: ISODATA (unsupervised)
• 5: Mahalanobis (supervised)
• 6: Binary Encoding (supervised)
• 7: K-Means (unsupervised)
• 8: SID (supervised)
OUT_BNAME (optional)
Use this keyword to specify an output band name for the classification image. OUT_BNAME is a single string value.
Keywords for Supervised Classification
The following keywords can be used with any of the supervised classification methods (parallelepiped, minimum distance, maximum likelihood, Mahalanobis, SAM, and Binary Encoding):
MEAN
Use this keyword to specify the mean spectral values for each class when performing supervised classification. MEAN is a floating-point or double-precision array of [num_bands, num_classes] values. The spectral mean of each class (for supervised methods) is commonly computed from the spectral mean of the ROI representing the training region of the class. The actual number of output classes, NUM_CLASSES, is computed from the number of spectral means plus one for the Unclassified class.
NoteFor the unsupervised methods of ISODATA and K-Means, the initial starting classes are calculated automatically from the mean on the input data and do not require the MEAN keyword.
RULE_FID (optional)
Use this keyword to specify a named variable that contains the file ID for the processed rule image. This file ID can be used to access the processed data.
RULE_IN_MEMORY (optional)
Set this keyword to store output rule images in memory.
RULE_OUT_BNAME (optional)
Use this keyword to specify a string array that contains the output band names for the rule image.
RULE_OUT_NAME (optional)
Use this keyword to specify an output filename for the rule image. If this item is present, the rule image is automatically saved.
CLASS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 75
Keywords for Parallelepiped Classification
STDV
Use this keyword to specify a floating-point or double-precision array with the dimensions [num_bands, num_classes] containing the standard deviation for each of the spectral classes.
STD_MULT (optional)
Use this keyword to specify a floating-point or double-precision multiplication factor or array of factors (one for each class) specifying the width around the standard deviation within which the spectrum may fall and still be classified into that class. If you specify an array, each class is tested with its corresponding width. The default value is 1.0.
Keywords for Minimum Distance Classification
DATA_SCALE (optional)
Use this keyword to specify a floating-point value representing the data scale factor. The scale factor is a division factor used to convert integer scaled reflectance or radiance data into floating-point values. For example, for reflectance data scaled into the range of 0 to 10,000, set the scale factor to 10,000. For uncalibrated integer data, set the scale factor to the maximum value the instrument can measure ((2n) - 1, where n is the bit depth of the instrument). Set the scale factor to 255 for 8-bit instruments (such as Landsat-4), set the scale factor to 1023 for 10-bit instruments (such as NOAA-12 AVHRR), and set the scale factor to 2047 for 11-bit instruments (such as IKONOS).
STDV
Use this keyword to specify a floating-point or double-precision array with dimensions [num_bands, num_classes], containing the standard deviation for each of the spectral classes. You must specify this value if you specify STD_MULT.
STD_MULT (optional)
Use this keyword to specify a floating-point or double-precision multiplication factor or array of factors (one for each class) specifying the width around the standard deviation within which the spectrum may fall and still be classified into that class. If you specify an array, each class is tested with its corresponding width. If you use STD_MULT, you must set the keyword STDV. The default value is 1.0.
THRESH (optional)
Use this keyword to specify a floating-point or double-precision maximum distance error or array of errors (one for each class) by which a spectral value can differ from the mean value. If you specify an array, each class is tested against its corresponding error. When you specify a single value, THRESH is applied class-by-class, not as the total error.
ENVI Reference Guide CLASS_DOIT
76 Chapter 2: ENVI Routines
Keywords for Maximum Likelihood Classification
COV
Use this keyword to specify a floating-point or double-precision array with dimensions [num_bands, num_bands, num_classes] containing the covariance of the classification spectrum used.
DATA_SCALE
Use this keyword to specify a floating-point value representing the data scale factor. The scale factor is a division factor used to convert integer scaled reflectance or radiance data into floating-point values. For example, for reflectance data scaled into the range of 0 to 10,000, set the scale factor to 10,000. For uncalibrated integer data, set the scale factor to the maximum value the instrument can measure ((2n) - 1, where n is the bit depth of the instrument). Set the scale factor to 255 for 8-bit instruments (such as Landsat-4), set the scale factor to 1023 for 10-bit instruments (such as NOAA-12 AVHRR), and set the scale factor to 2047 for 11-bit instruments (such as IKONOS).
STDV
Use this keyword to specify a floating-point or double-precision array with dimensions [num_bands, num_classes] containing the standard deviation for each of the spectral classes.
THRESH (optional)
Use this keyword to specify a floating-point or double-precision minimum probability or array of probabilities (one for each class) that a class must have in order to be classified. Specify a value from 0 to 1. If an array is specified, each class is tested against its corresponding probability.
Keywords for SAM Classification
THRESH (optional)
Use this keyword to specify a floating-point or double-precision maximum angle or array of maximum angles (one for each class) in radians, to classify. If you specify an array, each class is tested against its corresponding maximum spectral angle. THRESH should have a value between 0 and /2. The default value is /2.
Keywords for SID Classification
THRESH (optional)
Use this keyword to specify a floating-point or double-precision maximum value or array of maximum values (one for each class). If you specify an array, each class is tested against its corresponding maximum spectral divergence. The default value is .05, but can vary substantially given the nature of this similarity measure. SID is based upon a dimensionless metric involving the logarithm of a ratio of probabilities based upon each spectral vector. Therefore, a threshold that discriminates well for one pair of spectral vectors may be either too sensitive or not sensitive enough for another pair due to the similar/dissimilar nature of their probability distributions.
CLASS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 77
Keywords for Mahalanobis
COV
Use this keyword to specify a floating-point or double-precision array with dimensions [num_bands, num_bands, num_classes] containing the covariance of the classification spectrum used.
NPTS
Use this keyword to specify an array of long integers representing the number of points in each ROI, with one element per ROI. Use the ENVI_GET_ROI_INFORMATION routine to return the number of points in each ROI.
THRESH (optional)
Use this keyword to specify a floating-point or double-precision maximum distance error or array of errors (one for each class) by which a spectral value can differ from the mean value. If you specify an array, each class is tested against its corresponding error. When you specify a single value, THRESH is applied class-by-class, not as the total error.
Keywords for Binary Encoding
THRESH (optional)
Use this keyword to specify a floating-point or double-precision minimum match percent or array of minimum match percents (one for each class). The value of THRESH is between 0.0 and 1.0, ranging from 0% to 100%. If you specify an array, each class is tested against its corresponding minimum match percent. For example, a value of 1.0 means that all bands must match the Binary Encoding, and a value of 0.4 means that at least 40% of the bands must match.
Keywords for Unsupervised Classification
You can use the following keywords with any of the unsupervised classification methods (K-Means and ISODATA):
ITERATIONS
Use this keyword to specify the maximum iteration count.
STD_MULT (optional)
Use this keyword to specify a floating-point multiplication factor specifying the width around the standard deviation within which a spectrum may fall and still be classified into that class. The default value is 1.0.
THRESH (optional)
Use this keyword to specify the maximum distance error by which a spectral value can differ from a mean value. The THRESH value is applied band by band, not as the total error.
ENVI Reference Guide CLASS_DOIT
78 Chapter 2: ENVI Routines
Keywords for K-Means
CHANGE_THRESH
Set this keyword to a floating-point number between 0.0 and 1.0 to specify the percentage of pixels that can change classes during each iteration. If this value is greater than the CHANGE_THRESH value, another iteration is performed, provided that it does not exceed the maximum number of iterations. If the percentage is less then the threshold, the classification is complete. A value of 1.0 means 100%.
NUM_CLASSES
Use this keyword to specify the desired number of output classes.
Keywords for ISODATA
CHANGE_THRESH
Set this keyword to a floating-point number between 0.0 and 1.0 to specify the percentage of pixels that can change classes during each iteration. If this value is greater than the CHANGE_THRESH value, another iteration is performed, provided that it does not exceed the maximum number of iterations. If the percentage is less then the threshold, the classification is complete. A value of 1.0 means 100%.
ISO_MERGE_DIST
Set this keyword to a floating-point number greater than 0.0 to specify the class merge distance (in DN). If the distance between class means is less than ISO_MERGE_DIST, the classes will be merged. The maximum number of pairs merged in any loop is determined by ISO_MERGE_PAIRS.
ISO_MERGE_PAIRS
Set this keyword to a long-integer value to specify the maximum number of classes that can be merged in a single iteration.
ISO_MIN_PIXELS
Set this keyword to a long-integer value to specify the minimum number of pixels needed to form a class. If there are few pixels in the class, that class will be deleted.
ISO_SPLIT_SMULT
Set this keyword to a floating-point number greater than 0.0 to specify the standard deviation multiplier used to calculate the mean of split classes. The new means are calculated as follows:
class_1_mean = class_mean + ISO_SPLIT_STD * current_stdvclass_2_mean = class_mean - ISO_SPLIT_STD * current_stdv
The default value is 1.0.
CLASS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 79
ISO_SPLIT_STD
Set this keyword to a floating-point number greater than 0.0 to specify the minimum class standard deviation value (in DN). If a class standard deviation is greater than ISO_SPLIT_STD, the class is split into two classes.
MIN_CLASSES
Use this keyword to specify an integer value of the desired minimum number of output classes.
NUM_CLASSES
Use this keyword to specify an integer value of the desired maximum number of output classes.
Example
This example performs a Spectral Information Divergence (SID) supervised classification in batch mode using ROIs previously saved to an ROI file. The procedure ENVI_STATS_DOIT is used to calculate the ROI mean, standard deviation, and covariance. The class names and colors come from the ROI names and colors, respectively.
This example uses the following files on the ENVI Resource DVD that shipped with your software:
• Data/c95avsub/cup95mnf.dat
• Data/c95avsub/cup95mnf.hdr
• Data/c95avsub/cup95ndv.roi
forward_function envi_get_roi_ids, envi_get_roi_dims_ptrpro example_class_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'cup95mnf.dat', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Get the spatial dimensions and # of bands ; for the input file. ; envi_file_query, fid, dims=dims, nb=nb
ENVI Reference Guide CLASS_DOIT
80 Chapter 2: ENVI Routines
; ; Set the POS to classify all ; data (spectrally) in the file. ; pos = lindgen(nb) out_name = 'testimg' ; ; Restore the pre saved regions of interest. ; Set the class names equal to the roi ; names and use the roi colors as the ; class colors. ; envi_restore_rois, 'cup95ndv.roi' roi_ids = envi_get_roi_ids(fid=fid, $ roi_colors=roi_colors, roi_names=class_names) class_names = ['Unclassified', class_names] num_classes = n_elements(roi_ids) lookup = bytarr(3, num_classes + 1) ; Set the unclassified class to black and use roi colors lookup = bytarr(3,num_classes+1) lookup[0,1] = roi_colors ; ; Calculate the statistics from each region of interest. ; Each ROI specifies the training area for each class. ; The calculated MEAN will be passed to the ; classifcation routine. ; mean = fltarr(n_elements(pos), num_classes) for j=0, num_classes-1 do begin ; get the statistics for each selected class roi_dims=[envi_get_roi_dims_ptr(roi_ids[j]),0,0,0,0] envi_doit, 'envi_stats_doit', fid=fid, pos=pos, $ dims=roi_dims, comp_flag=4, mean=c_mean mean[0,j] = c_mean endfor ; ; Calculate the Spectral Information Divergence (SID) supervised ; classification. ; thresh=replicate(0.05,num_classes) envi_doit, 'class_doit', fid=fid, pos=pos, dims=dims, $ out_bname='SID', out_name=out_name, method=8, $ mean=mean, r_fid=r_fid, $ lookup=lookup, class_names=class_names, $ in_memory=0, thresh=thresh ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_NEURAL_NET_DOITENVI_SVM_DOIT
CLASS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 81
CLASS_MAJORITY_DOIT
Use this procedure to perform majority or minority analysis on a classification image. The keyword CLASS_PTR determines which classes to modify during processing.
Syntax
ENVI_DOIT, 'CLASS_MAJORITY_DOIT', CLASS_PTR=array, DIMS=array, FID=file ID, /IN_MEMORY, KERNEL_SIZE=array, METHOD={0 | 1}, OUT_BNAME=array, OUT_NAME=string, POS=array [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID (optional)
CLASS_PTR
Use this keyword to specify an array of long integers representing class numbers on which to perform analysis.
KERNEL_SIZE
Use this keyword to specify a kernel size for the majority and minority analysis. KERNEL_SIZE is a two-element array specifying the x and y kernel size, respectively.
METHOD
Set this keyword to a value of 0 to perform majority analysis, and to 1 to perform minority analysis.
Example
pro example_class_majority_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors
ENVI Reference Guide CLASS_MAJORITY_DOIT
82 Chapter 2: ENVI Routines
; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtm_sam.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, nb=nb, $ num_classes=num_classes pos = [0] out_name = 'testimg' method = 0 kernel_size = [5,5] class_ptr = lindgen(num_classes) + 1 ; ; Call the doit ; envi_doit, 'class_majority_doit', fid=fid, $ pos=pos, dims=dims, method=method, $ kernel_size=kernel_size, out_name=out_name, $ class_ptr=class_ptr ; ; Exit ENVI ; envi_batch_exitend
See Also
CLASS_CS_DOITCLASS_DOIT
CLASS_MAJORITY_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 83
CLASS_RULE_DOIT
Use this procedure to classify rule images.
Syntax
ENVI_DOIT, 'CLASS_RULE_DOIT', CLASS_NAMES=string array, DIMS=array, FID=file ID, /IN_MEMORY, LOOKUP=array, METHOD={0 | 1}, OUT_NAME=string, POS=array, R_FID=variable [, THRESH=value]
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
POS
R_FID
CLASS_NAMES
Use this keyword to specify names for each output class. CLASS_NAMES is an array of strings with num_classes+1 elements. Remember to set Class 0 to “Unclassified.”
LOOKUP
Use this keyword to specify an array of long integers representing class RGB values for the supervised methods only (the unsupervised methods generate their own LOOKUP based on the number of output classes). The LOOKUP array contains an RGB triplet for the “Unclassified” class plus one RGB triplet for each output class. The “Unclassified” class typically uses the RGB triplet [0, 0, 0] for black. The dimensions of the array are [3, num_classes+1], and the RGB triplet is ordered [r, g , b]. LOOKUP[*, 0] is the “Unclassified” class, and the order of the other classes is determined by the order of the classification data in keyword MEAN.
METHOD
Set this keyword to a value of 0 to perform a minimum rule decision, whereby the class (or band) with the smallest value becomes the selected class. Or, set METHOD to 1 to perform a maximum rule decision.
ENVI Reference Guide CLASS_RULE_DOIT
84 Chapter 2: ENVI Routines
THRESH (optional)
Use this keyword to specify an optional minimum (METHOD=0) or maximum (METHOD=1) threshold for classifying the rule image. If you do not specify a threshold, the entire image will be classified.
Example
pro example_class_rule_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtm_rul.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, nb=nb, bnames=bnames pos = lindgen(nb) out_name = 'testimg' class_names = ['Unclassified', bnames] ; ; Build the lookup table ; lookup = bytarr(3,nb+1) for i=1,nb do begin envi_get_rgb_triplets, i+1, r, g, b lookup[0,i] = [r,g,b] endfor ; ; Call the doit ; envi_doit, 'class_rule_doit', $ fid=fid, pos=pos, dims=dims, $ lookup=lookup, method=0, $ class_names=class_names, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
CLASS_RULE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 85
CLASS_STATS_DOIT
Use this procedure to calculate statistics for images based on a classification mask.
Syntax
ENVI_DOIT, 'CLASS_STATS_DOIT', CLASS_DIMS=array, CLASS_FID=file ID, CLASS_PTR=array, COMP_FLAG={0 | 1 | 2} [, COV=variable] [, DMAX=variable] [, DMIN=variable] [, EVAL=variable] [, EVEC=variable], FID=file ID [, HIST=variable] [, MEAN=variable], POS=array [, REP_NAME=array] [, REPORT_FLAG={0 | 1 | 2}] [, STA_NAME=string array] [, STDV=variable] [, /TO_SCREEN]
Keywords
CLASS_DIMS
Use this keyword to specify the spatial dimensions on which to perform the operation. CLASS_DIMS is a five-element array of long integers with the following definitions:
• CLASS_DIMS[0]: Unused for this function, set to -1
• CLASS_DIMS[1]: The starting x pixel (0)
• CLASS_DIMS[2]: The ending x pixel
• CLASS_DIMS[3]: The starting y pixel (0)
• CLASS_DIMS[4]: The ending y pixel
Note that the dimensions specified must be within the classification image, including the first pixel offsets.
CLASS_FID
Use this keyword to specify the file ID of the classification image.
CLASS_PTR
Use this keyword to specify an array of long integers representing class numbers on which to perform statistics.
COMP_FLAG
Set this keyword equal to a bit value indicating the calculations to perform.
• Bit 0: Not used
• Bit 1: Enables the calculation of histograms
• Bit 2: Enables the calculation of covariance
• Bits 3 to 15: Not used
COV (optional)
ENVI Reference Guide CLASS_STATS_DOIT
86 Chapter 2: ENVI Routines
Use this keyword to specify a named variable that contains the returned covariance matrix. You must set bit 2 in COMP_FLAG (i.e., COMP_FLAG=4) to generate the covariance matrix.
DMAX (optional)
Use this keyword to specify a named variable that contains the array of data maximums, one for each band position.
DMIN (optional)
Use this keyword to specify a named variable that contains the array of data minimums, one for each band position.
EVAL (optional)
Use this keyword to specify a named variable that contains the eigenvalues. You must set bit 2 in COMP_FLAG (i.e., COMP_FLAG=4) to generate the covariance matrix.
EVEC (optional)
Use this keyword to specify a named variable that contains the eigenvector. You must set bit 2 in COMP_FLAG (i.e., COMP_FLAG=4) to generate the covariance matrix.
FID
See “Common Keywords” on page 34 for a definition of this keyword.
HIST (optional)
Use this keyword to specify a named variable that contains the histogram array. You must set bit 1 in COMP_FLAG (i.e., COMP_FLAG=2) to generate the histogram output.
MEAN (optional)
Use this keyword to specify a named variable that contains the array of data means, one for each band position.
POS
See “Common Keywords” on page 34 for a definition of this keyword.
REP_NAME (optional)
Use this keyword to specify a string array containing the filename for the output report file.
REPORT_FLAG (optional)
Set this keyword equal to a bit value indicating the type of output reports desired. Logically AND the bit values together to get the desired reports.
• Bit 0: Basic statistics (REPORT_FLAG=1)
• Bit 1: Generate histogram report (default, REPORT_FLAG=2)
• Bit 2: Generate covariance report (REPORT_FLAG=4)
• Bits 3 to 15: Not used
If REPORT_FLAG=0, no output report is generated.
CLASS_STATS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 87
STA_NAME (optional)
Use this keyword to specify a string array containing the filename for the output statistics file.
STDV (optional)
Use this keyword to specify a named variable that contains the array of data standard deviations, one for each band position.
TO_SCREEN (optional)
Set this keyword to print the report on the screen. This keyword only controls the display of the secondary statistics report window. The main statistics report window will appear regardless of this keyword.
Example
pro example_class_stats_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files ; envi_open_file, 'bhtmref.img', r_fid=fid envi_open_file, 'bhtm_sam.img', r_fid=cfid if (fid eq -1 or cfid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, cfid, num_classes=num_classes class_ptr = indgen(num_classes) envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'class_stats.txt' ; ; Call the doit ; envi_doit, 'class_stats_doit', fid=fid, pos=pos, $ dims=dims, comp_flag=0, report_flag=1, $ rep_name=out_name, class_fid=cfid, $ class_ptr=class_ptr ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide CLASS_STATS_DOIT
88 Chapter 2: ENVI Routines
See Also
ENVI_GET_STATISTICSENVI_STATS_DOITENVI_WRITE_STATISTICS
CLASS_STATS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 89
COM_CLASS_DOIT
Use this procedure to combine classes in ENVI classified images.
Syntax
ENVI_DOIT, 'COM_CLASS_DOIT', COMB_LUT=array, DIMS=array, FID=file ID, /IN_MEMORY, OUT_NAME=string, R_FID=variable, /REMOVE_EMPTY
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
R_FID
COMB_LUT
Use this keyword to specify an array of long integers indicating the output class for each input class. COMB_LUT has num_classes elements.
For example, to map class 0 to 0, class 1 to 0, class 2 to 3, and class 3 to 2, set the keyword as follows:
comb_lut = [0, 0, 3, 2]
REMOVE_EMPTY
Set this keyword to remove empty classes after combining. If empty classes are not removed, one or more classes with no elements may exist in the output image. The default is to leave the empty classes.
Example
pro example_com_class_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ;
ENVI Reference Guide COM_CLASS_DOIT
90 Chapter 2: ENVI Routines
envi_open_file, 'bhtm_sam.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, $ num_classes=num_classes pos = [0] out_name = 'testimg' comb_lut = lindgen(num_classes) comb_lut[1] = 0 comb_lut[4] = 2 comb_lut[5] = 2 ; ; Call the doit ; envi_doit, 'com_class_doit', $ fid=fid, pos=pos, dims=dims, $ comb_lut=comb_lut, /remove_empty, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
COM_CLASS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 91
CONTINUUM_REMOVE_DOIT
Use this procedure to perform Continuum Removal on the data.
Syntax
ENVI_DOIT, 'CONTINUUM_REMOVE_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, M_FID=file ID, M_POS=value, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of these keywords.
DIMS
FID
IN_MEMORY
M_FID
M_POS
OUT_BNAME
OUT_NAME
POS
R_FID
Example
pro example_continuum_remove_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ;
ENVI Reference Guide CONTINUUM_REMOVE_DOIT
92 Chapter 2: ENVI Routines
; Set the keywords. We will perform the ; continuum removal on all samples ; and bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Perform the continuum removal ; envi_doit, 'continuum_remove_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
CONTINUUM_REMOVE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 93
CONV_DOIT
Use this procedure to perform convolution filtering, including high pass, low pass, laplacian, Gaussian, median, directional, Sobel, Roberts, and user-defined. For METHOD=1 and METHOD=2, the data type is automatically set to integer. For the remaining methods, the data type is converted as follows. Values in parentheses refer to the IDL convention for data types.
• Input byte (1) converts to integer (2)
• Input unsigned integer (12) converts to integer (2)
• Input unsigned long (13) converts to long (3)
Syntax
ENVI_DOIT, 'CONV_DOIT', ADD_BACK=floating point{0.0 to 1.0}, DIMS=array, FID=file ID, /IN_MEMORY, KERNEL=value, KX=value, KY=value, METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
ADD_BACK
Set this keyword equal to a floating-point or double-precision value between 0.0 and 1.0, specifying the filter add-back percentage. A value of 1.0 is equal to 100%.
KERNEL
Use this keyword to specify a convolution kernel for METHOD=4, 5, 6, 7, and 8.
KX
Use this keyword to specify the x kernel size. For METHOD=0, 1, 2, and 3, KX must be equal to KY. For METHOD=0 and 1, KX must be set equal to 3.
ENVI Reference Guide CONV_DOIT
94 Chapter 2: ENVI Routines
KY
Use this keyword to specify the y kernel size. For METHOD=0, 1, 2, and 3, KY must be equal to KX. For METHOD=0 and 1, KY must be set equal to 3.
METHOD
Use this keyword to specify the type of filter to apply. Choose one of the following:
• 0: Sobel
• 1: Roberts
• 2: Median
• 3: Low pass
• 4: High pass
• 5: Laplacian
• 6: Directional
• 7: Gaussian
• 8: User-defined
Example
pro example_conv_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, nb=nb, bname=bname pos = lindgen(nb) out_name = 'testimg' method = 2 ; ; Call the doit ; envi_doit,'conv_doit', fid=fid, pos=pos, $ dims=dims, out_name=out_name, $ out_bname=bname(pos), method=method, $
CONV_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 95
kx=5, ky=5, add_back=.2, in_memory=0, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide CONV_DOIT
96 Chapter 2: ENVI Routines
CONVERT_DOIT
Use this procedure to convert the interleave type between BSQ, BIL, and BIP.
Syntax
ENVI_DOIT, 'CONVERT_DOIT', DIMS=array, FID=file ID, O_INTERLEAVE={0 | 1 | 2}, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
FID
OUT_NAME
POS
R_FID
O_INTERLEAVE
Set this keyword to one of the following integer values to specify the interleave output:
• 0: BSQ
• 1: BIL
• 2: BIP
Example
pro example_convert_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the
CONVERT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 97
; continuum removal on all samples ; and bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Perform the file conversion. Convert ; the input BSQ image to BIL storage ; order. ; envi_doit, 'convert_doit', $ fid=fid, pos=pos, dims=dims, $ o_interleave=1, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide CONVERT_DOIT
98 Chapter 2: ENVI Routines
CONVERT_INPLACE_DOIT
Use this procedure to convert, in place, an ENVI file from one storage interleave to another. The program allows you to convert between BSQ, BIL, and BIP storage interleaves without creating temporary files.
Syntax
ENVI_DOIT, 'CONVERT_IN_PLACE_DOIT', DIMS=array, FID=file ID, O_INTERLEAVE={0 | 1 | 2}, POS=array [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
DIMS
FID
POS
R_FID (optional)
O_INTERLEAVE
Set this keyword to one of the following integer values to specify the interleave output:
• 0: BSQ
• 1: BIL
• 2: BIP
Example
pro example_convert_inplace_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables
CONVERT_INPLACE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 99
; envi_file_query, fid, dims=dims, nb=nb, $ interleave=interleave o_interleave = ([1,2,0])[interleave] pos = lindgen(nb) ; ; Call the doit envi_doit,'convert_inplace_doit', fid=fid, $ pos=pos, dims=dims, $ o_interleave=o_interleave, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
CONVERT_DOIT
ENVI Reference Guide CONVERT_INPLACE_DOIT
100 Chapter 2: ENVI Routines
CROSS_TRACK_CORRECTION_DOIT
Use this procedure to remove variation in the cross-track illumination of an image and to perform antenna pattern correction on radar images.
Syntax
ENVI_DOIT, 'CROSS_TRACK_CORRECTION_DOIT', DIMS=array, FID=file ID [, /IN_MEMORY] [, M_FID=file ID] [, M_POS=value] [, /MASK_OUTPUT], METHOD={0 | 1} [, ORDER=value] [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=variable], RANGE_DIR={0 | 1}
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY (optional)
M_FID (optional)
M_POS (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
MASK_OUTPUT (optional)
Set this keyword to apply a mask to the output image. By default, the optional mask information you supply (using keywords M_FID and M_POS) is applied only when calculating the polynomial correction. If you do not set M_FID and M_POS, this keyword has no effect.
METHOD
Set this keyword to a value of 0 to perform additive correction, and to a value of 1 to perform multiplicative correction.
ORDER (optional)
Use this keyword to specify the order of the polynomial for the cross-track illumination or antenna-pattern correction. A polynomial function with the defined order is fit to the means of the data specified by RANGE_DIR and used to remove the variations. The default value is 1 (a first-degree polynomial).
CROSS_TRACK_CORRECTION_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 101
RANGE_DIR
Set this keyword to one of the following values to specify the cross-track or range direction.
• 0: Across the samples of a single line
• 1: Across the lines of a single sample
Example
This example is used to compute the cross-track correction for the file bhtmref.img. The correction is applied to all pixels and all bands, without any masking. The cross-track or range direction is set to samples using the RANGE_DIR keyword. The ORDER keyword is set to a second-order polynomial, and the METHOD keyword is used to perform a multiplicative correction. The output is stored to disk. This example uses the following files found in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number):
• bhtmref.img
• bhtmref.hdr
NoteThis correction is not scientifically valid; it is applied to this image only to demonstrate the use of the processing procedure.
pro example_cross_track_correction_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; cross track correction on all samples ; and bands in the file. The correction will ; be in the samples direction, multiplicative, ; and with a 2nd order polynomial. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' range_dir = 0 method = 1 order = 2
ENVI Reference Guide CROSS_TRACK_CORRECTION_DOIT
102 Chapter 2: ENVI Routines
; ; Perform the cross track correction ; envi_doit, 'cross_track_correction_doit', $ fid=fid, pos=pos, dims=dims, $ range_dir=range_dir, out_name=out_name, $ method=method, order=order, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
EMITTANCE_CALC_DOITENVI_AVHRR_CALIBRATE_DOITENVI_CAL_DOITTIMS_CAL_DOITTMCAL_DOIT
CROSS_TRACK_CORRECTION_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 103
DARK_SUB_DOIT
Use this procedure to apply atmospheric scattering corrections to image data. The digital number to subtract from each band can be either the band minimum, an average based upon an ROI, or a specific value.
Syntax
ENVI_DOIT, 'DARK_SUB_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, VALUES=array
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
VALUES
Use this keyword to specify an array of values to subtract from each band of the data. The size of the array is equal to the number of elements in POS.
Example
pro example_dark_sub_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit
ENVI Reference Guide DARK_SUB_DOIT
104 Chapter 2: ENVI Routines
return endif ; ; Set the keywords. We will perform the ; continuum removal on all samples ; and bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' values = [10,5,9,7,2,13] ; ; Perform the dark current subtraction. ; envi_doit, 'dark_sub_doit', $ fid=fid, pos=pos, dims=dims, $ values=values, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
DARK_SUB_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 105
DECOR_DOIT
Use this procedure to remove high correlation between three bands to make a saturated color image.
Syntax
ENVI_DOIT, 'DECOR_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of these keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
Example
pro example_decor_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; decorrelation stretch on the first ; three bands in the file and all ; spatial pixels. ;
ENVI Reference Guide DECOR_DOIT
106 Chapter 2: ENVI Routines
envi_file_query, fid, dims=dims t_fid = [fid,fid,fid] pos = [0,1,2] out_name = 'testimg' ; ; Perform the decorrelation stretch ; envi_doit, 'decor_doit', $ fid=t_fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
DECOR_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 107
DEM_BAD_DATA_DOIT
Use this procedure to correct bad data points and areas in DEMs. Bad data points are defined by a mask band, bad-data value, minimum threshold, or maximum threshold. The results from these optional keywords are combined with an OR logical operator to form the overall bad data mask. You must define at least one of the methods for specifying bad data.
Syntax
ENVI_DOIT, 'DEM_BAD_DATA_DOIT' [, BAD_VALUE=value], DIMS=array, FID=file ID, /IN_MEMORY [, M_FID=file ID] [, M_POS=value] [, MAX_THRESH=value] [, MIN_THRESH=value] [, OUT_BNAME=string array], OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
BAD_VALUE (optional)Use this keyword to specify a single bad DEM value.
M_FID (optional)Use this keyword to specify the file ID of the bad-data mask file. Mask pixels not equal to 0 are considered bad data. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. M_FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
M_POS (optional)Use this keyword to specify the band position of the bad-data mask band. Mask pixels not equal to 0 are considered bad data. M_POS is a long integer with a value greater than or equal to 0.
MAX_THRESH (optional)
ENVI Reference Guide DEM_BAD_DATA_DOIT
108 Chapter 2: ENVI Routines
Use this keyword to specify a single maximum threshold for bad DEM values. Values less than or equal to this threshold are considered bad data. When used in conjunction with MIN_THRESH, values between both thresholds are considered bad.
MIN_THRESH (optional)Use this keyword to specify a single minimum threshold for bad DEM values. Values greater than or equal to this threshold are considered bad data. When used in conjunction with MAX_THRESH, values between both thresholds are considered bad.
See Also
TOPO_DOIT
DEM_BAD_DATA_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 109
DESKEW_DOIT
Use this procedure to deskew Landsat MSS data for Earth rotation.
Syntax
ENVI_DOIT, 'DESKEW_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, LATD=long integer, LATM=long integer, LATS=long integer, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
LATD
Set this keyword to a long integer specifying the latitude degrees for the Landsat scene center.
LATM
Set this keyword to a long integer specifying the latitude minutes for the Landsat scene center.
LATS
Set this keyword to a long integer specifying the latitude seconds for the Landsat scene center.
Example
pro example_deskew_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ;
ENVI Reference Guide DESKEW_DOIT
110 Chapter 2: ENVI Routines
; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; image deskew on all samples and ; bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Deskew the image ; envi_doit, 'deskew_doit', $ fid=fid, pos=pos, dims=dims, $ latd=44, latm=13, lats=0, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
DESKEW_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 111
DESTRIPE_DOIT
Use this procedure to destripe image data for detector imbalance.
Syntax
ENVI_DOIT, 'DESTRIPE_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, NUM_DET=integer, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
NUM_DET
Use this keyword to specify the number of detectors in the instrument. Set to a value of 16 for TM, or to a value of 6 for MSS.
Example
pro example_destripe_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
ENVI Reference Guide DESTRIPE_DOIT
112 Chapter 2: ENVI Routines
; ; Set the keywords. We will perform the ; destriping on all samples and bands ; in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Perform the image destriping ; envi_doit, 'destripe_doit', $ fid=fid, pos=pos, dims=dims, $ num_det=16, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
DESTRIPE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 113
DISP_GET_LOCATION
Use this procedure to return the x and y locations of the current pixel in a given display group. Pixel locations are returned in a modified file coordinate system:
pixel coord = file coord + (x|y)start - 1
Where (x | y)start is the xstart or ystart value in the ENVI header for the displayed image.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
DISP_GET_LOCATION, DN, XFLOC, YFLOC [, /FLOATING] [, /NO_OFFSET]
Arguments
DN
This is the display number corresponding to an open display group.
XFLOC
This returned variable contains the x location of the current pixel in modified file coordinates.
YFLOC
This returned variable contains the y location of the current pixel in modified file coordinates.
Keywords
FLOATING (optional)Set this keyword if you want the XFLOC and YFLOC coordinates to be returned as floating-point values. If you do not set this keyword, then XFLOC and YFLOC will be long-integer values.
NO_OFFSET (optional)Set this keyword to return the current pixel location in ordinary zero-based file coordinates without (x | y)start values being added.
Example
;; This example prints out the location of ; the current pixel for each display;pro example_disp_get_location ; ; Get all the display numbers and ; check to make sure at least one
ENVI Reference Guide DISP_GET_LOCATION
114 Chapter 2: ENVI Routines
; display is present. ; display = envi_get_display_numbers() if (display[0] eq -1) then return ; ; Print out the location of the ; current pixel for each display ; for i=0, n_elements(display)-1 do begin disp_get_location, display[i], xloc, yloc print, display[i], xloc, yloc endforend
See Also
DISP_GOTOENVI_DISP_QUERY
DISP_GET_LOCATION ENVI Reference Guide
Chapter 2: ENVI Routines 115
DISP_GOTO
Use this procedure to move a currently selected pixel to a new location in a display group. The Zoom window will also be moved, so that it is centered on the new current pixel location. If the new current pixel location is not within the current Image window, the Image and Scroll windows will be moved so that they include the new current pixel.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
DISP_GOTO, DN, XFLOC, YFLOC [, /NO_WARN]
Arguments
DN
This is the display number corresponding to an open display group.
XFLOC
This is a named variable that contains the x location of the current pixel in zero-based file coordinates.
YFLOC
This is a named variable that contains the y location of the current pixel in zero-based file coordinates.
Keywords
NO_WARN (optional)Set this keyword if you do not want an error message printed when the (XFLOC, YFLOC) location is invalid for the currently displayed image. For example, if the image is (512, 512) and you specify (700, 700), an error message will be printed, unless you set /NO_WARN.
ENVI Reference Guide DISP_GOTO
116 Chapter 2: ENVI Routines
Example
;; This example moves the current pixel in ; the first display by 10 pixels in the ; X and Y directions.;pro example_disp_goto ; ; Get all the display numbers and ; check to make sure at least one ; display is present. ; display = envi_get_display_numbers() if (display[0] eq -1) then return ; ; Move the first display ten pixels ; in X and Y. ; disp_get_location, display[0], xloc, yloc disp_goto, display[0], xloc+10, yloc+10end
See Also
DISP_GET_LOCATIONENVI_DISP_QUERY
DISP_GOTO ENVI Reference Guide
Chapter 2: ENVI Routines 117
DISP_OUT_IMG
Use this procedure to output an image to a PostScript file.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
DISP_OUT_IMG [, ANN_COLOR=integer] [, ANN_NAMES=string array] [, BORDER=array] [, BPP={1 | 2 | 4 | 8}], /COLOR, DIMS=array, FID=file ID, /LAND, OUT_NAME=string, POS=array, PSIZE=array, REBIN=value, XOFF=value, XSIZE=value, YOFF=value, YSIZE=value
Keywords
ANN_COLOR (optional)Use this keyword to specify the gray scale level for graphical overlays when outputting to gray scale. ANN_COLOR is a single integer value from 0 to 255 (inclusive). The default value is 0.
ANN_NAMES (optional)Use this keyword to specify an array of saved annotation filenames. Each will overlay on the output image.
BORDER (optional)Use this keyword to specify a two-element array of x and y border sizes (in inches).
BPP (optional)Use this keyword to specify the number of bits per pixel in the PostScript output. Valid values are 1, 2, 4, or 8.
COLOR
Set this keyword for color output. You must also set the POS and FID keywords accordingly.
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).
• DIMS[0]: Unused for this routine; set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
ENVI Reference Guide DISP_OUT_IMG
118 Chapter 2: ENVI Routines
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
FID
Use this keyword to specify an array of file IDs. If COLOR=1 (color is enabled), set this keyword as FID=[FID, FID, FID].
LAND
Set this keyword for landscape output. The default is portrait output.
OUT_NAME
Use this keyword to specify a string with the output filename for the PostScript file.
POS
Use this keyword to specify an array of band positions for each of the files specified by the FID array. If COLOR=1 (color is enabled), set this keyword as POS=[0L, 1, 2].
PSIZE
Use this keyword to specify a two-element array indicating the paper size in inches, for example: [8.5, 11].
REBIN
Use this keyword to specify a REBIN factor to apply to the data. Values less than 1 enlarge the data, and values greater than 1 reduce the data.
XOFF
Use this keyword to specify the x offset (in inches) from the left side of the output.
XSIZE
Use this keyword to specify the x size of the output.
YOFF
Use this keyword to specify the y offset (in inches) from the top of the output.
YSIZE
Use this keyword to specify the y size of the output.
Example
pro example_disp_out_img ; ; First restore all the base save files.
DISP_OUT_IMG ENVI Reference Guide
Chapter 2: ENVI Routines 119
; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to select the first band ; in the file. ; envi_file_query, fid, dims=dims pos = [0] ; ; Call the output routine. ; disp_out_img, $ fid=fid, dims=dims, pos=pos, $ bpp=8, color=0, land=0, psize=[8.5,11], $ out_name='test.ps', rebin=1., $ xoff=.25, yoff=.25, xsize=5., ysize=5. ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide DISP_OUT_IMG
120 Chapter 2: ENVI Routines
ELINE_CAL_DOIT
Use this procedure to spectrally calibrate an image using the empirical line method.
Syntax
ENVI_DOIT, 'ELINE_CAL_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, PATH_RAD=array, POS=array, R_FID=variable, SOLAR_IRR=array
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
PATH_RAD
Use this keyword to specify an array of path radiance values, one for each band in the POS array.
SOLAR_IRR
Use this keyword to specify an array of maximum solar irradiance values, one for each band in the POS array.
Example
pro example_eline_cal_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ;
ELINE_CAL_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 121
envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; emperical line calibration on all ; samples and all bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' path_rad = [2.00, 1.33, 1.20, $ 1.11, 2.60, 3.12] solar_irr = [2.33, 4.10, 6.00, $ 1.55, 5.32, 4.05] ; ; Perform the emperical line calibration ; envi_doit, 'eline_cal_doit', $ fid=fid, pos=pos, dims=dims, $ path_rad=path_rad, $ solar_irr=solar_irr, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide ELINE_CAL_DOIT
122 Chapter 2: ENVI Routines
EMITTANCE_CALC_DOIT
Use this procedure to convert data to emissivity using either reference channel emissivity, emissivity normalization, or alpha residuals. Using the keywords DATA_SCALE and WL_SCALE, you can convert input data and wavelengths on the fly to W/m2/m/sr and m, respectively. Optionally, you can output a temperature image using the reference channel emissivity or emissivity normalization method.
Syntax
ENVI_DOIT, 'EMITTANCE_CALC_DOIT' [, CONSTANT_BAND=long integer], DATA_SCALE=value, DIMS=array [, EMISSIVITY_VALUE=value], FID=file ID, /IN_MEMORY, METHOD={0 | 1 | 2} [, OUT_BNAME=string array] [, OUT_NAME=string], POS=array [, R_FID=variable] [, /TEMP_IN_MEMORY] [, TEMP_OUT_NAME=string], WL_SCALE=value
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME (optional)
OUT_NAME (optional)
POS
R_FID (optional)
CONSTANT_BAND (optional)Use this keyword to specify the band position of the constant band used in the reference channel method only. CONSTANT_BAND is a single long integer ranging from 0 to number of bands minus 1.
DATA_SCALE
Use this keyword to specify the scale factor applied to the data, prior to calculating the emissivity. DATA_SCALE converts the input data to W/m2/m/sr.
EMISSIVITY_VALUE (optional)Use this keyword to specify the assumed emissivity value. EMISSIVITY_VALUE is only used when METHOD=0 or 1.
EMITTANCE_CALC_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 123
METHOD
Set this keyword to one of the following values to specify the algorithm for calculating emissivity.
• 0: Reference channel
• 1: Emissivity normalization
• 2: Alpha residuals
TEMP_IN_MEMORY (optional)Set this keyword to specify that output temperature images should be stored in memory.
TEMP_OUT_NAME (optional)Use this keyword to specify an output filename for the temperature image, which is automatically saved. TEMP_OUT_NAME is only valid when METHOD=0 or 1.
WL_SCALE
Use this keyword to specify the scale factor applied to the wavelengths, prior to calculating the emissivity. WL_SCALE converts the input wavelength to m.
See Also
TIMS_CAL_DOIT
ENVI Reference Guide EMITTANCE_CALC_DOIT
124 Chapter 2: ENVI Routines
ENVI
This procedure is used to restore the base ENVI save files (.sav) for batch mode.
Syntax
ENVI, /RESTORE_BASE_SAVE_FILES
Keywords
RESTORE_BASE_SAVE_FILES
Use this keyword to restore the base ENVI save files (.sav). After calling this procedure, use ENVI_BATCH_INIT to initialize batch mode.
Example
This example restores the base ENVI save files (.sav) and initializes ENVI for batch mode.
ENVI, /RESTORE_BASE_SAVE_FILESENVI_BATCH_INIT, LOG_FILE = 'batch_log.txt', BATCH_LUN = lunit
See Also
ENVI_BATCH_EXITENVI_BATCH_INIT
ENVI ENVI Reference Guide
Chapter 2: ENVI Routines 125
ENVIZOOM
This procedure is used to restore the base ENVI Zoom save files (.sav).
Syntax
ENVIZOOM
See Also
ENVI
ENVI Reference Guide ENVIZOOM
126 Chapter 2: ENVI Routines
ENVI_ACE_DOIT
Syntax | Keywords | Example | See Also
Use this procedure to run the Adaptive Coherence Estimator (ACE) target detection analysis. This method is derived from the Generalized Likelihood Ratio (GLR) approach. The ACE is invariant to relative scaling of input spectra and has a Constant False Alarm Rate (CFAR) with respect to such scaling. As with Constrained Energy Minimization (CEM) and Matched Filtering (MF), ACE does not require knowledge of all the endmembers within a scene.
To remove anomalous pixels before modeling the scene background, run ENVI_SUBSPACE_BACKGROUND_STATS_DOIT prior to ENVI_ACE_DOIT. Removing anomalous pixels prior to modeling the scene background can potentially improve the results, particularly in a scene that has a lot of clutter or man-made objects.
Syntax
ENVI_DOIT, 'ENVI_ACE_DOIT', FID=file ID, POS=array, DIMS=array [,M_FID=file ID] [, M_POS=value], TARGET=array [, COV=array] [, /IN_MEMORY], OUT_NAME=string [, OUT_BNAME=string array] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
IN_MEMORY (optional)
OUT_NAME
OUT_BNAME (optional)
R_FID
TARGET
Use this keyword to specify the target spectra. It is a floating-point array. The array size is [number of input bands, number of target spectra].
COV (optional)Set this keyword to specify the covariance matrix for the input bands. If the keyword is not defined, ENVI computes it internally.
ENVI_ACE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 127
Example
pro example_envi_ace_doit
; First restore all the base save files. envi, /restore_base_save_files ; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt. envi_batch_init, log_file=’batch.txt’
; Open the input file envi_open_file, ’mof94av.bil’, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Set the POS keyword ; to process all spectral data. ; Output the result to disk. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’mof94av_ace’ ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for ACE. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. envi_read_cols, ’m94_em.asc’, $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = ’ACE (’ + em_names[2:*] + ’)’ ; Calculate the covariance of the ; input data file. envi_doit, ’envi_stats_doit’, $ fid=fid, pos=pos, dims=dims, $ cov=cov, comp_flag=5
; Call the Adaptive Coherence Estimator ; processing routine. envi_doit,’envi_ace_doit’, $ fid=fid, pos=pos, dims=dims, $ cov=cov, target=endmem, $ out_name=out_name, $ out_bname=out_bname, r_fid=r_fid
; Exit ENVI envi_batch_exit end
ENVI Reference Guide ENVI_ACE_DOIT
128 Chapter 2: ENVI Routines
See Also
ENVI_CEM_DOITENVI_OSP_DOITENVI_SUBSPACE_BACKGROUND_STATS_DOITENVI_TCIMF_DOITENVI_TCIMF_MF_DOITMATCH_FILTER_DOITMATCH_FILTER_MT_DOIT
ENVI_ACE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 129
ENVI_ADD_PROJECTION
Use this procedure to update the ENVI projections.
Syntax
ENVI_ADD_PROJECTION, Proj [, NAME=string] [, /WRITE]
Keywords
NAME (optional)Use this keyword to specify the output file to write, including the directory path. The default is to use map_proj.txt in the map_proj directory of the installation tree. NAME is a string.
WRITE (optional)Set this keyword to update the map projection file. The default is to add the projection to the current ENVI session and not save the projection to a file.
ENVI Reference Guide ENVI_ADD_PROJECTION
130 Chapter 2: ENVI Routines
ENVI_ASSIGN_HEADER_VALUE
Use this procedure to set user-defined header values, which are in addition to the standard ENVI header keywords set using ENVI_SETUP_HEAD or ENVI_ENTER_DATA. User-defined header values use the same KEYWORD=value format as the standard ENVI header values. Use the procedure ENVI_WRITE_FILE_HEADER to write the new ENVI header to disk.
WarningUser-defined keywords can be any string values, but they must not conflict with the standard ENVI header keywords. See The ENVI Header Format in Getting Started with ENVI for a list of these keywords.
Syntax
ENVI_ASSIGN_HEADER_VALUE, FID=file ID, KEYWORD=string [, PRECISION=integer] [, /SCIENTIFIC_NOTATION], VALUE=value
Keywords
FID
See “Common Keywords” on page 34 for a definition of this keyword.
KEYWORD
This is a case-insensitive string with the name of the user-defined keyword.
PRECISION (optional)Use this keyword to specify the number of digits to the right of the decimal point when saving floating-point, double-precision, and complex data types for user-defined header values. The default is to use four decimal places.
NoteBe careful to avoid losing precision since the header values are stored as ASCII strings.
SCIENTIFIC_NOTATION (optional)Set this keyword to store the output string in scientific notation rather than standard floating-point notation.
VALUE
Use this keyword to specify the user-defined keyword values. VALUE can be a single element or an array of byte (8 bits), integer (16 bits), long integer (32 bits), floating-point (32 bits), double-precision floating point (64 bits), complex (2x32 bits), string, double-precision complex (2x64 bits), unsigned integer (16 bits), unsigned long integer (32 bits), long 64-bit integer, or unsigned long 64-bit integer values.
ENVI_ASSIGN_HEADER_VALUE ENVI Reference Guide
Chapter 2: ENVI Routines 131
Example
The following example opens the image file can_tmr.img using the ENVI_OPEN_FILE procedure. Once the file is open and a valid file ID is returned, store a user-defined header value for “My Scale Factors” to the header using ENVI_ASSIGN_HEADER_VALUE. Query the new header field using ENVI_GET_HEADER_VALUE with the FLOAT keyword to return floating-point values. The returned result is printed to the ENVI log window. At this point, the header change exists only in the current ENVI session. To write an updated header to disk, call the procedure ENVI_WRITE_FILE_HEADER.
envi_open_file, 'can_tmr.img', r_fid=fidif (fid eq -1) then returnscale_factors = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]envi_assign_header_value, fid=fid, keyword='My Scale Factors', $ value=scale_factors, precision=3values = envi_get_header_value(fid, 'My Scale Factors', /float)print, 'My Scale Factors', valuesenvi_write_file_header, fid
See Also
ENVI_GET_HEADER_VALUEENVI_WRITE_FILE_HEADER
ENVI Reference Guide ENVI_ASSIGN_HEADER_VALUE
132 Chapter 2: ENVI Routines
ENVI_AUTO_TIE_POINTS_DOIT
This procedure automatically calculates tie points for two images, allowing fully automatic image registration. The ENVI_REGISTER_DOIT procedure uses the tie points to co-register the two images. See “Automatically Coregister Images” in the ENVI User’s Guide for descriptions of the area-based matching technique.
Syntax
ENVI_DOIT, 'ENVI_AUTO_TIE_POINTS_DOIT' [, AREA_CHIP_SIZE=value], BASE_FID=file ID [, BASE_MATCH_POS=scalar] [, IN_TIE_POINTS_ARRAY=array] [, INTEREST_OPERATOR={0 | 1}] [, MIN_CORRELATION=value] [, MOVE_WIN=value] [, NUM_OVERSAMPLES=value] [, NUM_TIE_POINTS=value] [, OUT_TIE_POINTS_ARRAY=array] [, OUT_TIE_POINTS_NAME=string] [, SEARCH_WIN=value], WARP_FID=file ID [, WARP_MATCH_POS=value]
Keywords
AREA_CHIP_SIZE (optional)Use this keyword to specify an integer value for one side of a square image chip size for finding the Moravec or Förstner interest points in the base image. Larger values require more computational time; however, the obtained tie points may be more useful. The default is 128, meaning a 128 x 128 image chip size.
BASE_FID
Use this keyword to specify the file ID of the base image. This is the value returned from the R_FID keyword in the ENVI_OPEN_FILE procedure. BASE_FID is a long integer with a value greater than 0. An invalid file ID is specified as –1.
BASE_MATCH_POS (optional)
Use this keyword to specify a band number from the base image on which to perform image matching. This keyword is a long integer, ranging from 0 to the number of bands minus 1. The default is 0 (the first band).
IN_TIE_POINTS_ARRAY (optional) Use this keyword to store three or more seed tie points to guide the image matching process. This keyword is a [4, n] floating-point array, where the four columns are base image coordinates (x1, y1) and warp image coordinates (x2, y2), and n is the number of tie points.
INTEREST_OPERATOR (optional)
Use this keyword to specify the operator type to use for identifying point features. It can be either 0 (Moravec operator) or 1 (Förstner). The default is 0.
ENVI_AUTO_TIE_POINTS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 133
MIN_CORRELATION (optional) Use this keyword to specify a floating-point value for the minimum correlation coefficient. Any matches with a correlation coefficient smaller than this keyword value are discarded. The default is 0.70.
MOVE_WIN (optional)
Use this keyword to specify an integer that is one side of a square area defining the moving window size. The default value is 11, meaning an moving window size of 11 x 11 pixels.
NUM_OVERSAMPLES (optional) Set this keyword to an integer specifying the number of over-samples. Larger values require more processing time, but result in increased reliability. The default value is 1.
NUM_TIE_POINTS (optional) Use this keyword to specify an integer value for the number of tie points to generate. The default is 25.
OUT_TIE_POINTS_ARRAY (optional) Use this keyword to specify a named variable for storing auto-generated tie points. This keyword is a [4, n] floating-point array, where the four columns are base image coordinates (x1, y1) and warp image coordinates (x2, y2), and n is the number of tie points. The values use zero-based indexing.
OUT_TIE_POINTS_NAME (optional)
Use this keyword to specify an output filename in which to store the tie points. The values use one-based indexing.
SEARCH_WIN (optional) Set this keyword to an integer value representing one side of a square area specifying the search window size. Using larger values makes it more likely that the correct match may be found; however, more computational time is required for these conditions. The default is 81, meaning the search window size is 81 x 81.
WARP_FID
Use this keyword to specify the file ID for the input warp image file. This input warp file ID is the value returned from the R_FID keyword in the ENVI_OPEN_FILE procedure. WARP_FID is a long integer with a value greater than 0. An invalid file ID is specified as –1.
WARP_MATCH_POS (optional) Use this keyword to specify a single band position from the input warp image on which to perform image matching. WARP_MATCH_POS is a long integer, ranging from 0 to the number of bands minus 1. The default is 0 (the first band).
ENVI Reference Guide ENVI_AUTO_TIE_POINTS_DOIT
134 Chapter 2: ENVI Routines
Example
In this example, area-based matching is performed on an image with three known tie points.
pro example1_auto_tie_points_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input files ; envi_open_file, 'bldr_sp.img', r_fid=base_fid envi_open_file, 'bldr_tm.img', r_fid=warp_fid if (base_fid eq -1 || warp_fid eq -1) then begin envi_batch_exit return endif ; ;Set the IN_TIE_POINTS_ARRAY, BASE_MATCH_POS, WARP_MATCH_POS, ; OUT_TIE_POINTS_NAME, NUM_TIE_POINTS, MOVE_WIN, ; SEARCH_WIN, NUM_OVERSAMPLES, and AREA_CHIP_SIZE keywords to ; process ; in_tie_points_array = $ [[285.000000, 255.000000, 133.250000, 263.500000], $ [836.000000, 223.000000, 322.500000, 218.500000], $ [529.000000, 1222.00000, 280.250000, 583.250000]] base_match_pos = 0L warp_match_pos = 0L num_tie_points = 25 move_win = 11 search_win = 81 area_chip_size = 128L num_oversamples = 4 out_tie_points_name = 'out_tie_points1.pts' ; ; Perform the automatic tie point collection ; envi_doit, 'envi_auto_tie_points_doit', base_fid=base_fid, $ warp_fid=warp_fid, base_match_pos=base_match_pos, $ warp_match_pos=warp_match_pos, $ num_tie_points=num_tie_points, move_win=move_win, $ search_win=search_win, area_chip_size=area_chip_size, $ in_tie_points_array=in_tie_points_array, $ num_oversamples=num_oversamples, $ out_tie_points_name=out_tie_points_name ; ; Exit ENVI ; envi_batch_exitend
ENVI_AUTO_TIE_POINTS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 135
See Also
ENVI_REGISTER_DOIT
ENVI Reference Guide ENVI_AUTO_TIE_POINTS_DOIT
136 Chapter 2: ENVI Routines
ENVI_AVHRR_CALIBRATE_DOIT
Use this procedure to calibrate AVHRR data or compute AVHRR SST. The input to this procedure must be an AVHRR Level 1B file or a data file from the NOAA-K through NOAA-M (KLM) satellites. The information in the file header is used for the calibration and SST calculations.
Syntax
ENVI_DOIT, 'ENVI_AVHRR_CALIBRATE_DOIT' [, /CALC_SST] [, /CORRECT_SOLARZ], DIMS=array, FID=file ID [, /IN_MEMORY] [, METHOD={0 | 1 | 2 | 3}] [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
CALC_SST (optional)Set this keyword to output SST instead of the calibrated data. If you set CALC_SST, you must also specify METHOD.
CORRECT_SOLARZ (optional)Set this keyword to allow correction for the solar zenith angle.
METHOD (optional)Use this keyword to specify the algorithm for the Multi-Channel Sea Surface Temperature (MCSST) calculation. If you set METHOD, you must also set CALC_SST. METHOD is one of the following integer values:
• 0: Day MCSST split
• 1: Night MCSST split
• 2: Night MCSST dual
• 3: Night MCSST triple
ENVI_AVHRR_CALIBRATE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 137
Example
pro example_envi_avhrr_calibrate_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files ; envi_open_data_file, 'avhrr_file', $ r_fid=fid, /avhrr if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords ; envi_file_query, fid, dims=dims, nb=nb out_name = 'testimg' pos = lindgen(nb) ; ; Call the doit ; envi_doit, 'envi_avhrr_calibrate_doit', $ fid=fid, dims=dims, pos=pos, $ out_name=out_name, /correct_solarz, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_AVHRR_GEOMETRY_DOIT
ENVI Reference Guide ENVI_AVHRR_CALIBRATE_DOIT
138 Chapter 2: ENVI Routines
ENVI_AVHRR_GEOMETRY_DOIT
Use this procedure to compute the AVHRR geometry (latitude and longitude), solar zenith angles, and sensor zenith angles for each pixel. The input to this procedure must be an AVHRR Level 1B or KLM file. The information in the file header is used to compute the AVHRR geometry.
ENVI uses the same solar geometry calculations as the NOAA Earth System Research Laboratory (see http://www.srrb.noaa.gov/), except that it uses lookup tables to obtain equations for time, declination, and Julian day.
Syntax
ENVI_DOIT, 'ENVI_AVHRR_GEOMETRY_DOIT', DIMS=array, FID=file ID [, /IN_MEMORY], METHOD=array [, OUT_BNAME=string array], OUT_DT={4 | 5}, OUT_NAME=string [, /RADIANS] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
R_FID (optional)
METHOD
Use this keyword to specify which of the output bands to calculate. METHOD is a four-element array of ones and zeros, where a 1 indicates that the corresponding output band should be calculated. METHOD has the following definitions:
• METHOD[0]: Compute the latitude of each pixel
• METHOD[1]: Compute the longitude of each pixel
• METHOD[2]: Compute the solar zenith angle of each pixel
• METHOD[3]: Compute the sensor zenith angle of each pixel
OUT_DT
Use this keyword to specify the output data type as either floating-point or double-precision. OUT_DT is a long integer that uses the IDL data type conventions:
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
ENVI_AVHRR_GEOMETRY_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 139
RADIANS
Set this keyword to specify that output zenith angles are in radians. The default unit is degrees.
Example
pro example_envi_avhrr_geometry_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files ; envi_open_data_file, 'avhrr_file', $ r_fid=fid, /avhrr if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords ; envi_file_query, fid, dims=dims out_name = 'testimg' method = [1,1,1,1] out_bname = ['Latitude', $ 'Longitude', $ 'Solar Zenith', $ 'Sensor Zenith'] ; ; Call the doit ; envi_doit, 'envi_avhrr_geometry_doit', $ fid=fid, dims=dims, out_name=out_name, $ out_dt=4, method=method, $ out_bname=out_bname, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_AVHRR_CALIBRATE_DOIT
ENVI Reference Guide ENVI_AVHRR_GEOMETRY_DOIT
140 Chapter 2: ENVI Routines
ENVI_AVHRR_WARP_DOIT
Use this procedure to warp AVHRR data or resulting AVHRR data products. This procedure requires the file ID from the file to warp and the corresponding AVHRR file ID from the original dataset. For example, you can warp a calibrated image cube or an AVHRR SST image by specifying the file ID of the product and the file ID of the original AVHRR dataset. In order to warp a raw AVHRR dataset, you supply the same file ID. The original AVHRR dataset must be an AVHRR Level 1B or KLM file. The information in the file header is used to compute the warp points.
Syntax
ENVI_DOIT, 'ENVI_AVHRR_WARP_DOIT', AVHRR_FID=variable, BACKGROUND=integer, DEGREE=value, DIMS=array, FID=file ID [, GCP_OUT_NAME=string], GRID=array [, /IN_MEMORY], METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8} [, OUT_BNAME=string array], OUT_NAME=string, PIXEL_SIZE=array, POS=array, PROJ=structure [, R_FID=variable] [, /ZERO_EDGE]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
AVHRR_FID
Use this keyword to specify the file ID for the original AVHRR dataset, either an AVHRR Level 1B or KLM file. This is the value returned from the keyword R_FID in the ENVI_OPEN_DATA_FILE procedure (be sure to set the keyword AVHRR when you call ENVI_OPEN_DATA_FILE). FID is a long integer with a value greater than 0. An invalid file ID is specified as –1.
BACKGROUND
Use this keyword to specify the output image background value.
ENVI_AVHRR_WARP_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 141
DEGREE
Use this keyword to specify the degree of the warp to perform. This keyword is unnecessary when METHOD=0, 1, 2, 6, 7, or 8.
GCP_OUT_NAME (optional)Use this keyword to specify a single string with the output filename for the warp-points file.
GRID
Use this keyword to specify the number of points in the x and y warping grid. GRID is a two-element array of long integers specifying the number of x and y points, respectively, used to form an equally spaced set of warp points.
METHOD
Set this keyword to one of the following integers to specify the warping method to use.
• 0: RST with nearest neighbor
• 1: RST with bilinear
• 2: RST with cubic convolution
• 3: Polynomial with nearest neighbor
• 4: Polynomial with bilinear
• 5: Polynomial with cubic convolution
• 6: Triangulation with nearest neighbor
• 7: Triangulation with bilinear
• 8: Triangulation with cubic convolution
PIXEL_SIZE
Use this keyword to specify the x and y pixel size. PIXEL_SIZE is a two-element, double- precision array of the output x and y pixel sizes, respectively.
PROJ
Use this keyword to specify the projection for the warped file. PROJ is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE.
ZERO_EDGE (optional)Set this keyword to set the edges outside any triangles to the value specified by BACKGROUND. Use this keyword only with triangulation (METHOD=6, 7, or 8).
Example
forward_function envi_proj_units_translate, $ envi_proj_createpro example_envi_avhrr_warp_doit ; ; First restore all the base save files.
ENVI Reference Guide ENVI_AVHRR_WARP_DOIT
142 Chapter 2: ENVI Routines
; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files ; envi_open_data_file, 'avhrr_file', $ r_fid=fid, /avhrr if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' units = envi_proj_units_translate('Degrees') proj = envi_proj_create(/geographic, unit=units) ps = [.05,.05] ; ; Call the doit ; envi_doit, 'envi_avhrr_warp_doit', fid=fid, $ avhrr_fid=fid, dims=dims, pos=pos, $ out_name=out_name, method=1, degree=1, $ background=0, grid=[5,5], proj=proj, $ pixel_size=ps, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_AVHRR_GEOMETRY_DOIT
ENVI_AVHRR_WARP_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 143
ENVI Reference Guide ENVI_AVHRR_WARP_DOIT
144 Chapter 2: ENVI Routines
ENVI_BANDMAX_SELECT_BANDS
This function performs the BandMax background suppression algorithm to derive a subset of significant bands using input target and background spectra. The resulting band subset can be used to highlight targets and suppress backgrounds in a classification or other analysis.
Syntax
Result = ENVI_BANDMAX_SELECT_BANDS(TargetSpectra, BackgroundSpectra [, GOOD_BAND_COUNT=variable] [, GOOD_BAND_LIST=variable] [, SIGNIFICANCE=variable] [, THRESHOLD=value])
Return Value
The return value is an array of band positions that are the best for differentiating between the target and background spectra. This value can be used as a POS input to other ENVI processing functions. If no significant bands are found, a value of –1 is returned.
Arguments
TargetSpectra
This is an array of one or more spectra representing the input targets.
BackgroundSpectra
This is an array of one or more spectra representing the input backgrounds. These spectra must have the same number of bands as the TargetSpectra argument.
Keywords
GOOD_BAND_COUNT (optional)
Use this keyword to specify a named variable that contains a scalar value with the number of significant bands found by the BandMax algorithm.
GOOD_BAND_LIST (optional)
Use this keyword to specify a named variable that contains an array of zeros and ones, indicating which bands the BandMax algorithm determines are significant. Each value is set to 0 (indicating this band should be ignored for processing) or 1 (indicating this band is significant for isolating the targets from the background data). If no significant bands are found, the variable returned by this keyword is undefined.
SIGNIFICANCE (optional)
Use this keyword to specify a named variable that contains an array of band significance values. The array returned by this keyword contains floating-point values ranging from 0 to 1. Each value indicates how well the corresponding band differentiates between target and background spectra. If an error is encountered in the processing, a value of –1 is returned.
THRESHOLD (optional)
ENVI_BANDMAX_SELECT_BANDS ENVI Reference Guide
Chapter 2: ENVI Routines 145
Use this keyword to specify a floating-point value ranging from 0.0 to 1.0. This value represents the threshold for the minimum significance value that determines which bands this function returns. The default threshold value is calculated to select 25% of the input bands, but never less than six bands. If you specify an undefined named variable for this keyword, the default threshold value is returned for that variable.
Examples
The following example uses the cup95eff.int file in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number). The jpl1.sli file is in the IDLxx\products\envixx\spec_lib\jpl_lib directory. Input image wavelengths are derived from the cup95eff.int file to resample the spectra from the library in the jpl1.sli file. One resampled spectrum is used as a target, and another is used as the background in the BandMax algorithm.
PRO BandMaxExample; This example procedure uses the ENVI_BANDMAX_SELECT_BANDS; function(the BandMax algorithm) to determine a subset of bands; for the data in the "cup95eff.int" image file that helps to; differentiate an Alunite target spectrum from a well-ordered; Kaolinite background spectrum. These spectra are a part of the; "jpl1.sli" spectral library.
; Find the input image file and query its wavelengths. These; wavelengths are used to resample the input spectra.cupriteFile = ENVI_PICKFILE(FILTER = '*.int', $
TITLE = 'Find the "cup95eff.int" File')IF (cupriteFile EQ '') THEN RETURNENVI_OPEN_FILE, cupriteFile, R_FID = cupriteFIDENVI_FILE_QUERY, cupriteFID, WL = cupriteWLs
; Find the input spectral library and query its number of samples; and wavelengths. The number of samples value is used to access; specific spectra in the library. The wavelengths are used to; resample the input spectra.libFile = ENVI_PICKFILE(FILTER = '*.sli', $
TITLE = 'Find the "jpl1.sli" File')IF (libFile EQ '') THEN RETURNENVI_OPEN_FILE, libFile, R_FID = libFIDENVI_FILE_QUERY, libFID, NS = libNS, WL = libWLs
; Get spectrum for Alunite (the target) from the input spectral; library.libSpectrum3 = ENVI_GET_SLICE(FID = libFID, LINE = 3, $
POS = 0, XS = 0, XE = libNS - 1); Resample Alunite spectrum to the wavelengths of the input image.ENVI_RESAMPLE_SPECTRA, libWLs, libSpectrum3, cupriteWLs, $
targetSpectrum
; Get spectrum for well-ordered Kaolinite (the background) from; the input spectral library.libSpectrum83 = ENVI_GET_SLICE(FID = libFID, LINE = 83, $
POS = 0, XS = 0, XE = libNS - 1); Resample Kaolinite spectrum to the wavelengths of the input; image.
ENVI Reference Guide ENVI_BANDMAX_SELECT_BANDS
146 Chapter 2: ENVI Routines
ENVI_RESAMPLE_SPECTRA, libWLs, libSpectrum83, cupriteWLs, $backgroundSpectrum
; Perform the BandMax algorithm on the Alunite target and the; Kaolinite background to obtain a subset for the input image.subset = ENVI_BANDMAX_SELECT_BANDS(targetSpectrum, $
backgroundSpectrum); Show the resulting subset. This subset can be used as an input to; the POS keyword of any ENVI library routine. It will help to; differentiate the target from the background in the input image.PRINT, subset
; Exit out of Batch ModeENVI_BATCH_EXIT
END
This example produces the following subset of band positions:
2 3 6 11 14 15 17 18 21 29 30 35 37
It can be applied to the input image through the POS keyword in other ENVI procedures to help differentiate the target spectrum from the background spectrum.
ENVI_BANDMAX_SELECT_BANDS ENVI Reference Guide
Chapter 2: ENVI Routines 147
ENVI_BATCH_EXIT
Use this procedure to terminate an ENVI session from the non-menu batch mode. See “Exiting Batch Mode” in the ENVI Programmer’s Guide for a more complete description.
Syntax
ENVI_BATCH_EXIT [, /EXIT_IDL] [, /NO_CONFIRM]
Keywords
EXIT_IDL (optional)
Use this keyword to force IDL to exit even if ENVI’s preference setting for Exit IDL on Exit from ENVI is set to No.
NO_CONFIRM (optional)
Set this keyword to override IDL’s exit confirmation preference setting.
Example
See “Examples of ENVI Batch Mode Routines” in the ENVI Programmer’s Guide.
See Also
ENVIENVI_BATCH_INITENVI_DOIT
ENVI Reference Guide ENVI_BATCH_EXIT
148 Chapter 2: ENVI Routines
ENVI_BATCH_INIT
Use this procedure to initialize ENVI in the non-menu batch mode. See “Initiating Batch Mode” in the ENVI Programmer’s Guide for a more complete description.
WarningDo not attempt to initialize ENVI in batch mode from an IDL session that is currently running an interactive ENVI session. Instead, start a new IDL session to initialize ENVI in batch mode.
Syntax
ENVI_BATCH_INIT [, BATCH_LUN=variable] [, LOG_FILE=string] [, /NO_STATUS_WINDOW]
Keywords
BATCH_LUN (optional)
Use this keyword to specify a named variable that contains the logical unit number of the batch log file.
LOG_FILE (optional)
Use this keyword to specify a batch log file. Any errors or warnings that would normally appear on the screen during an interactive ENVI session will be written to the log file. It is important to check your log file after your processing is complete, to make sure no errors have occurred. LOG_FILE is a string variable specifying the filename and path of the batch log file.
NO_STATUS_WINDOW (optional)
Set this keyword to prevent the ENVI processing status window from displaying. Additional control of the status window can be achieved using ENVI_BATCH_STATUS_WINDOW.
Example
See “Examples of ENVI Batch Mode Routines” in the ENVI Programmer’s Guide.
See Also
ENVIENVI_BATCH_EXITENVI_BATCH_STATUS_WINDOWENVI_DOIT
ENVI_BATCH_INIT ENVI Reference Guide
Chapter 2: ENVI Routines 149
ENVI_BATCH_STATUS_WINDOW
Use this procedure to enable and disable the ENVI batch status window. The status window is used to show the progress of the processing routines.
ENVI_BATCH_STATUS_WINDOW allows you to precisely control the status window and to enable and disable the status window multiple times in a single batch mode session. In addition, the keyword NO_STATUS_WINDOW in the ENVI_BATCH_INIT procedure controls the initial state of the status window.
Syntax
ENVI_BATCH_STATUS_WINDOW [, /OFF] [, /ON]
Keywords
OFF (optional)
Set this keyword to prevent display of the ENVI processing status window.
ON (optional)
Set this keyword to allow display of the ENVI processing status window.
Example
The following example runs statistics on bhtmref.img with and without the status window. This example uses the following files found in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number):
• bhtmref.img
• bhtmref.hdr
First, initialize ENVI in batch mode with the status window present. Open the file bhtmref.img and use ENVI_STATS_DOIT to perform basic statistical calculations. During this process, the status window will be displayed. Next, turn off the status window and perform the same statistics processing. This time, the status window is not displayed. After each statistical calculation, print the mean value.
pro example_envi_batch_status_window ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin
ENVI Reference Guide ENVI_BATCH_STATUS_WINDOW
150 Chapter 2: ENVI Routines
envi_batch_exit return endif ; ; Get the dimensions and # bands ; for the input file. ; envi_file_query, fid, dims=dims, nb=nb ; ; Set the pos to calculate ; statistics for all data (spectrally) ; in the file. ; pos = lindgen(nb) ; ; Calculate the basic statistics and ; print the mean. ; envi_doit, 'envi_stats_doit', fid=fid, pos=pos, $ dims=dims, comp_flag=1, mean=mean print, 'Mean', mean ; ; Turn off the status window and do the same ; envi_batch_status_window, /off ; ; Calculate the basic statistics and ; print the mean. ; envi_doit, 'envi_stats_doit', fid=fid, pos=pos, $ dims=dims, comp_flag=1, mean=mean print, 'Mean', mean ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_BATCH_INITENVI_DOIT
ENVI_BATCH_STATUS_WINDOW ENVI Reference Guide
Chapter 2: ENVI Routines 151
ENVI_BUFFER_ZONE_DOIT
Use this procedure to create a buffer-zone image from a classification image. Each pixel in the output image is the nearest distance, in pixels, from any classified pixel specified by CLASS_PTR. Any pixels that are farther away from the MAX_DISTANCE are set to MAX_DISTANCE.
Syntax
ENVI_DOIT, 'ENVI_BUFFER_ZONE_DOIT', CLASS_PTR=array, DIMS=array [, DISTANCE_DT={0 | 1}], FID=file ID [, /IN_MEMORY], MAX_DISTANCE=long integer [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
CLASS_PTR
Use this keyword to specify the classes around which to compute the buffer zone. CLASS_PTR is an array of long integers representing class numbers ranging from 0 (“Unclassified”) to the number of classes.
DISTANCE_DT (optional)
Use this keyword to specify the output data type: 0 (integer) or 1 (floating-point). Depending on the maximum distance, integer data types are byte, unsigned integer, or unsigned long integer. The default value is 1 (floating-point output).
MAX_DISTANCE
Use this keyword to specify a long integer representing the maximum distance (in pixels) for the buffer zone. Pixels greater than this value will be set to MAX_DISTANCE.
Example
pro example_envi_buffer_zone_doit
ENVI Reference Guide ENVI_BUFFER_ZONE_DOIT
152 Chapter 2: ENVI Routines
; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtm_sam.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to ; processes the first band (classifcation ; images only have one band) and all the ; pixels. The MAX_DISTANCE and CLASS_PTR ; keywords are set to create a buffer ; zone of 20 pixels around the second ; class (remember the first class is the ; unclassified class). ; envi_file_query, fid, dims=dims pos = [0] out_name = 'testimg' max_distance = 20 distance_dt = 1 class_ptr = [1] ; ; Call the doit ; envi_doit,'envi_buffer_zone_doit', $ fid=fid, pos=pos, dims=dims, $ max_distance=max_distance, class_ptr=class_ptr, $ distance_dt=distance_dt, out_name=out_name ; ; Exit ENVI ; envi_batch_exitend
ENVI_BUFFER_ZONE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 153
ENVI_CAL_DOIT
Use this procedure to spectrally calibrate an image using flat field or IARR methods.
Syntax
ENVI_DOIT, 'ENVI_CAL_DOIT', DIMS=array, DSTR=variable, FID=file ID, /IN_MEMORY, MEAN=array, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
DSTR
Use this keyword to specify a named variable that holds one of the following descriptions (depending on which method was used to calculate the mean values): 'Flat Field' or 'IARR Calibration'.
MEAN
Use this keyword to specify an array of floating-point values to divide into each band. The array size is equal to the number of bands you specify.
Example
pro example_envi_cal_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file
ENVI Reference Guide ENVI_CAL_DOIT
154 Chapter 2: ENVI Routines
; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; flat field calibration on all ; samples and all bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' mean = [1.39, 2.15, 3.41, $ 1.73, 1.92, 4.32] dstr = 'Flat Field' ; ; Perform the Flat Field calibration ; envi_doit, 'envi_cal_doit', $ fid=fid, pos=pos, dims=dims, $ mean=mean, dstr=dstr, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI_CAL_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 155
ENVI_CEM_DOIT
Syntax | Keywords | Example | See Also
Use this procedure to run the Constrained Energy Minimization (CEM) target detection analysis. As with Adaptive Coherence Estimator (ACE) and Matched Filtering (MF), CEM does not require knowledge of all the endmembers within a scene. Using a specific constraint, CEM uses a finite impulse response (FIR) filter to pass through the desired target while minimizing its output energy resulting from background other than the desired targets. A correlation or covariance matrix is used to characterize the composite unknown background. In a mathematical sense, MF is a mean-centered version of CEM, where the data mean is subtracted from all pixel vectors.
To remove anomalous pixels before modeling the scene background, run ENVI_SUBSPACE_BACKGROUND_STATS_DOIT prior to ENVI_CEM_DOIT. Removing anomalous pixels prior to modeling the scene background can potentially improve the results, particularly in a scene that has a lot of clutter or man-made objects.
Syntax
ENVI_DOIT, 'ENVI_CEM_DOIT', FID=file ID, POS=array, DIMS=array [,M_FID=file ID] [,M_POS=value], TARGET=array [, COV=array] [, /USE_COV] [, /IN_MEMORY], OUT_NAME=string [, OUT_BNAME=string array] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
IN_MEMORY (optional)
OUT_NAME
OUT_BNAME (optional)
R_FID (optional)
TARGET
Use this keyword to specify the target spectra. It is a floating-point array. The array size is [number of input bands, number of target spectra].
ENVI Reference Guide ENVI_CEM_DOIT
156 Chapter 2: ENVI Routines
COV (optional)
Set this keyword to specify the covariance matrix for the input bands. If the keyword is not defined, ENVI computes it internally.
USE_COV (optional)
Set this keyword to specify using the covariance matrix as background statistics, instead of the correlation matrix for the input bands. By default, ENVI uses the input bands correlation matrix as background statistics, which is derived from the covariance matrix internally. If this keyword is defined, it must be with a non-zero value.
Example
pro example_envi_cem_doit
; First restore all the base save files. envi, /restore_base_save_files ; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt. envi_batch_init, log_file=’batch.txt’
; Open the input file envi_open_file, ’mof94av.bil’, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Set the POS keyword ; to process all spectral data. ; Output the result to disk. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’mof94av_cem’ ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for CEM. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. envi_read_cols, ’m94_em.asc’, $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = ’CEM (’ + em_names[2:*] + ’)’ ; Calculate the covariance of the ; input data file. envi_doit, ’envi_stats_doit’, $ fid=fid, pos=pos, dims=dims, $ cov=cov, comp_flag=5
; Call the Constrained Energy Minimization
ENVI_CEM_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 157
; processing routine. envi_doit,’envi_cem_doit’, $ fid=fid, pos=pos, dims=dims, $ cov=cov, target=endmem, $ out_name=out_name, $ out_bname=out_bname, r_fid=r_fid
; Exit ENVI envi_batch_exit end
See Also
ENVI_ACE_DOITENVI_OSP_DOITENVI_SUBSPACE_BACKGROUND_STATS_DOITENVI_TCIMF_DOITENVI_TCIMF_MF_DOITMATCH_FILTER_DOITMATCH_FILTER_MT_DOIT
ENVI Reference Guide ENVI_CEM_DOIT
158 Chapter 2: ENVI Routines
ENVI_CENTER
Use this procedure to return the centering offsets for a widget.
Syntax
ENVI_CENTER, Xoff, Yoff [, /XBIG] [, /YBIG]
Arguments
Xoff
This is a named variable that contains the x (horizontal) offset for use in the call to the IDL routine WIDGET_BASE.
Yoff
This is a named variable that contains the y (vertical) offset for use in the call to the IDL routine WIDGET_BASE.
Keywords
XBIG (optional)
Set this keyword if the widget will be large in the horizontal direction.
YBIG (optional)
Set this keyword if the widget will be large in the vertical direction.
Example
This example gets the centering information from ENVI_CENTER and uses it in the call to WIDGET_BASE.
envi_center, xoff, yoffbase = widget_base(title='Center test', xoff=xoff, $
yoff=yoff, /column)
ENVI_CENTER ENVI Reference Guide
Chapter 2: ENVI Routines 159
ENVI_CLOSE_DISPLAY
This procedure closes a display group.
Syntax
ENVI_CLOSE_DISPLAY, DN
Arguments
DN
This is the display number corresponding to a display group. Display numbers (DNs) are zero-based; ENVI Display #1 corresponds to DN=0.
Keywords
None
Example
To close ENVI Display #3, use the following code:
ENVI_CLOSE_DISPLAY, 2
ENVI Reference Guide ENVI_CLOSE_DISPLAY
160 Chapter 2: ENVI Routines
ENVI_CLOVER_DOIT
Use this procedure to overlay a classification image on the output image.
Syntax
ENVI_DOIT, 'ENVI_CLOVER_DOIT', CFID=file ID, DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, OVERLAY_LUT=array, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
CFID
Use this keyword to specify the file ID of the classification image file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. CFID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
OVERLAY_LUT
Use this keyword to specify an array indicating which classes to overlay on the image. For example, to overlay classes 2, 3 and 4, set the keyword as follows:
overlay_lut = [2, 3, 4]
NoteClass numbers are zero-based, and the “Unclassified” class is usually Class 0.
If you overlay all the classes on the output image, the output image will not be visible. Typically, unclassified pixels do not overlay.
Example
pro example_clover_doit ;
ENVI_CLOVER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 161
; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files. ; Set the path on the input file. ; Create bhtm_sam.img and set the path. ; envi_open_file, 'bhtmref.img', r_fid=fid envi_open_file, 'bhtm_sam.img', r_fid=cfid if (fid eq -1 or cfid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, nb=nb pos = [0,1,2] out_name = 'testimg' overlay_lut = [1,4,5] cpos = [0] ; ; Call the doit ; envi_doit, 'envi_clover_doit', $ fid=fid, pos=pos, dims=dims, $ cfid=cfid, overlay_lut=overlay_lut, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide ENVI_CLOVER_DOIT
162 Chapter 2: ENVI Routines
ENVI_COLLECT_SPECTRA
Use this procedure to perform spectra collection. This procedure incorporates ENVI’s Endmember Collection dialog into a user function; the dialog is used to collect training sets and endmembers for classification and mapping routines. For more information, see “Using Endmember Collection Widgets” in the ENVI Programmer’s Guide.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
ENVI_COLLECT_SPECTRA, DIMS=array, FID=file ID [, INFO=variable] [, M_FID=file ID] [, M_POS=value] [, POS=array], PROCEDURE=procedure [, TITLE=string]
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
FID
M_FID (optional)
M_POS (optional)
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).
• DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
INFO (optional)
Use this keyword to specify user-defined data to pass to the routine defined by the keyword PROCEDURE. The value of INFO can be any IDL variable, including structures.
POS (optional)
ENVI_COLLECT_SPECTRA ENVI Reference Guide
Chapter 2: ENVI Routines 163
Use this keyword to specify an array of band positions. POS is an array of long integers, ranging from 0 to the number of bands minus 1. The default is POS = LINDGEN(nb), where the number of bands is retrieved from the file specified by FID.
PROCEDURE
Use this keyword to specify the procedure to call when you click Apply on the Endmember Collection dialog. PROCEDURE must have the following definition even if you do not specify the optional keywords to ENVI_COLLECT_SPECTRA:
PRO MY_PROCEDURE, FID=FID, POS=POS, DIMS=DIMS, $ INFO=INFO, M_FID=M_FID, M_POS=M_POS, SPEC=SPEC, $ SNAMES=SNAMES, SCOLORS=SCOLORS, _EXTRA=_EXTRA
The values from the keywords FID, POS, DIMS, INFO, M_FID and M_POS are passed through from the call to ENVI_COLLECT_SPECTRA. SPEC, SNAMES and SCOLORS contain information about the collected spectra. The SPEC array, whose dimensions are [nb, nspec], contains the data for the collected spectra. SNAMES is a string array of the collected spectra names. SCOLOR is an array of graphics color indices. To convert graphics colors to RGB triplets, see ENVI_GET_RGB_TRIPLETS. The keyword _EXTRA is used to collect unused keywords.
TITLE (optional)
Use this keyword to specify the string used in the title bar of the Spectral Collection dialog. The default string is Endmember Collection.
Example
pro example_envi_collect_spectra
envi_select, fid=fid if (fid eq -1) then return
envi_collect_spectra, fid=fid, procedure='my_procedure'
end;; Define the procedure to called each time the; apply button is selected.;pro my_procedure, fid=fid, pos=pos, dims=dims, spec=spec, $ snames=snames, scolors=scolors, _extra=_extra
print, 'snames ', snames print, 'scolors ', scolors print, 'spec ', spec
end
ENVI Reference Guide ENVI_COLLECT_SPECTRA
164 Chapter 2: ENVI Routines
ENVI_COMPUTE_SUN_ANGLES
Use this function to compute solar elevation and azimuth angles for a given time, latitude, and longitude. This function returns a two-element array of double-precision values representing solar elevation and azimuth, respectively, for the selected input values.
Syntax
Result = ENVI_COMPUTE_SUN_ANGLES (Day, Month, Year, GMTtime, Lat, Lon)
Arguments
Day
Use this keyword to specify the day of year for the desired solar angles. Day is an integer value, 1 through 31.
Month
Use this keyword to specify the month for the desired solar angles. Month is an integer value, 1 through 12.
Year
Use this keyword to specify the year for the desired solar angles. Year is an integer value of the form yyyy.
GMTtime
Use this keyword to specify the Greenwich Mean Time (GMT) for the desired solar angles. GMTtime is a floating-point value, 0 through 2400. For example, a value of 1430.0 represents a GMT time of 14:30.
Lat
Use this keyword to specify the latitude for the desired solar angles. Lat is a floating-point number in degrees. North is positive and South is negative.
Lon
Use this keyword to specify the longitude for the desired solar angles. Lon is a floating-point number in degrees. East is positive and West is negative.
Example
This example computes solar elevation and azimuth angles for 34 degrees north, 117 degrees west on July 4, 1984, 22:45 GMT.
angles = envi_compute_sun_angles(4, 7, 1984, 2245., $34., -117.)
print, 'Sun elevation= ', angles[0]print, 'Sun azimuth= ', angles[1]
ENVI_COMPUTE_SUN_ANGLES ENVI Reference Guide
Chapter 2: ENVI Routines 165
See Also
TOPO_DOIT
ENVI Reference Guide ENVI_COMPUTE_SUN_ANGLES
166 Chapter 2: ENVI Routines
ENVI_CONVERT_FILE_COORDINATES
Use this procedure to convert x,y pixel coordinates to their corresponding map coordinates, and vice-versa, for a given file.
Syntax
ENVI_CONVERT_FILE_COORDINATES, FID, XF, YF, XMap, YMap [, /TO_MAP]
Arguments
FID
Use this argument to specify a named variable that contains the file ID for the open file. The file ID is used to get the appropriate projection information for the conversion. If the file does not have an associated projection, the file coordinates and map coordinates are equal. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
XF
If you set the TO_MAP keyword, XF is a variable that contains the x file coordinates to convert. XF can be a single value or an array of values. The first file coordinate is 0.
If you do not set the TO_MAP keyword, XF is a named variable that contains the returned x file coordinates for the input XMap and YMap arrays.
YF
If you set the TO_MAP keyword, YF is a variable that contains the y file coordinates to convert. YF can be a single value or an array of values. The first file coordinate is 0.
If you do not set the TO_MAP keyword, YF is a named variable that contains the returned y file coordinates for the input XMap and YMap arrays.
XMap
If you set the TO_MAP keyword, XMap is a named variable that contains the returned x map coordinates for the input XF and YF arrays
If you do not set the TO_MAP keyword, XMap is a variable that contains the x map coordinates to convert. XMap can be a single value or an array of values.
YMap
If you set the TO_MAP keyword, YMap is a named variable that contains the returned y map coordinates for the input XF and YF arrays
If you do not set the TO_MAP keyword, YMap is a variable that contains the y map coordinates to convert. YMap can be a single value or an array of values.
ENVI_CONVERT_FILE_COORDINATES ENVI Reference Guide
Chapter 2: ENVI Routines 167
Keywords
TO_MAP (optional)
Set this keyword to convert the input file coordinates to map coordinates.
Example
This example converts the first three pixels on the first line to map coordinates.
xf = [0,1,2]yf = [0,0,0]envi_convert_file_coordinates, fid, xf, yf, xmap, ymap, /to_map
See Also
WIDGET_GEOWIDGET_MAP
ENVI Reference Guide ENVI_CONVERT_FILE_COORDINATES
168 Chapter 2: ENVI Routines
ENVI_CONVERT_FILE_MAP_PROJECTION
Use this procedure to convert a file from its current map projection to a specified output projection. This procedure requires an input file, the output projection, and the resampling and warping method; no ground control points are needed (they are generated internally). This procedure converts among many projections in ENVI. Neither the input nor output projection can be Arbitrary.
Syntax
ENVI_CONVERT_FILE_MAP_PROJECTION [, BACKGROUND=integer] [, DEGREE=value], DIMS=array, FID=file ID [, GCP_NAME=string] [, GRID=array] [, O_PIXEL_SIZE=array], O_PROJ=structure [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=variable] [, RESAMPLING={0 | 1 | 2}] [, WARP_METHOD={0 | 1 | 2 | 3}] [, /ZERO_EDGE]
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
FID
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
BACKGROUND (optional)
Use this keyword to specify the output image background value. All pixels outside the warped-image boundary will be set to this value. The default is 0.
DEGREE (optional)
Use this keyword to specify the degree of the warping polynomial for the polynomial method. The degree of the polynomial is limited by the number of ground control points (GCPs). You must ensure that #GCPs > (DEGREE + 1)2. The default value is 1 (first-degree polynomial).
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).
• DIMS[0]: Unused for this routine; set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
ENVI_CONVERT_FILE_MAP_PROJECTION ENVI Reference Guide
Chapter 2: ENVI Routines 169
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
GCP_NAME (optional)
Use this optional string keyword to specify the output filename for the warp points. If WARP_METHOD=3, this keyword is ignored.
GRID (optional)
Use this keyword to specify a two-element array of long integers representing the grid spacing in pixels for the x and y warp points, respectively, used to convert between the two map projections. Regardless of the GRID value, a minimum of four corner points will be used. The default is to use every 10th point in both x and y.
If WARP_METHOD=3, this keyword is ignored.
O_PIXEL_SIZE (optional)
Use this keyword to specify a two-element array of double-precision values representing the x and y pixel sizes, respectively.
O_PROJ
Use this keyword to specify the output projection for the converted file. You cannot set O_PROJ to the Arbitrary projection. O_PROJ is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE.
RESAMPLING (optional)
Set this keyword to one of the following values to specify the resampling method:
• 0: Nearest neighbor
• 1: Bilinear
• 2: Cubic convolution
The default method is nearest neighbor.
WARP_METHOD (optional)
Set this keyword to one of the following values to specify the warp or rigorous projection method:
• 0: Rotation, scaling, and translation (RST)
• 1: Polynomial
• 2: Triangulation
• 3: Rigorous (pixel-by-pixel)
The default method is RST.
ENVI Reference Guide ENVI_CONVERT_FILE_MAP_PROJECTION
170 Chapter 2: ENVI Routines
If WARP_METHOD=3, the GCP_NAME and GRID keywords are ignored.
ZERO_EDGE (optional)
Set this keyword to specify that the edges outside of any triangles are set to the value specified by BACKGROUND. The keyword is used only for triangulation (WARP_METHOD=2).
Example
The following example converts the file bhtmref.img from UTM zone 13 North to UTM zone 12 North. This example uses the following files in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number):
• bhtmref.img
• bhtmref.hdr
Create the output UTM projection using ENVI_PROJ_CREATE, with UTM Zone 12 North, the default datum of North America 1927, and the default units of meters. Set the output pixel size to 28.5 meters for both x and y. Use the RST method with bilinear resampling for conversion.
forward_function envi_proj_create
pro example_envi_convert_file_map_projection ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file=’batch.txt’ ; ; Open the input file ; envi_open_file, ’bhtmref.img’, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Setup the values for the keywords ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’testimg’ o_proj = envi_proj_create(/utm, zone=12) o_pixel_size = [28.5, 28.5] ; ; Call the doit ; envi_convert_file_map_projection, fid=fid, $ pos=pos, dims=dims, o_proj=o_proj, $ o_pixel_size=o_pixel_size, grid=[50,50], $
ENVI_CONVERT_FILE_MAP_PROJECTION ENVI Reference Guide
Chapter 2: ENVI Routines 171
out_name=out_name, warp_method=0, $ resampling=1, background=0 ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_CONVERT_FILE_COORDINATESENVI_CONVERT_PROJECTION_COORDINATESENVI_GET_PROJECTIONENVI_PROJ_CREATE
ENVI Reference Guide ENVI_CONVERT_FILE_MAP_PROJECTION
172 Chapter 2: ENVI Routines
ENVI_CONVERT_LIDAR_DATA_DOIT
This procedure reads a LAS-formatted LIDAR data file and converts it to either an ENVI image file or an EVF file.
Syntax
ENVI_DOIT, 'ENVI_CONVERT_LIDAR_DATA_DOIT' [, BACKGROUND=value] [, DATA_TYPE={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}] [, /EXTRAP], FNAME=string, /IN_MEMORY | [, INTERP={0 | 1}] [, MODEL_TYPE={0 | 1 | 2}] [, OMAP_INFO=variable], OUT_FNAME=string [, OUT_IMAGE={0 | 1 | 2}] [, /OPEN] [, R_FID=variable] [, /VECTOR]
Keywords
NoteThe keywords DATA_TYPE, EXTRAP, INTERP, MODEL_TYPE, and OUT_IMAGE only apply when converting the LAS LIDAR data to ENVI raster data. If you set the keyword VECTOR, these keywords are ignored.
BACKGROUND (optional)
Use this keyword to specify a floating-point value to use for the elevation and intensity data that lie outside the calculated triangles defined by the LAS point data. The default value is 0.
DATA_TYPE (optional)
Use this keyword to specify the IDL data type of the file, using the following IDL convention. The default data type is integer (DATA_TYPE=2).
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
EXTRAP (optional)
Set this keyword to extrapolate the results past the bounds of the data.
ENVI_CONVERT_LIDAR_DATA_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 173
FNAME
Set this keyword to a string representing the name and full path of the input LAS LIDAR file.
IN_MEMORY (optional)
See “Common Keywords” on page 34 for a definition of this keyword.
INTERP (optional)
Use this keyword to specify the type of interpolation used to convert the data. Set INTERP to 0 for the linear method (default), or to 1 for the quintic method.
MODEL_TYPE (optional)
Set this keyword to one of the following values to indicate the type of model used to convert the data.
• 0: Last return (default)
• 1: Full feature
• 2: First return
OMAP_INFO (optional)
Use this keyword to specify the output map information structure that the data should be written to. This structure should have the same format as that returned from ENVI_MAP_INFO_CREATE.
OUT_FNAME
Use this keyword to specify an output filename for the resulting data. If you set the keyword IN_MEMORY, this keyword is unnecessary.
OUT_IMAGE (optional)
Set this keyword to one of the following values to indicate the type of raster output produced.
• 0: Elevation and intensity (default)
• 1: Elevation only
• 2: Intensity only
OPEN (optional)
Set this keyword to automatically open the resulting ENVI image file in the Available Bands List, or the ENVI vector file in the Available Vectors List.
R_FID (optional)
Use this keyword to specify a named variable that contains the file ID for the resulting ENVI image file or the vector ID for the resulting vectors. You can use this file ID to subsequently access the resulting processed data. This keyword returns a value of –1 if an error occurs trying to create an ENVI raster file, or a null pointer if an error occurs trying to create an ENVI vector file.
VECTOR (optional)
ENVI Reference Guide ENVI_CONVERT_LIDAR_DATA_DOIT
174 Chapter 2: ENVI Routines
Set this keyword to save the data as vectors to an EVF. By default, the data are converted to raster and saved to an ENVI image file.
ENVI_CONVERT_LIDAR_DATA_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 175
ENVI_CONVERT_PROJECTION_COORDINATES
Use this procedure to convert map coordinates from one projection to another. The procedure supports conversion among any ENVI projection types including user-defined. For example, this procedure can convert UTM coordinates to Geographic (latitude and longitude) or between UTM zones.
Syntax
ENVI_CONVERT_PROJECTION_COORDINATES, iXmap, iYmap, iProj, oXmap, oYmap, oProj [, INPUT_Z=array] [, OUTPUT_Z=variable]
Arguments
iXmap
Use this argument to specify the input x map points that will be converted from the iProj projection to the oProj projection. iXmap can be a single value or an array of values.
iYmap
Use this argument to specify the input y map points that will be converted from the iProj projection to the oProj projection. iYmap can be a single value, or an array of values.
iProj
Use this argument to specify the input projection for the iXmap and iYmap points. iProj is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE
oProj
Use this argument to specify the output projection for the converted iXmap and iYmap points. oProj is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE.
oXmap
Use this argument to specify a named variable that contains the converted x map points. The oXmap points are the input x map coordinates converted to the oProj projection.
oYmap
Use this argument to specify a named variable that contains the converted y map points. The oYmap points are the input y map coordinates converted to the oProj projection.
Keywords
INPUT_Z (optional)
Use this keyword to specify the input elevation values corresponding to each of the input iXmap and iYmap points. Elevation values are used to more accurately convert between different data. INPUT_Z is a floating-point array with the same length as iXmap.
ENVI Reference Guide ENVI_CONVERT_PROJECTION_COORDINATES
176 Chapter 2: ENVI Routines
OUTPUT_Z (optional)
Use this keyword to specify a named variable that contains the output elevation values for each of the converted map coordinates. Use OUTPUT_Z only when you specify INPUT_Z.
Example
This example converts a series of latitude and longitude points in a Geographic projection to a UTM Zone 11 projection. The new map points are converted to a UTM Zone 12 projection. First, create the Geographic and UTM Zone 11 projections using ENVI_GET_PROJECTION. Next, create an array of x,y latitude and longitude map coordinates. Convert these points to UTM Zone 11 using ENVI_CONVERT_PROJECTION_COORDINATES. The results of the UTM Zone 11 map coordinates will not be converted to UTM Zone 12 map coordinates.
; ; Build the projections using ; the standard defaults;iproj = ENVI_PROJ_CREATE(/geographic)oproj = ENVI_PROJ_CREATE(/utm,zone=11);; Create the pairs of Latitude and Longitudeixmap = [-117., -117.5, -118., $ -117., -117.5, -118.]iymap = [34.0, 34.0, 34.0, $ 35.0, 35.0, 35.0];; Convert from Geographic to UTM zone 11;ENVI_CONVERT_PROJECTION_COORDINATES, $ ixmap, iymap, iproj, $ oxmap, oymap, oproj;; Convert from UTM zone 11 to UTM zone 12;oproj2 = ENVI_PROJ_CREATE (/utm,zone=12)ENVI_CONVERT_PROJECTION_COORDINATES, $ oxmap, oymap, oproj, $ oxmap2, oymap2, oproj2
See Also
ENVI_GET_PROJECTIONENVI_MAP_INFO_CREATEENVI_PROJ_CREATE
ENVI_CONVERT_PROJECTION_COORDINATES ENVI Reference Guide
Chapter 2: ENVI Routines 177
ENVI_CREATE_ROI
This function is used to create a new ROI and return its ROI ID. You can add points to the ROI using the procedure ENVI_DEFINE_ROI.
Syntax
Result = ENVI_CREATE_ROI([, COLOR=integer] [, FILL_MODE=integer] [, FILL_ORIEN=integer] [, FILL_SPACING=floating point] [, NAME=string], NL=value [, /NO_UPDATE], NS=value)
Keywords
COLOR (optional)
Use this keyword to specify the graphics color index of the ROI. The default value is 2.
FILL_MODE (optional)
Use this optional integer keyword to specify the IDL fill style for polygon ROIs. The default value is 1 (solid fill).
FILL_ORIEN (optional)
Use this optional integer keyword to specify the rotation of fill for polygon ROIs. This value must be greater than 1, and it is only used when the FILL_MODE value is greater than 1. The default value is 45.
FILL_SPACING (optional)
Use this optional floating-point keyword to specify the spacing of fill for polygon ROIs. This keyword is only used when FILL_MODE is greater than 1. The default value is 0.1.
NAME (optional)
Use this keyword to specify a string variable for the ROI name. The default string is New Region.
NL
Use this keyword to specify the ROI spatial line dimension tied to the ROI.
NO_UPDATE (optional)
Set this keyword to indicate that the newly created ROI should not appear in the ROI Tool dialog.
NS
Use this keyword to specify the ROI spatial sample dimension tied to the ROI.
ENVI Reference Guide ENVI_CREATE_ROI
178 Chapter 2: ENVI Routines
Example
Use ENVI_CREATE_ROI to create a new ROI. Then, add a polygon to the ROI using ENVI_DEFINE_ROI.
roi_id = envi_create_roi(color=4, name='Test roi', ns=512, nl=512)xpts = [100, 200, 200, 100, 100]ypts = [100, 100, 200, 200, 100]envi_define_roi, roi_id, /polygon, xpts=xpts, ypts=ypts
See Also
ENVI_DEFINE_ROIENVI_GET_ROI_DATAENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_IDSENVI_RESTORE_ROISENVI_SAVE_ROIS
ENVI_CREATE_ROI ENVI Reference Guide
Chapter 2: ENVI Routines 179
ENVI_CUBE_3D_DOIT
Use this procedure to build a 3D image cube.
Syntax
ENVI_DOIT, 'ENVI_CUBE_3D_DOIT', BORDER=integer, CT=array, DIMS=array, FID=file ID, /IN_MEMORY, OUT_NAME=string, POS=array, R_FID=variable, RGB_POS=value, SCALE=floating point
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
POS
R_FID
BORDER
Use this keyword to specify the number of border pixels surrounding the image cube.
CT
Use this keyword to specify the color table used for the spectral-profile colors. CT is a byte array with dimensions [256, 3].
RGB_POS
Use this keyword to specify the three RGB band positions for the cube face.
SCALE
Use this keyword to specify a spectral scale factor to exaggerate or compress the spectral profile. A value greater than 1.0 exaggerates the spectral profile; a value less than 1.0 compresses the spectral profile. You must set SCALE to 1.0 if the spectral profile is not to be changed.
Example
pro example_envi_cube_3d_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files
ENVI Reference Guide ENVI_CUBE_3D_DOIT
180 Chapter 2: ENVI Routines
; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords DIMS and POS to ; use all pixles and all bands for the ; spatial and spectral parts of the cube. ; Use band 3,2,1 as the RGB bands for the ; front face of the cube. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) rgb_pos = [3,2,1] out_name = 'testimg' ; ; Set the CT keyword to the fifth color ; table from the IDL colors1.tbl file. ; openr, unit, filepath('colors1.tbl', $ sub=['resource','colors']), $ /block, /get a = assoc(unit, bytarr(256,3), 1) ct = a[4] ct[0,*] = 0 free_lun, unit ; ; Call the doit ; envi_doit, 'envi_cube_3d_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, scale=10.0, $ border=30, rgb_pos=rgb_pos, ct=ct, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI_CUBE_3D_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 181
ENVI_DEFAULT_STRETCH_CREATE
This function returns an ENVI default stretch structure, which is used to set the default stretch when displaying data from a file. Create the default stretch structure using ENVI_DEFAULT_STRETCH_CREATE and set the DEF_STRETCH keyword in the ENVI_SETUP_HEAD or ENVI_ENTER_DATA routines. Use this routine instead of directly accessing the default stretch structure.
Syntax
Result = ENVI_DEFAULT_STRETCH_CREATE([, /EQUALIZE] [, /GAUSSIAN] [, /LINEAR] [, /NONE] [, /PCT_LINEAR] [, /SQUARE_ROOT] [, VAL1=value] [, VAL2=value])
Keywords
EQUALIZE (optional)
Set this keyword to create an equalization default stretch structure. The keywords VAL1 and VAL2 are not used with this stretch.
GAUSSIAN (optional)
Set this keyword to create a Gaussian default stretch structure. Use the keyword VAL1 to specify the number of Gaussian standard deviations for the stretch. The default for VAL1 is 2. The keyword VAL2 is not used with this stretch.
LINEAR (optional)
Set this keyword to create a linear range default stretch structure. Use the keyword VAL1 to specify the minimum and VAL2 to specify the maximum values for the linear stretch range. The default values for VAL1 and VAL2 are 0 and 255, respectively.
NONE (optional)
Set this keyword to create a default stretch structure with no stretch defined. The keywords VAL1 and VAL2 are not used with this stretch.
PCT_LINEAR (optional)
Set this keyword to create a percent linear default stretch structure. Use the keyword VAL1 to specify the percentage for the stretch. The default is VAL1=0, specifying a 0% stretch.
SQUARE_ROOT (optional)
Set this keyword to create a square root default stretch structure. The keywords VAL1 and VAL2 are not used with this stretch.
VAL1 (optional)
Set this keyword according to the stretch keyword you set.
• GAUSSIAN: VAL1 is a floating-point value specifying the Gaussian standard deviation for the stretch
ENVI Reference Guide ENVI_DEFAULT_STRETCH_CREATE
182 Chapter 2: ENVI Routines
• LINEAR: VAL1 is a floating-point value specifying the minimum value for the stretch range
• PCT_LINEAR: VAL1 is a long integer, 0 through 100, specifying the percent of the stretch
Do not use VAL1 when you set the keywords EQUALIZE, NONE, or SQUARE_ROOT.
VAL2 (optional)
Use this keyword only when you set the LINEAR keyword. Set VAL2 to a floating-point value, specifying the maximum value for the stretch range. Do not use VAL2 for any other types of stretches.
Examples
The following example creates a default stretch structure for a 2% linear stretch:
def_stretch = ENVI_DEFAULT_STRETCH_CREATE(/PCT_LINEAR, VAL1=2)
The next example creates a default stretch structure for a linear stretch between 100 and 200:
def_stretch = ENVI_DEFAULT_STRETCH_CREATE(/LINEAR, VAL1=100, VAL2=200)
See Also
ENVI_ENTER_DATAENVI_SETUP_HEAD
ENVI_DEFAULT_STRETCH_CREATE ENVI Reference Guide
Chapter 2: ENVI Routines 183
ENVI_DEFINE_MENU_BUTTON
Use this procedure to add menu items (buttons) to the ENVI menu system from a user-defined procedure in a .pro or .sav file within the save_add directory. The .pro or .sav file must contain a procedure named filename_define_buttons, where filename is the name of that file. For instance, if the file in the save_add directory is named my_process.pro, a procedure named my_process_define_buttons.pro should be in that file to allow you to add buttons to the ENVI menu system. The filename_define_buttons procedure has only one argument and no keywords, as shown in the following example code:
PRO my_process_define_buttons, buttonInfo;; Define Buttons with ENVI_DEFINE_MENU_BUTTON;END
The filename_define_buttons procedure is used to call the ENVI_DEFINE_MENU_BUTTON procedure, which enables you to define a new button. The ENVI_DEFINE_MENU_BUTTON procedure has one argument and several keywords that include information on where the new button is located in the ENVI menu system. The following figure and comments show an example of button location terminology in the ENVI menu system.
The Basic Tools menu is a button containing a submenu. It is also the parent button of Resize Data (Spatial/Spectral), Subset Data via ROIs, etc. Resize Data (Spatial/Spectral) is a child button of Basic Tools. Statistics is a sibling button to Resize Data (Spatial/Spectral), Subset Data via ROIs, etc. Statistics is also a parent button because it contains a submenu.
Syntax
ENVI_DEFINE_MENU_BUTTON, ButtonInfo [, /DISPLAY], EVENT_PRO=string, /MENU, UVALUE=string [, POSITION=long integer or string] [, REF_INDEX=long integer] [, REF_UVALUE=variable], REF_VALUE=string [, SEPARATOR={0 | 1 | -1}] [, /SIBLING], VALUE=string
Figure 10-1: Menu Location Example in the ENVI Main Menu Bar
ENVI Reference Guide ENVI_DEFINE_MENU_BUTTON
184 Chapter 2: ENVI Routines
Arguments
ButtonInfo
This is a structure containing information about the new button. This argument must be the same as the argument used for the <filename>_define_buttons procedure.
WarningThe value of the argument is defined by ENVI and should not be modified.
Keywords
DISPLAY (optional)
Set this keyword to add the new button to the display group menu bar, instead of to the ENVI main menu bar (default).
EVENT_PRO (optional)
Use this keyword to specify a string containing the name of the event handling procedure for the new button, which is called when you select the new button. If you set the MENU keyword, the EVENT_PRO keyword is not required.
MENU (optional)
Set this keyword to indicate the new button has a submenu, making it a parent button. You are not required to specify a value for the UVALUE keyword if you set the MENU keyword. By default, the MENU keyword is not set.
POSITION (optional)
Use this keyword to specify the location of the new button relative to the reference button, which is specified with the REF_VALUE keyword.
NoteYou cannot add a new button after Exit in the File option of the ENVI main menu bar.
If the new button is a sibling (/SIBLING) to the reference button, then you can set the position to one of the following values:
• 'before': String value indicating the new button is placed just before the reference button
• 'after': String value indicating the new button is placed just after the reference button
• negative number: Long integer indicating the new button is placed a relative distance before the reference button. A value of 0 is not valid in this case. For example, a value of –1 is equivalent to a value of 'before'. A value of –2 places the new button before the reference button, with one sibling between the new and the reference button.
• positive number: Long integer indicating the new button is placed a relative distance after the reference button. A value of 0 is not valid in this case. A value of 1 is
ENVI_DEFINE_MENU_BUTTON ENVI Reference Guide
Chapter 2: ENVI Routines 185
equivalent to a value of 'after'. A value of 2 places the new button after the reference button, with one sibling between the new and the reference button.
If the new button is a child of the reference button (SIBLING=0, default), then you can set the POSITION keyword to one of the following values:
• 'first': String value indicating the new button is placed as the first child
• 'last': String value indicating the new button is placed as the last child
• -1, 0, or a positive number: Long integer indicating the index of the child button relative to it parent. For example, POSITION=0 represents the first child, POSITION=1 represents the second child, and so forth. POSITION= –1 is equivalent to 'last', which places the new button as the last child (no matter how many children already exist).
The default value is POSITION='after' for a sibling button and POSITION='last' for a child button.
REF_INDEX (optional)
Use this keyword to indicate the index of the button used as a reference if the name specified for the REF_VALUE keyword is not unique. For example, the Preprocessing button appears in two places in the ENVI menu system, in the Basic Tools and the Spectral menus. The index value is based on the sequential order of the button names in the envi.men file. REF_INDEX=0 represents the first instance in the file, REF_INDEX=1 represents the second instance, and so forth. If the value of REF_INDEX is greater than the number of instances in the file, the first instance of the button is used as the reference button. The default is REF_INDEX=0.
REF_UVALUE (optional)
Use this keyword to specify a reference button by its user-defined value.
NoteSpecifying an existing ENVI button name with the REF_VALUE keyword may not always produce a match because you can edit the envi.men file and it may have been changed for a given installation (for example, when translating the button names into a different language). However, a user-defined value for this button does not change. The REF_UVALUE keyword enables you to specify this user-defined value so it can be used as a backup for the REF_VALUE when it does not match any existing buttons. However, the REF_UVALUE keyword does not work for parent buttons because submenus do not produce events.
REF_VALUE
Use this keyword to specify a string containing the name of the reference button, which is already located in the ENVI menu system.
SEPARATOR (optional)
Set this keyword to place a separator before the new button. By default, SEPARATOR=0. To place the separator after the new button, set SEPARATOR to -1.
SIBLING (optional)
ENVI Reference Guide ENVI_DEFINE_MENU_BUTTON
186 Chapter 2: ENVI Routines
Set this keyword to indicate that the new button is a sibling of the reference button, which is specified with the REF_VALUE keyword. By default, a new button is a child of the reference button unless the SIBLING keyword is set. However, if the reference button is not a parent button (i.e., it does not contain a submenu), you do not need to set this keyword because the new button is always a sibling to that reference button.
UVALUE
Use this keyword to specify a string containing information you want to maintain about the new button. This string is passed to the event handling procedure for the new button. If the MENU keyword is set, you are not required to specify a value for the UVALUE keyword.
NoteIn general, the user-defined value of a widget can be of any type, but for this procedure, the value for the UVALUE keyword must be a string.
VALUE
Use this keyword to specify a string containing the name of the new button you want to create. The name specified for the VALUE keyword is also used as the label for the new button.
Examples
The following examples are for a fictitious file named my_process.pro.
Example 1
The first example adds four new buttons. The My Menu parent button is placed in the ENVI main menu bar just after Basic Tools and just before Classification. This new button contains three children: Option 1, Option 2, and Option 3.
PRO my_process_define_buttons, buttonInfo;; Basic Tools ->; My Menu ->; Option 1; Option 2; --------; Option 3; Classification ->;ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'My Menu', $
/MENU, REF_VALUE = 'Basic Tools', /SIBLING, POSITION = 'after'ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Option 1', $
UVALUE = 'option 1', EVENT_PRO = 'my_process_event', $REF_VALUE = 'My Menu', POSITION = 'last'
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Option 2', $UVALUE = 'option 2', EVENT_PRO = 'my_process_event', $ REF_VALUE = 'My Menu', POSITION = 'last'
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Option 3', $UVALUE = 'option 3', EVENT_PRO = 'my_process_event', $REF_VALUE = 'My Menu', POSITION = 'last', /SEPARATOR
END
ENVI_DEFINE_MENU_BUTTON ENVI Reference Guide
Chapter 2: ENVI Routines 187
Example 2
The previous example used string values for the POSITION keyword. This example creates the same buttons, but it uses integer values for the POSITION keyword.
PRO my_process_define_buttons, buttonInfo
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'My Menu', $/MENU, REF_VALUE = 'File', /SIBLING, POSITION = 2
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Option 2', $UVALUE = 'option 2', EVENT_PRO = 'my_process_event', $REF_VALUE = 'My Menu', POSITION = 0
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Option 1', $UVALUE = 'option 1', EVENT_PRO = 'my_process_event', $REF_VALUE = 'Option 2', REF_UVALUE = 'option 1', POSITION = -1
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Option 3', $UVALUE = 'option 3', EVENT_PRO = 'my_process_event', $REF_VALUE = 'Option 2', REF_UVALUE = 'option 1', POSITION = 1, $/SEPARATOR
END
Example 3
The following example shows how to add new buttons as children to the Preprocessing buttons under Basic Tools and Spectral.
PRO my_process_define_buttons, buttonInfo
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'New Tools', $/MENU, REF_VALUE = 'Preprocessing', REF_INDEX = 0, $POSITION = 'last'
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Tool 1', $UVALUE = 'tool 1', EVENT_PRO = 'my_process_event', $REF_VALUE = 'New Tools', POSITION = -1
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Tool 2', $UVALUE = 'tool 2', EVENT_PRO = 'my_process_event', $REF_VALUE = 'New Tools', POSITION = -1
;ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'New Tools', $
/MENU, REF_VALUE = 'Preprocessing', REF_INDEX = 1, $POSITION = 'last'
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Tool 1', $UVALUE = 'tool 1', EVENT_PRO = 'my_process_event', $REF_VALUE = 'New Tools', REF_INDEX = 1, POSITION = -1
ENVI_DEFINE_MENU_BUTTON, buttonInfo, VALUE = 'Tool 2', $UVALUE = 'tool 2', EVENT_PRO = 'my_process_event', $REF_VALUE = 'New Tools', REF_INDEX = 1, POSITION = -1
END
ENVI Reference Guide ENVI_DEFINE_MENU_BUTTON
188 Chapter 2: ENVI Routines
ENVI_DEFINE_ROI
Use this procedure to define point, polyline, and polygon objects in an ROI. Each ROI can be composed of multiple and/or mixed objects. For example, a single ROI may have 100 individual points and three polygons. Using a ROI_ID returned from ENVI_CREATE_ROI, each call to ENVI_DEFINE_ROI adds one object to the ROI definition (multiple points may be added with a single call). Once you create an ROI, you can use it in processing routines or save it to an ROI file.
Syntax
ENVI_DEFINE_ROI, ROI_ID [, /NO_UPDATE] [, /POINT] [, /POLYGON] [, /POLYLINE], XPTS=array, YPTS=array
Arguments
ROI_ID
This is a single ID returned from the function ENVI_CREATE_ROI or ENVI_GET_ROI_IDS.
Keywords
NO_UPDATE (optional)
Set this keyword to indicate the newly created ROI should not appear in the ROI Tool dialog.
POINT (optional)
Set this keyword to indicate that the x and y arrays define a set of points. When you set POINT, you cannot set POLYLINE and POLYGON.
POLYLINE (optional)
Set this keyword to indicate that the x and y arrays define a polyline. A polyline is a series of x,y points that are connected with a straight line. You can define only one polyline with each call to ENVI_DEFINE_ROI. When you set POLYLINE, you cannot set POINT and POLYGON.
POLYGON (optional)
Set this keyword to indicate that the x and y arrays define a polygon. A polygon is a closed area that is defined by a series of connected x,y points. In order to properly close the polygon, the first and last point in XPTS and YPTS must be the same. When you set POLYGON, you cannot set POINT and POLYLINE.
XPTS
Use this keyword to specify an array of x points of the specified type. XPTS is in file coordinates. You must set one of the keywords POINT, POLYLINE, or POLYGON, to indicate the type of XPTS.
ENVI_DEFINE_ROI ENVI Reference Guide
Chapter 2: ENVI Routines 189
YPTS
Use this keyword to specify an array of y points of the specified type. YPTS is in file coordinates. You must set one of the keywords POINT, POLYLINE, or POLYGON, to indicate the type ‘of YPTS.
Example
This example creates a square polygon ROI to display on the bhtmref.img image. This example uses the following files found in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number):
• bhtmref.img
• bhtmref.hdr
First, start ENVI and open the file bhtmref.img. Issue the ENVI_SELECT command and select the file bhtmref.img. Next, use ENVI_CREATE_ROI and the returned FID to create an ROI with the file attributes associated with bhtmref.img. Now, define the square polygon points and add this object to the ROI using ENVI_DEFINE_ROI. You can overlay the resulting ROI on the file bmtmref.img.
;; Choose the bhtmref.img file;ENVI_SELECT, fid=fid;; Get the dimensions for this; file and create an ROI;ENVI_FILE_QUERY, fid, dims=dimsroi_id = ENVI_CREATE_ROI(ns=ns, nl=nl, $ color=4, name='Square');; Define the square and add; the polygon object to the ROI;xpts = [100, 200, 200, 100, 100]ypts = [100, 100, 200, 200, 100]ENVI_DEFINE_ROI, roi_id, /polygon, $ xpts=xpts, ypts=ypts
See Also
ENVI_CREATE_ROIENVI_GET_ROI_DATAENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_IDSENVI_RESTORE_ROISENVI_SAVE_ROIS
ENVI Reference Guide ENVI_DEFINE_ROI
190 Chapter 2: ENVI Routines
ENVI_DELETE_ROIS
Use this procedure to delete ROIs from within ENVI. The procedure accepts a list of ROIs to delete, or optionally deletes all ROIs.
Syntax
ENVI_DELETE_ROIS [, ROI_IDS] [, /ALL]
Arguments
ROI_IDS
This optional argument represents the individual ROI IDs to delete. This value is returned from ENVI_GET_ROI_IDS or ENVI_CREATE_ROI.
Keywords
ALL (optional)
Set this keyword to delete all ROIs, in which case you do not use the ROI_IDS argument.
Example
roi_ids = envi_get_roi_ids()envi_delete_rois, roi_ids
ENVI_DELETE_ROIS ENVI Reference Guide
Chapter 2: ENVI Routines 191
ENVI_DISP_QUERY
This procedure queries and returns display information from a display group.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
ENVI_DISP_QUERY, DN, COLOR={0 | 2 | 8}, FID=file ID, NL=variable, NS=variable, POS=array [, /REBIN=variable] [, /W1=variable] [, /X0=value], /XDS=variable [, /Y0=value], /YDS=variable [, /ZFACT=variable]
Arguments
DN
This is the display number corresponding to an open display group.
Keywords
COLOR
Use this keyword to specify a named variable that contains the display color information. The valid values for COLOR are as follows:
• 0: Gray scale image
• 2: Classification image
• 8: Three-band image
FID
Use this keyword to specify a named variable that contains the file ID for the open file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a three-element array of long integers. For gray scale and classification images, only the first array element is valid. For RGB displays, each FID element relates to the red (0), green (1), and blue (2) bands. An invalid file ID is specified as -1.
NL
Use this keyword to specify a named variable that contains the number of lines in the file.
NS
Use this keyword to specify a named variable that contains the number of samples in the file.
POS
Use this keyword to specify a named variable that contains the band positions of the display data. POS is a three-element array of long integers. For gray scale and classification images,
ENVI Reference Guide ENVI_DISP_QUERY
192 Chapter 2: ENVI Routines
only the first array element is valid. For RGB displays, each POS array element relates to the red (0), green (1), and blue (2) bands.
REBIN (optional)
Use this keyword to specify a named variable that contains the resize factor currently being used in the Scroll window. If DN is valid, the resulting variable (“resize” in this case) will be a floating-point number. If the image display does not have a Scroll window (i.e., the entire image fits into the full-resolution Image window), but you use the REBIN keyword, a meaningless REBIN value is still returned.
W1 (optional)
Use this keyword to specify a named variable that contains the IDL window IDs for the Image, Zoom, and Scroll windows. If DN is valid, the resulting variable (“win” in this case) is a three-element array of long integers, where:
• WIN[0]: Window ID of the Image window
• WIN[1]: Window ID of the Zoom window
• WIN[2]: Window ID of the Scroll window
NoteIf there is no scroll window in the specified ENVI display, WIN[2] may be equal to 0 or -1, or it may contain the window ID of an invalid display.
X0 (optional)
Use this keyword to specify the x position of the upper-left pixel of the Image window in file coordinates (zero-based numbers).
XDS
Use this keyword to specify a named variable that contains the x display size in pixels for the display group windows. XDS is a three-element array of long integers that correspond to the Image, Zoom, and Scroll windows, respectively.
Y0 (optional)
Use this keyword to specify the y position of the upper-left pixel of the Image window in file coordinates (zero-based numbers).
YDS
Use this keyword to specify a named variable that contains the x display size in pixels for the display group windows. YDS is a three-element array of long integers that correspond to the Image, Zoom, and Scroll windows, respectively.
ZFACT (optional)
Use this keyword to specify a named variable that contains the zoom factor currently being used in the Zoom window. If DN is valid, the resulting variable (“zoom” in this case) is a two-element array of integers, where:
• ZOOM[0]: Zoom factor for the full-resolution Image window, which is always 1.
ENVI_DISP_QUERY ENVI Reference Guide
Chapter 2: ENVI Routines 193
• ZOOM[1] : Current zoom factor for the Zoom window.
Example
envi_disp_query, dn, xds=xds, yds=yds, fid=fid, $color=color
See Also
ENVI_FILE_QUERY
ENVI Reference Guide ENVI_DISP_QUERY
194 Chapter 2: ENVI Routines
ENVI_DISPLAY_BANDS
Use this procedure to display a gray scale or RGB image in the current display group. You can optionally create a new display group. An interactive ENVI session is required to run this procedure.
Syntax
ENVI_DISPLAY_BANDS, FID, POS [, IMAGE_OFFSET=array] [, IMAGE_SIZE=array] [, /NEW] [, /SCROLL_HIDE] [, SCROLL_OFFSET=array] [, SCROLL_REBIN=floating point] [, WINDOW_STYLE={0 | 1 | 2 | 3}] [, ZOOM_FACTOR=integer] [, /ZOOM_HIDE] [, ZOOM_OFFSET=array] [, ZOOM_SIZE=array]
Arguments
FID
This is a one- or three-element array of long integers representing the file IDs of the files for each of the gray scale or RGB bands to display. When FID is a three-element array, the bands represent the red, green, and blue channels, respectively. All of the files listed in FID must have the same number of samples and lines.
POS
This is a one- or three-element array of long integers representing band positions. Elements of POS are paired with the elements of FID.
Keywords
IMAGE_OFFSET (optional)
Use this keyword to specify a two-element array of long integers representing the x and y offset in screen pixels, respectively, of the Image window.
IMAGE_SIZE (optional)
Use this keyword to specify a two-element array of long integers representing the x and y size in screen pixels, respectively, of the Image window.
NEW (optional)
Set this keyword to create a new display group. The default is to use the current display group. If no window exists, a new window is created.
SCROLL_REBIN (optional)
Use this keyword to specify the initial resize factor for the Scroll window. SCROLL_REBIN is a floating-point number greater than 1.0. The size of the Scroll window is determined as follows:
x = number of samples of input image / SCROLL_REBIN
y = number of lines of input image / SCROLL_REBIN
ENVI_DISPLAY_BANDS ENVI Reference Guide
Chapter 2: ENVI Routines 195
SCROLL_OFFSET (optional)
Use this keyword to specify a two-element array of long integers representing the x and y offset in screen pixels, respectively, of the Scroll window.
SCROLL_HIDE
Set this keyword to initially hide the Scroll window.
WINDOW_STYLE (optional)
Set this keyword to one of the following values to configure the style for new windows (created when you set the keyword NEW).
• 0: Image/Scroll/Zoom
• 1: Scroll/Zoom
• 2: Image
• 3: Zoom
The default is to use the window style specified in Preferences.
ZOOM_FACTOR (optional)
Use this keyword to specify the initial zoom factor for the Zoom window.
ZOOM_HIDE (optional)
Set this keyword to initially hide the Zoom window.
ZOOM_OFFSET (optional)
Use this keyword to specify a two-element array of long integers representing the x and y offset in screen pixels, respectively, of the Zoom window.
ZOOM_SIZE (optional)
Use this keyword to specify a two-element array of long integers representing the x and y size in screen pixels, respectively, of the Zoom window.
Example
The following example displays the first three bands of a file, specified by FID, as an RGB combination in a new display window.
envi_display_bands, [fid,fid,fid], [0,1,2], /new
See Also
ENVI_DISP_QUERY
ENVI Reference Guide ENVI_DISPLAY_BANDS
196 Chapter 2: ENVI Routines
ENVI_DOIT
The ENVI_DOIT procedure is the interface for all of the ENVI processing routines (those that end with _DOIT). Each _DOIT is a string argument to ENVI_DOIT with specific keywords that follow.
Syntax
ENVI_DOIT, 'Routine_Name' [, /NO_CATCH] [, /NO_REALIZE]
Arguments
Routine_Name
Routine_Name is a string variable specifying the processing routine to execute. ENVI commonly refers to processing routines as “DOIT.” Many of the internal ENVI processing routines are available to you in batch mode. The value of Routine_Name should be any valid _DOIT routine in ENVI. Keywords specific to each of these routines are described in this ENVI Reference Guide.
Keywords
NO_CATCH (optional)
Set this keyword to disable the ENVI catch mechanism, which provides a generalized method for handling exceptions and errors. By disabling the ENVI catch mechanism, you have the option to add your own. If you do not use a catch mechanism and an error occurs, ENVI stops program execution, prints an error message, and reverts control to the command line. The ENVI session (interactive or batch) must be continued manually from the command line. See the IDL procedure CATCH for instructions on adding your own catch mechanism. Use NO_CATCH only with the procedure ENVI_DOIT.
NO_REALIZE (optional)
Set this keyword to prevent the Available Bands List from displaying if a new output file is created at the end of the Routine_Name process. If the Available Bands List is already realized, this keyword has no effect. Some processing routines (such as ENVI_STATS_DOIT) produce dialogs, but they do not produce output files. The NO_REALIZE keyword only applies to cases resulting in an output file. Otherwise, this keyword is ignored.
Example
The following example generates statistics on the file bhtmref.img. This example uses the following files found in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number):
• bhtmref.img
• bhtmref.hdr
ENVI_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 197
First, ENVI is initialized in batch mode, and the batch log file is set to batch.txt. Next, the file bmtmref.img opens, and ENVI_STATS_DOIT is used to calculate basic statistics. The procedure ENVI_STATS_DOIT is the string argument to ENVI_DOIT. The keywords to ENVI_STATS_DOIT are listed in the call to ENVI_DOIT. After the statistics are completed, the mean value is printed.
pro example_envi_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Get the dimensions and # bands ; for the input file. ; envi_file_query, fid, dims=dims, nb=nb ; ; Set the pos to calculate ; statistics for all spectral data in the file. ; pos = lindgen(nb) ; ; Calculate the basic statistics and the ; histogram for the input data file. Print ; out the calculated information. ; envi_doit, 'envi_stats_doit', fid=fid, pos=pos, $ dims=dims, comp_flag=1, mean=mean ; print, 'Mean' , mean ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVIENVI_BATCH_EXITENVI_BATCH_INIT
ENVI Reference Guide ENVI_DOIT
198 Chapter 2: ENVI Routines
ENVI_ENTER_DATA
Use this routine to enter image data from an array into ENVI memory. ENVI_ENTER_DATA internally calls ENVI_SETUP_HEAD and registers the bands in the Available Bands List. This routine automatically creates an ENVI header file for the image (which is also stored in memory), and it returns the FID for the in-memory image. Once the image appears in the Available Bands List, you can use it like any other ENVI image and even save it to disk by selecting File Save File As ENVI Standard from the ENVI main menu bar.
Syntax
ENVI_ENTER_DATA, Data [, BBL=array] [, BNAMES=string array] [, CLASS_NAMES=string array] [, DATA_GAINS=array] [, DATA_IGNORE_VALUE=variable] [, DATA_OFFSET=array] [, DEF_STRETCH=value] [, DESCRIP=string] [, FILE_TYPE=integer] [, FUNC_COMPLEX={0 | 1 | 2 | 3 | 4}] [, FWHM=array] [, GEO_POINTS=array] [, INFO=value] [, INHERIT=value] [, LOOKUP=array] [, MAP_INFO=value] [, NUM_CLASSES=integer] [, PIXEL_SIZE=array] [, R_FID=variable] [, REFLECTANCE_SCALE_FACTOR=variable] [, SENSOR_TYPE=integer] [, SPEC_NAMES=string array] [, UNITS=integer] [, WAVELENGTH_UNIT={0 | 1 | 2 | 3 | 4 | 5 | 6}] [, WL=array] [, XSTART=integer] [, YSTART=integer] [, ZPLOT_AVERAGE=array] [, ZPLOT_TITLES=string array] [, ZRANGE=array]
Arguments
Data
This is a 2D or 3D data array of type byte, integer, unsigned integer, long integer, unsigned long integer, long 64-bit integer, unsigned long 64-bit integer, floating point, double precision, complex, or double complex. The data must be in BSQ format and have the dimensions [samples, lines] or [samples, lines, bands].
NoteThe array is incorporated into the ENVI session directly, rendering the variable undefined after the call to ENVI_ENTER_DATA. If you wish to use the array after the call to ENVI_ENTER_DATA, first copy the array and set the Data argument equal to the copy.
Keywords
BBL (optional)Use this keyword to specify an array of ones and zeros representing the good and bad bands, respectively. The number of elements in BBL must be equal to the number of bands in the image.
BNAMES (optional)
ENVI_ENTER_DATA ENVI Reference Guide
Chapter 2: ENVI Routines 199
Use this keyword to specify the band names assigned to the data. BNAMES is a string array (with num_bands elements) of band names. The default band names are [band 1, band 2], etc.
CLASS_NAMES (optional)Use this keyword to specify a string array of class names for classification images. The first element (Class 0) is “Unclassified.” Only use CLASS_NAMES if the result is a classification image, in which case this keyword is required. If the result is not a classification image, this keyword is optional.
DATA_GAINS
Use this keyword to specify a named variable that contains an array of gains for each band in the dataset. DATA_GAINS can be used in conjunction with DATA_OFFSETS in ENVI's general purpose utility Apply Gain and Offset.
DATA_IGNORE_VALUE (optional)Use this keyword to specify a named variable that contains a scalar number representing the data value to ignore in the dataset. If you set DATA_IGNORE_VALUE, it is the same type as the input dataset, and an undefined ignore value is represented by the double-precision number 1e-34. Currently, this value is used only in user-written ENVI code.
DATA_OFFSET (optional)Use this keyword to specify a named variable that contains an array of offsets for each band in the dataset. DATA_OFFSETS can be used in conjunction with DATA_GAINS in ENVI's general purpose utility Apply Gain and Offset.
DEF_STRETCH (optional)Use this keyword to specify the default stretch information. Set DEF_STRETCH equal to the value returned from ENVI_DEFAULT_STRETCH_CREATE.
DESCRIP (optional)Use this keyword to specify a text description of the data, or of the type of processing performed.
FILE_TYPE (optional)Use this keyword to specify an integer value indicating the file type. See “ENVI_FILE_TYPE” on page 228 for details on how to determine the integer value of a file type.
FUNC_COMPLEX (optional)Set this keyword to one of the following values to specify the complex lookup function that determines how to display complex data.
• 0: Power (default): The natural log of the magnitude
• 1: Magnitude:
• 2: Real: The real portion of the complex number
• 3: Imaginary: The imaginary part of the complex number
real 2 inaryimag 2+
ENVI Reference Guide ENVI_ENTER_DATA
200 Chapter 2: ENVI Routines
• 4: Phase:
NoteOnly set this keyword if the IDL data type of the image is complex or double-precision complex.
FWHM (optional)Use this keyword to specify an array of floating-point values representing full-width-half-maximum responses for each band. The number of elements in this array is equal to the number of bands in the image.
GEO_POINTS
Use this keyword to specify a 16-element array of double-precision, floating-point values representing geographic coordinates for the upper-left, upper-right, lower-left, and lower-right corners of the image. The array consists of four groups of x and y pixel locations and their corresponding latitude and longitude values with the form [x, y, lat, lon]. South latitudes and west longitudes have negative values. The array is defined as follows:
• GEO_POINTS[0:3]: Upper left
• GEO_POINTS[4:7]: Upper right
• GEO_POINTS[8:11]: Lower left
• GEO_POINTS[12:15]: Lower right
INFO (optional)Use this keyword to store information that you can pass to your spatial and spectral readers. INFO is retrieved from ENVI_FILE_QUERY using the keyword H_INFO, which is a handle to the data. Use HANDLE_VALUE and the handle H_INFO to retrieve the data for INFO.
INHERIT (optional)Use this keyword to specify the file inheritance. Set INHERIT equal to the value returned from ENVI_SET_INHERITANCE.
LOOKUP (optional)Use this keyword to specify an array of long integers representing class RGB values for classification images. The LOOKUP array contains an RGB triplet for each class specified by the keyword NUM_CLASSES. The dimensions of the array are [3, num_classes], and the RGB triplet is ordered [r, g , b]. You must set LOOKUP when entering a classification image.
MAP_INFO (optional)Use this keyword to specify map information. Set MAP_INFO equal to the value returned from ENVI_MAP_INFO_CREATE.
NUM_CLASSES (optional)Use this keyword to specify the number of classes for classification images. Remember to include Class 0 (“Unclassified”) in the number of classes. You only need to set NUM_CLASSES when entering a classification image.
arc inaryimagreal
--------------------------tan
ENVI_ENTER_DATA ENVI Reference Guide
Chapter 2: ENVI Routines 201
PIXEL_SIZE (optional)Use this keyword to specify the pixel size of images that are not georeferenced. PIXEL_SIZE is a two-element array of floating-point values representing the x and y pixel sizes, respectively.
R_FID (optional)See “Common Keywords” on page 34 for a definition of this keyword.
REFLECTANCE_SCALE_FACTOR (optional)Use this keyword to specify a named variable that contains a single scalar number used to convert the input data into reflectance. For example, REFLECTANCE_SCALE_FACTOR would be used to convert integer scaled reflectance data into floating point [0, 1] reflectance values.
SENSOR_TYPE (optional)Use this keyword to specify an integer value indicating the sensor type. See “ENVI_SENSOR_TYPE” on page 365 for details on how to determine the integer value of a sensor type.
SPEC_NAMES (optional)Use this keyword to specify a string array of spectral library names. You only need to set SPEC_NAMES when entering spectral library files.
UNITS (optional)Use this keyword to specify the PIXEL_SIZE units for images that are not georeferenced. UNITS is an integer value returned from ENVI_TRANSLATE_PROJECTION_UNITS. Georeferenced images do not use this value. Instead, they use the pixel size and units contained in the map information structure.
WAVELENGTH_UNIT (optional)Use this keyword to specify a named variable that contains one of the following values, indicating the wavelength units.
• 0: Micrometers
• 1: Nanometers
• 2: Wavenumber
• 3: GHz
• 4: MHz
• 5: Index
• 6: Unknown
WL (optional)Use this keyword to specify an array of wavelength values. The number of elements is equal to the number of bands.
XSTART (optional)
ENVI Reference Guide ENVI_ENTER_DATA
202 Chapter 2: ENVI Routines
Use this keyword to specify the x starting sample for the first pixel in the file. The default value is 0. Use XSTART in conjunction with YSTART to preserve the spatial reference for subsetted files. When processing a file, you typically set the XSTART of the output file to the XSTART of the input file plus the value of DIMS[1] (the starting sample).
YSTART (optional)Use this keyword to specify the y starting sample for the first pixel in the file. The default value is 0. Use YSTART in conjunction with XSTART to preserve the spatial reference for subsetted files. When processing a file, you typically set the YSTART of the output file to the YSTART of the input file plus the value of DIMS[3] (the starting line).
ZPLOT_AVERAGE (optional)Use this keyword to specify a two-element array of long integers representing the x and y window size (in pixels) for the Z Profile. The window size must be a value of 1 or greater. The Z Profile is formed from the average of the profiles within the specified window. The default window size is [1, 1].
ZRANGE (optional)Use this keyword to specify a 2D array for the lower and upper range used by default in spectral plots.
ZPLOT_TITLES (optional)Use this keyword to specify a two-element string array for the x and y plot titles. The default x title is “Band Number” for images with no wavelength information and “Wavelength” for images with wavelength information. The default y axis title is “Value.”
Examples
The following example generates a 256 x 256 byte ramp using the function BINDGEN. You enter this array into ENVI using the ENVI_ENTER_DATA procedure. This is the simplest use of ENVI_ENTER_DATA.
data = BINDGEN(256,256)ENVI_ENTER_DATA, data
The following example creates two classes (plus the “Unclassified” class) from the ramp image and enters the resulting classification image into ENVI. The “Unclassified” class is black [0, 0, 0], the first class is red [255, 0, 0], and the second class is yellow [255, 255, 0]. The classification image has the description “Example Classification Image” and the band name “Ramp Classification.”
;; Create a 2D ramp and then classify all values ; from 20 to 100 in the first class (classification ; data value equal to one) and classify all values ; from 101 to 220 into the second class ; (classification data value equal to two);data = BINDGEN(256,256)class = BYTE((data ge 20 and data le 100) + $ 2B * (data ge 101 and data le 220));; Create the classification information
ENVI_ENTER_DATA ENVI Reference Guide
Chapter 2: ENVI Routines 203
;class_names = ['Unclassified','Red','Yellow']lookup = [[0,0,0],[255,0,0],[255,255,0]]bnames = ['Ramp Classification']descrip = 'Example Classification Image'file_type = ENVI_FILE_TYPE('ENVI Classification');; Enter the data into ENVI;ENVI_ENTER_DATA, class, num_classes=3, $ class_names=class_names, lookup=lookup, $ file_type=file_type, bnames=bnames, $ descrip=descrip
The following example assigns a geographic projection to the ramp image with the upper-left corner at 15 degrees south, 48 degrees west, with an x and y pixel size of one arc second. The map projection is created using ENVI_MAP_INFO_CREATE, and the resulting structure uses the MAP_INFO keyword when the data are entered into ENVI.
;; First create the ramp image. The ramp image ; would actually be replaced by a real ; georeferenced image.;data = BINDGEN(256,256);; Create the item used for the projection;mc = [.5D,.5, -48,-15]ps = [1D/3600, 1D/3600]units = ENVI_TRANSLATE_PROJECTION_UNITS('Degrees')map_info = ENVI_MAP_INFO_CREATE(/geographic, $ mc=mc, ps=ps, units=units);; Enter the data into ENVI;ENVI_ENTER_DATA, data, map_info=map_info
See Also
ENVI_SETUP_HEAD
ENVI Reference Guide ENVI_ENTER_DATA
204 Chapter 2: ENVI Routines
ENVI_ENVISAT_GEOREF_DOIT
The ENVI_ENVISAT_GEOREF_DOIT procedure georeferences AATSR-, ASAR-, and MERIS-format ENVISAT data by extracting geolocation tie points from header information in the ENVISAT file.
Syntax
ENVI_DOIT, 'ENVI_ENVISAT_GEOREF_DOIT' [, BACKGROUND=value] [, DEGREE=value] [, DIMS=array], F_FID=file ID [, GCP_NAME=string], /IN_MEMORY [, OUT_BNAME=string array], OUT_NAME=string [, OUT_PROJ=structure] [, POS=array] [, R_FID=variable] [, WARP_METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}] [, ZERO_EDGE=0]
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS (optional)
IN_MEMORY
OUT_BNAME (optional)
OUT_NAME
POS (optional)
R_FID (optional)
BACKGROUND (optional)Use this keyword to specify the value for all background pixels. The default value is 0.
DEGREE (optional)Use this keyword to specify the degree of the polynomial warp when WARP_METHOD=3, 4, or 5. The default is DEGREE=1.
F_FID
Use this keyword to specify the file ID of the open file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
GCP_NAME (optional)Use this keyword to specify the name of the output file that contains the GCPs. If you do not set this keyword, the points are not saved to disk.
OUT_PROJ (optional)Use this keyword to specify the projection of the resulting data. You cannot set OUT_PROJ to the Arbitrary projection. OUT_PROJ is a projection structure returned from
ENVI_ENVISAT_GEOREF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 205
ENVI_PROJ_CREATE or ENVI_GET_PROJECTION. The default projection is derived from the input data.
WARP_METHOD (optional)Use this keyword to specify an integer value that indicates the combination of methods used to warp and resample the image.
• 0: RST with nearest neighbor (default)
• 1: RST with bilinear
• 2: RST with cubic convolution
• 3: Polynomial with nearest neighbor
• 4: Polynomial with bilinear
• 5: Polynomial with cubic convolution
• 6: Triangulation with nearest neighbor
• 7: Triangulation with bilinear
• 8: Triangulation with cubic convolution
ZERO_EDGE (optional)Set this keyword to specify that the edges outside of any triangles for the triangulation method are set to the value specified by the BACKGROUND keyword. The ZERO_EDGE keyword is only used when WARP_METHOD=6, 7, or 8.
NoteThe ZERO_EDGE keyword is set by default. To disable this, explicitly set the ZERO_EDGE keyword to 0.
Examples
The following sample lines of code show how to call this procedure to georegister a MERIS file:
fname = $"MER_FR__2PNIPA20030529_093827_000000502016_00437_06503_0047.N1"
ENVI_OPEN_DATA_FILE, fname, R_FID = fid, /ENVISATIF (fid EQ -1) THEN RETURN; MERIS files have numerous meta files associated with them. The; last meta file id points to the radiance data for Level 1 and; reflectance for level 2 products.fid = fid[N_ELEMENTS(fid) - 1]ENVI_DOIT, "ENVI_ENVISAT_GEOREF_DOIT", F_FID = fid, /IN_MEMORY
ENVI Reference Guide ENVI_ENVISAT_GEOREF_DOIT
206 Chapter 2: ENVI Routines
ENVI_EVF_CLOSE
Use this procedure to close an EVF. After you open or create an EVF, it is important that you close it using this procedure, to help conserve the IDL session’s memory.
Syntax
ENVI_EVF_CLOSE, EVF_ID
Arguments
EVF_ID
This is the EVF ID of the EVF to close. The EVF ID is returned from either ENVI_EVF_OPEN (for existing EVF files) or ENVI_EVF_DEFINE_CLOSE (for newly created EVF files).
Example
pro print_evf_record_info;; Open the EVF file can_v1.evf in the; ENVI_Install_Directory/data/vector;evf_fname = 'can_v1.evf'evf_id = envi_evf_open(evf_fname);; Get the vector information;envi_evf_info, evf_id, num_recs=num_recs, $data_type=data_type, projection=projection, $layer_name=layer_name;; Print information about each record;print, 'Number of Records: ',num_recsfor i=0,num_recs-1 do begin record = envi_evf_read_record(evf_id, i) print, 'Number of nodes in Record ' + $ strtrim(i+1,2) + ': ', n_elements(record[0,*])endfor;; Close the EVF file;envi_evf_close, evf_idend
See Also
ENVI_EVF_DEFINE_CLOSEENVI_EVF_OPENENVI_EVF_INFO
ENVI_EVF_CLOSE ENVI Reference Guide
Chapter 2: ENVI Routines 207
ENVI_EVF_DEFINE_ADD_RECORD
Use this procedure to add a record to a new EVF. It accepts points, polylines, and polygon records.
Syntax
ENVI_EVF_DEFINE_ADD_RECORD, EVF_PTR, Points [, PARTS_PTR=value] [, TYPE=value]
Arguments
EVF_PTR
This is the pointer to the new EVF, and it is returned from ENVI_EVF_DEFINE_INIT.
NoteThis pointer is not the same as an ordinary EVF ID.
Points
This argument is a two-column array of x,y points that define the vector record added to the EVF. A point record consists of a single x,y pair, a polyline record consists of multiple x,y pairs, and a polygon record is a polyline with the same first and last points. Points is an array of [2, npts] where [0,*] are the x points and [1,*] are the y points. The data type of the x,y pairs (or nodes) that define the vector record will automatically be converted into the data type of the EVF defined in the call to ENVI_EVF_DEFINE_INIT.
TipFor points in a Geographic projection, remember to arrange the points vector as [longitude, latitude] to conform to the x, y order.
Keywords
PARTS_PTR (optional)Use this keyword along with the TYPE keyword when adding points to a vector record to indicate that the polygon is a multipart polygon. Multi-part polygons are commonly used to specify holes within polygons. The PARTS_PTR keyword tells ENVI how to order the points in the file. You should specify the points of the main polygon first, followed by the points for the holes within the polygon.
Suppose you are defining a polygon with three internal holes. It has 33 points total; the first 7 points define the main polygon, the next 10 define the first hole, the next 8 define the second hole, and the last 7 define the third hole. Define PARTS_PTR as follows:
parts_ptr = [0L, 7, -17, -25, -32]
Where the negative sign denotes nodes that are multipart.
TYPE (optional)
ENVI Reference Guide ENVI_EVF_DEFINE_ADD_RECORD
208 Chapter 2: ENVI Routines
Use this keyword along with the PARTS_PTR keyword to indicate the type of multipart vector data you are working with. Following are the possible values for TYPE:
• 1: Point
• 3: Polyline
• 5: Polygon
• 8: Multi-point
Set TYPE=5 when defining multipart polygon records.
See “Creating Multipart Vectors” in the ENVI Programmer’s Guide for an example of using the TYPE and PARTS_PTR keywords to define a multipart polygon record.
Example
pro create_new_evf_file;; Create a Geographic projection; with the default datum and units.;proj = envi_proj_create(/geographic);; Define a polyline vector in Lat/Lon coordinates;polyline = [ $ -106.904, 41.5887, $ -106.821, 42.2302, $ -106.013, 42.2183, $ -105.206, 41.3749, $ -105.657, 40.5078, $ -105.835, 39.5574, $ -105.170, 38.8447, $ -104.125, 39.4862, $ -103.269, 40.0563, $ -103.269, 40.0682, $ -102.913, 39.0585, $ -102.901, 39.0585, $ -102.901, 39.0348, $ -103.210, 38.4289, $ -103.804, 38.3695 ]polyline = reform(polyline, 2, 15);; define a polygon in Lat/Lon coordinates; (note first and last coords are identical);polygon = [ $ -104.113, 41.6956, $ -103.994, 42.1589, $ -103.934, 41.6838, $ -103.471, 41.8738, $ -103.887, 41.5531, $ -103.863, 41.0185, $ -103.851, 41.0185, $ -104.041, 41.4818, $ -104.041, 41.4937, $ -104.552, 41.2680, $
ENVI_EVF_DEFINE_ADD_RECORD ENVI Reference Guide
Chapter 2: ENVI Routines 209
-104.220, 41.6006, $ -104.422, 42.0995, $ -104.113, 41.6956 ]polygon = reform(polygon, 2, 13);; define a set of discrete points in Lat/Lon coordinates;points = [ $ -106.572, 39.6643, $ -106.643, 39.5218, $ -106.453, 39.4386, $ -106.417, 39.6168, $ -106.595, 39.4386, $ -106.774, 39.2011, $ -106.215, 39.4030, $ -106.393, 39.2961, $ -106.560, 39.1892, $ -106.536, 38.9872, $ -106.227, 39.1417, $ -106.192, 39.1179, $ -106.263, 38.9635, $ -106.073, 39.1298, $ -106.073, 39.2367 ]points = reform(points, 2, 15);; Initialize the new EVF file;evf_ptr = envi_evf_define_init('sample.evf', $ projection=proj, data_type=4, $ layer_name='Sample EVF File')if (ptr_valid(evf_ptr) eq 0) then return;; add the discrete points as individual records;for i=0,14 do $ envi_evf_define_add_record, evf_ptr, points[*,i];; add the polyline record;envi_evf_define_add_record, evf_ptr, polyline;; add the polygon record;envi_evf_define_add_record, evf_ptr, polygon;; Finish defining the new EVF file and; then close the EVF file;evf_id = envi_evf_define_close(evf_ptr, /return_id)envi_evf_close, evf_id;; create an attribute file for this new EVF file;; records 1-15 are individual points; record 16 is a polyline; record 17 is a polygon;attributes = replicate( {name:'', id:0L}, 17)for i=0,14 do begin
ENVI Reference Guide ENVI_EVF_DEFINE_ADD_RECORD
210 Chapter 2: ENVI Routines
attributes[i].name = 'Sample Point ' + strtrim(i+1,2) attributes[i].id = i+1endforattributes[15].name = 'Sample Polyline'attributes[15].id = 16attributes[16].name = 'Sample Polygon'attributes[16].id = 17
envi_write_dbf_file, 'sample.dbf', attributes
end
See Also
ENVI_EVF_CLOSEENVI_EVF_DEFINE_CLOSEENVI_EVF_DEFINE_INITENVI_PROJ_CREATEENVI_WRITE_COSMOSKYMED_METADATA
ENVI_EVF_DEFINE_ADD_RECORD ENVI Reference Guide
Chapter 2: ENVI Routines 211
ENVI_EVF_DEFINE_CLOSE
Use this function to finish defining a new EVF. You must call this function before you can use the new EVF. For convenience, it optionally returns the ID of the new EVF. You must initialize the EVF using ENVI_EVF_DEFINE_INIT.
Syntax
Result = ENVI_EVF_DEFINE_CLOSE(EVF_PTR [, /RETURN_ID])
Arguments
EVF_PTR
This is a pointer to the new EVF, and it is returned from ENVI_EVF_DEFINE_INIT.
Keywords
RETURN_ID (optional)Set this keyword to return the ID of the new EVF. This keyword saves you the step of opening the new EVF using ENVI_EVF_OPEN.
Example
See the code example under ENVI_EVF_CLOSE.
See Also
ENVI_EVF_CLOSEENVI_EVF_DEFINE_ADD_RECORDENVI_EVF_DEFINE_INITENVI_PROJ_CREATEENVI_WRITE_COSMOSKYMED_METADATA
ENVI Reference Guide ENVI_EVF_DEFINE_CLOSE
212 Chapter 2: ENVI Routines
ENVI_EVF_DEFINE_INIT
Use this function to initialize a new EVF. This is a required first step in defining a new EVF. This function returns a pointer to the new EVF file that you should use when adding vector records to the file (using ENVI_EVF_DEFINE_ADD_RECORD) and when completing the new file definition (using ENVI_EVF_DEFINE_CLOSE). The function allows you to specify an output filename, layer name, data type, and projection.
NoteThe EVF pointer returned by this function is not the same as an ordinary EVF ID. When you create a new EVF, the EVF ID is returned only when the file definition is completed with the call to ENVI_EVF_DEFINE_CLOSE.
Syntax
Result = ENVI_EVF_DEFINE_INIT(Filename [, DATA_TYPE={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}] [, LAYER_NAME=string] [, PROJECTION=structure])
Arguments
Filename
This is a string that specifies an output filename for the EVF.
Keywords
DATA_TYPE (optional)Use this keyword to specify the ENVI data type of the file. DATA_TYPE uses the following IDL convention. The default data type is double-precision if you do not set DATA_TYPE.
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
LAYER_NAME (optional)
ENVI_EVF_DEFINE_INIT ENVI Reference Guide
Chapter 2: ENVI Routines 213
Use this keyword to specify a single string name for the EVF layer. Each EVF consists of only a single layer. If you do not set LAYER_NAME, the default string is 'New Layer'.
PROJECTION (optional)Use this keyword to specify a map projection. PROJECTION is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE. The default projection is Arbitrary.
Example
See the code example under ENVI_EVF_DEFINE_ADD_RECORD.
See Also
ENVI_EVF_CLOSEENVI_EVF_DEFINE_ADD_RECORDENVI_EVF_DEFINE_CLOSEENVI_GET_PROJECTIONENVI_PROJ_CREATEENVI_WRITE_COSMOSKYMED_METADATA
ENVI Reference Guide ENVI_EVF_DEFINE_INIT
214 Chapter 2: ENVI Routines
ENVI_EVF_INFO
Use this procedure to get general information about an EVF. After you open the EVF with ENVI_EVF_OPEN (or ENVI_EVF_DEFINE_CLOSE returns the EVF ID), use the appropriate keyword to retrieve the number of records, layer name, data type, or projection.
Syntax
ENVI_EVF_INFO, EVF_ID [, DATA_TYPE=variable] [, LAYER_NAME=string] [, NUM_RECS=variable] [, PROJECTION=structure]
Arguments
EVF_ID
This is the EVF ID returned from ENVI_EVF_OPEN or ENVI_EVF_DEFINE_CLOSE.
Keywords
DATA_TYPE (optional)Use this keyword to specify a named variable that contains the ENVI data type of the vector file. DATA_TYPE uses the following IDL convention.
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
LAYER_NAME (optional)Use this keyword to specify a named variable that contains the string name for the EVF layer. Each EVF consists of only a single layer.
NUM_RECS (optional)Use this keyword to specify a named variable that contains the number of vector records in the EVF.
PROJECTION (optional)
ENVI_EVF_INFO ENVI Reference Guide
Chapter 2: ENVI Routines 215
Use this keyword to specify a map projection. PROJECTION is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE. The default projection is Arbitrary.
Example
See the code example under ENVI_EVF_CLOSE.
See Also
ENVI_EVF_CLOSEENVI_EVF_DEFINE_CLOSEENVI_EVF_OPENENVI_PROJ_CREATE
ENVI Reference Guide ENVI_EVF_INFO
216 Chapter 2: ENVI Routines
ENVI_EVF_OPEN
Use this function to open an existing EVF. It returns the EVF ID, which is used to access data from the file using ENVI_EVF_INFO and ENVI_EVF_READ_RECORD.
Syntax
Result = ENVI_EVF_OPEN(Filename)
Arguments
Filename
This is a string value that specifies the EVF filename.
Example
See the code example under ENVI_EVF_CLOSE.
See Also
ENVI_EVF_CLOSEENVI_EVF_DEFINE_INITENVI_EVF_INFOENVI_EVF_READ_RECORD
ENVI_EVF_OPEN ENVI Reference Guide
Chapter 2: ENVI Routines 217
ENVI_EVF_READ_RECORD
Use this function to retrieve records from an EVF. After you open the EVF with ENVI_EVF_OPEN (or ENVI_EVF_DEFINE_CLOSE returns the EVF ID), you can retrieve the specified record. The function ENVI_EVF_INFO returns the number of records.
Syntax
Result = ENVI_EVF_READ_RECORD(EVF_ID, Record_number [, PARTS_PTR=value] [, TYPE=value])
Return Value
The return value is a [2, n] array of double-precision, floating-point values, where n is the number of points in the record. Result[0, *] contains the x values, and Result[1, *] contains the y values.
Arguments
EVF_ID
This is the EVF ID returned from ENVI_EVF_OPEN or ENVI_EVF_DEFINE_CLOSE.
Record_number
This is the record number for the vector to retrieve. Record_number is a long integer from 0 to the total number of records minus one. The NUM_RECS value is retrieved using ENVI_EVF_INFO.
Keywords
PARTS_PTR (optional)If you are working with multipart vectors (for example, a polygon that contains holes), the value of this keyword is the output of the PARTS_PTR keyword in the ENVI_EVF_DEFINE_ADD_RECORD routine.
TYPE (optional)If you are working with multipart vectors, the possible values that will be returned for TYPE are as follows:
• 1: Point
• 3: Polyline
• 5: Polygon
• 8: Multi-point
Example
See the code example under ENVI_EVF_CLOSE.
ENVI Reference Guide ENVI_EVF_READ_RECORD
218 Chapter 2: ENVI Routines
See Also
ENVI_EVF_CLOSEENVI_EVF_DEFINE_CLOSEENVI_EVF_INFOENVI_EVF_OPEN
ENVI_EVF_READ_RECORD ENVI Reference Guide
Chapter 2: ENVI Routines 219
ENVI_EVF_TO_SHAPEFILE
This batch procedure enables you to output an EVF to shapefile format, which consists of files with .shp, .shx, and .dbf extensions.
A single EVF may contain points, polylines, polygons and/or multi-point records all in the same file. A shapefile, on the other hand, may only contain one record type per file. If the EVF contains only a single record type, then the resulting shapefile output from ENVI_EVF_TO_SHAPEFILE consists of three files:
rootname.shp,
rootname.shx,
rootname.dbf,
where rootname is the output_shapefile_rootname argument string.
If the EVF specified by the EVF_ID argument contains multiple record types, then the output of ENVI_EVF_TO_SHAPEFILE is a separate shapefile for each record type. For instance, if an EVF has any point, polyline, polygon, or multipoint records, the resulting files for a shapefile named rootname are:
If the EVF contains associated attributes, these attributes are contained in the rootname.dbf file. If there are no attributes, a dummy record ID column is used.
Syntax
ENVI_EVF_TO_SHAPEFILE, EVF_ID, output_shapefile_rootname
Arguments
EVF_ID
This is the EVF ID returned from ENVI_EVF_OPEN.
NoteThe EVF_ID argument may be an array of IDs as long as output_shapefile_rootname is a string array of the same number of elements. There must be one output root name per EVF_ID.
output_shapefile_rootname
This is a string with the root name for the resulting shapefiles. Because the shapefile output consists of multiple files with specific extensions, you do not need to include the .shp extension as part of this string.
rootname_point.shp for point records
rootname_polyline.shp for polyline records
rootname_polygon.shp for polygon records
rootname_multipoint.shp for multipoint records
ENVI Reference Guide ENVI_EVF_TO_SHAPEFILE
220 Chapter 2: ENVI Routines
WarningBecause EVF files also use a *.dbf file to store attributes, the output shapefile name must be different than the name of the EVF file. In other words, if you name an EVF foo.evf, then the output_shapefile_rootname argument should not be foo if the two formats (.evf, .shp) are to reside in the same directory.
ENVI_EVF_TO_SHAPEFILE ENVI Reference Guide
Chapter 2: ENVI Routines 221
ENVI_FILE_MNG
This procedure is used to manage ENVI files in memory and on disk.
Syntax
ENVI_FILE_MNG [, /DELETE], ID=file ID, /REMOVE
Keywords
DELETE (optional)Set this keyword to delete the specified file from the hard disk.
ID
Use this keyword to specify the file ID for the open file. This is the value returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0.
REMOVE
Set this keyword to remove the specified file from within ENVI.
Example
Remove the file specified by FID from ENVI and delete it from the disk.
envi_file_mng, id=fid, /remove, /delete
See Also
ENVI_GET_FILE_IDS
ENVI Reference Guide ENVI_FILE_MNG
222 Chapter 2: ENVI Routines
ENVI_FILE_QUERY
This procedure returns information about a data file, including (but not limited to) number of samples, lines, and bands; spatial dimensions; filename; data type; and interleave.
Syntax
ENVI_FILE_QUERY, FID [, BBL=array] [, BNAMES=variable] [, BYTE_SWAP=variable] [, CLASS_NAMES=variable] [, DATA_GAINS=variable] [, DATA_IGNORE_VALUE=variable] [, DATA_OFFSETS=variable] [, DATA_TYPE=variable] [, DEF_BANDS=array] [, DEF_ZRANGE=variable] [, DEF_STRETCH=variable] [, DESCRIP=variable] [, DIMS=variable] [, FILE_TYPE=variable] [, FNAME=variable] [, FUNC_COMPLEX={0 | 1 | 2 | 3 | 4}] [, FWHM=variable] [, H_INFO=variable] [, INTERLEAVE=variable] [, LOOKUP=variable] [, LUT_NAME=variable] [, NB=variable] [, NL=variable] [, NS=variable] [, NUM_CLASSES=variable] [, OFFSET=variable] [, READ_PROCEDURE=variable] [, REFLECTANCE_SCALE_FACTOR=variable] [, SENSOR_TYPE=integer] [, SNAME=variable] [, SPEC_NAMES=variable] [, STA_NAME=variable] [, WAVELENGTH_UNITS={0 | 1 | 2 | 3 | 4 | 5 | 6}] [, WL=variable] [, XSTART=variable] [, YSTART=variable]
Arguments
FID
This positional parameter is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
Keywords
BBL (optional)
Use this keyword to specify a named variable containing an array of ones and zeros representing the good and bad bands, respectively. The number of elements in BBL must be equal to the number of bands in the image. If no list of bad bands is available, BBL returns a value of -1.
BNAMES (optional)Use this keyword to specify a named variable that contains the band names associated with each band.
BYTE_SWAP (optional)Use this keyword to specify a named variable that contains the byte swap value for the data. If you set BYTE_SWAP, then the byte order of the data specified by FID is different than the current processor. User-specified spatial and spectral read procedures will need to byte order the data after reading from disk.
ENVI_FILE_QUERY ENVI Reference Guide
Chapter 2: ENVI Routines 223
CLASS_NAMES
Use this keyword to specify a string array of class names for classification images. The first element (Class 0) is “Unclassified.” Only use CLASS_NAMES if the result is a classification image, in which case this keyword is required. If the result is not a classification image, this keyword is optional.
DATA_GAINS (optional)Use this keyword to specify a named variable that contains an array of gains for each band in the dataset. DATA_GAINS is an array of values, one for each band. You can use DATA_GAINS in conjunction with DATA_OFFSETS in ENVI's general purpose utility, Apply Gain and Offset. If the gains are undefined for the input file, nothing is returned for the DATA_GAINS keyword.
DATA_IGNORE_VALUE (optional)Use this keyword to specify a named variable that contains a scalar number representing the data value to ignore in the dataset. If you set DATA_IGNORE_VALUE, it is the same type as the input dataset, and an undefined ignore value is represented by the double-precision number 1e-34. Currently, this value is used only in user-written ENVI code. If the data ignore value is undefined for the input file, DATA_IGNORE_VALUE returns nothing.
DATA_OFFSETS (optional)Use this keyword to specify a named variable that contains an array of offsets for each band in the dataset. You can use DATA_OFFSETS in conjunction with DATA_GAINS in ENVI's general purpose utility, Apply Gain and Offset. If the offsets are undefined for the input file, DATA_IGNORE_VALUE returns nothing.
DATA_TYPE (optional)Use this keyword to specify a named variable that contains the IDL data type of the file, using the following IDL convention.
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
DEF_BANDS (optional)
ENVI Reference Guide ENVI_FILE_QUERY
224 Chapter 2: ENVI Routines
Set this keyword to a one- or three-element array specifying which bands to display upon opening the file in ENVI. If you set DEF_BANDS to a one-element array, ENVI loads a grayscale image in the display group. If you set DEF_BANDS to a three-element array, ENVI loads an RGB image in the display group. The values are one-based. For example, to load bands 4, 3, and 2 of a 7-band image, set DEF_BANDS to [4, 3, 2].
DEF_ZRANGE (optional)Use this keyword to specify a named variable that contains a 2D array equal to the default lower and upper plot ranges in spectral plots.
DEF_STRETCH (optional)Use this keyword to specify a named variable that contains the default stretch, which is used when displaying a band from the file. DEF_STRETCH is the structure created by ENVI_DEFAULT_STRETCH_CREATE.
DESCRIP (optional)Use this keyword to specify a named variable that contains a string description of the file.
DIMS (optional)Use this keyword to specify a named variable that contains the spatial dimensions of the file.
FILE_TYPE (optional)Use this keyword to specify a named variable that contains an integer file-type value. See ENVI_FILE_TYPE for details on how to test for a given file type.
FNAME (optional)Use this keyword to specify a named variable that contains the name and path of the file. For memory items, FNAME contains a string indicating the memory item number and its associated spatial and spectral dimensions.
FUNC_COMPLEX (optional)Set this keyword to one of the following values to specify the complex lookup function that determines how to display complex data.
• 0: Power (default): The natural log of the magnitude
• 1: Magnitude:
• 2: Real: The real portion of the complex number
• 3: Imaginary: The imaginary part of the complex number
• 4: Phase:
NoteOnly set this keyword if the IDL data type of the image is complex or double-precision complex.
FWHM (optional)
real 2 inaryimag 2+
arc inaryimagreal
--------------------------tan
ENVI_FILE_QUERY ENVI Reference Guide
Chapter 2: ENVI Routines 225
Use this keyword to specify a named variable that contains an array of full-width-half-maximum values, one for each band. If there is no FWHM associated with the file, then a value of -1 is returned.
H_INFO (optional)Use this keyword to specify a named variable that contains a handle pointer to user-defined header information. Use the procedure HANDLE_VALUE to retrieve the information. The value of the handle is set equal to the INFO keyword in ENVI_SETUP_HEAD or ENVI_ENTER_DATA.
INTERLEAVE (optional)Use this keyword to specify a named variable that contains the file interleave type. The following integer values specify the interleave output:
• 0: BSQ
• 1: BIL
• 2: BIP
LOOKUP (optional)Use this keyword to specify a named variable that contains the RGB lookup values for each class in a classification image. The returned result is a byte array [3, num_classes]. LOOKUP is only set when the queried file is an ENVI classification file. Otherwise, the keyword returns a value of -1.
LUT_NAME (optional)Use this keyword to specify a named variable that contains the filename of the lookup table for the data.
NB (optional)Use this keyword to specify a named variable that contains the number of bands in the file.
NL (optional)Use this keyword to specify a named variable that contains the number of lines in the file.
NS (optional)Use this keyword to specify a named variable that contains the number of samples in the file.
NUM_CLASSES (optional)Use this keyword to specify a named variable that contains the number of classes for classification images. NUM_CLASSES is only set when the queried file is an ENVI classification file. Otherwise, the keyword returns a value of 0.
OFFSET (optional)Use this keyword to specify a named variable that contains the offset in bytes to the start of the data in the file.
READ_PROCEDURE (optional)
ENVI Reference Guide ENVI_FILE_QUERY
226 Chapter 2: ENVI Routines
Use this keyword to specify a named variable that contains a two-element string array of the procedure names for the spatial and spectral readers, respectively. The ENVI read procedures provide a powerful mechanism for importing custom formats or files directly into ENVI without the need for conversion. All spatial or spectral requests for data go through the specified read procedures.
REFLECTANCE_SCALE_FACTOR (optional)Use this keyword to specify a named variable that contains a single scalar number used to convert the input data into reflectance. For example, REFLECTANCE_SCALE_FACTOR would be used to convert integer scaled reflectance data into their floating point [0, 1] reflectance values. If the scale factor is undefined for the input file, nothing is returned for the this keyword.
SENSOR_TYPE (optional)Use this keyword to specify a named variable that contains the integer sensor type value. See ENVI_SENSOR_TYPE for details on how to test for a given sensor type.
SNAME (optional)Use this keyword to specify a named variable that contains the shortened filename (without the path). For memory items, SNAME contains an empty string.
SPEC_NAMES (optional)Use this keyword to specify a named variable that contains a string array of spectral library names. SPEC_NAMES is only set when the queried file is a spectral library.
STA_NAME (optional)Use this keyword to specify a named variable that contains the statistics file name. If no filename is specified, the STA_NAME is equal to the empty string, ‘’.
WAVELENGTH_UNITS (optional)Use this keyword to specify a named variable that contains a value indicating the wavelength units. The following values are valid:
• 0: Micrometers
• 1: Nanometers
• 2: Wavenumber
• 3: GHz
• 4: MHz
• 5: Index
• 6: Unknown
WL (optional)Use this keyword to specify a named variable that contains an array of wavelength values, one for each band. If there is no wavelength associated with the file, then a value of -1 is returned.
XSTART (optional)
ENVI_FILE_QUERY ENVI Reference Guide
Chapter 2: ENVI Routines 227
Use this keyword to specify a named variable that contains the x starting sample for the first pixel in the file.
YSTART (optional)Use this keyword to specify a named variable that contains the y starting row for the first pixel in the file.
Example
This example prompts the user for a file using ENVI_SELECT. Next, use ENVI_FILE_QUERY to retrieve the file information for the number of samples, lines and bands, spatial dimensions, the filename, data type, and interleave. Print the results to the screen.
ENVI_SELECT, fid=fid
ENVI_FILE_QUERY, fid, dims=dims, nb=nb, $ fname=fname, data_type=data_type, $ interleave=interleave
print, 'Filename = ', fnameprint, 'dims = ', dimsprint, 'nb = ', nbprint, 'interleave = ', interleaveprint, 'data type = ', data_type
See Also
ENVI_DISP_QUERYENVI_ENTER_DATAENVI_SETUP_HEAD
ENVI Reference Guide ENVI_FILE_QUERY
228 Chapter 2: ENVI Routines
ENVI_FILE_TYPE
ENVI files may conform to a range of different file types. This function returns a file type descriptor. All ENVI files that require a special display or input processing have a unique file type (meta file, virtual mosaic, classification, spectral library, FFT result). Any external file that requires an input read procedure also has a designated file type.
Syntax
Result = ENVI_FILE_TYPE(File_type)
Arguments
File_type
File_type can be either an integer or a string.
• If File_type is an integer, the function returns the string-format description of the file type returned by ENVI_FILE_QUERY.
• If File_type is a string, the function returns an arbitrarily assigned integer to use in procedures such as ENVI_SETUP_HEAD or ENVI_ENTER_DATA.
The file types and string descriptors are found in Table 12-1. File_type string descriptors are case-sensitive and may contain spaces.
File Type String Descriptor
ENVI Standard ENVI Standard
ENVI Meta File ENVI Meta File
ENVI Virtual Mosaic ENVI Virtual Mosaic
ENVI Classification ENVI Classification
ENVI Spectral Library ENVI Spectral Library
ENVI Fast Fourier Transform ENVI FFT
Australian Centre for Remote Sensing CEOS ACRES CEOS
ARC Digitized Raster Graphics ADRG
AVHRR LAC/HRPT, GAC data AVHRR CD
BMP BMP
CEOS Generic CEOS Generic
ENVISAT ENVISAT
ERDAS 8.X ERDAS 8.X
ERDAS IMAGINE ERDAS IMAGINE
Table 12-1: File Types and String Descriptors
ENVI_FILE_TYPE ENVI Reference Guide
Chapter 2: ENVI Routines 229
Examples
The following example prints the file-type string of the file associated with the file ID. The first command stores the integer file-type descriptor in the variable file_type:
envi_file_query, fid, file_type=file_type
The next line stores the string file type descriptor in the variable TYPE_STRING:
type_string = envi_file_type(file_type)print, type_string
European Space Agency Landsat TM ESA Landsat TM
ESA SHARP ESA SHARP
ESRI® GRID ESRI GRID
HDF EOS ASTER HDF EOS ASTER
HDF EOS MODIS HDF EOS MODIS
HDF Landsat HDF Landsat
HDF Modis Simulator HDF Modis Simulator
HDF Scientific Data and Raster HDF SD
HDF SeaWiFS HDF SeaWiFS
JPEG2000 JPEG2000
Multi-Resolution Seamless Image Database MrSID
National Imagery Transmission Format NITF
National Landsat Archive Production System CD NLAPS CD
NOAA DMSP NOAA DMSP
PCI PCI
Planetary Data System Image PDS Image
RADARSAT RADARSAT
SPOT CD SPOT CD
TIFF and GeoTIFF TIFF
Tiled QuickBird Tiled QB
Tiled WorldView Tiled WV
TFRD TFRD
ENVI Zoom Zoom
File Type String Descriptor
Table 12-1: File Types and String Descriptors
ENVI Reference Guide ENVI_FILE_TYPE
230 Chapter 2: ENVI Routines
The next example enters the array DATA into ENVI and sets the file type to SPOT data. The first line gets the integer file type for SPOT data. The second line enters the array.
file_type = envi_file_type('SPOT CD')envi_enter_data, DATA, file_type=file_type
See Also
ENVI_FILE_QUERYENVI_SENSOR_TYPE
ENVI_FILE_TYPE ENVI Reference Guide
Chapter 2: ENVI Routines 231
ENVI_FILTER_DOIT
Use this procedure to build an FFT filter image.
Syntax
ENVI_DOIT, 'ENVI_FILTER_DOIT' [, ANN_NAME=string], FILTER={0 | 1 | 2 | 3 | 4 | 5}, /IN_MEMORY, NBP=integer, NL=integer, NS=integer, OUT_NAME=string, R_FID=variable, RADIUS=array
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
IN_MEMORY
OUT_NAME
R_FID
ANN_NAME (optional)Use this keyword to specify an annotation filename for user-defined filters. This keyword is not used for circular or band-pass filters.
FILTER
Use this keyword to specify an integer corresponding to the filter type to build. Choose one of the following:
• 0: Circular pass filter
• 1: Circular cut filter
• 2: Band pass filter
• 3: Band cut filter
• 4: User-defined pass filter
• 5: User-defined cut filter
NBP
Use this keyword to specify the number of border pixels for the filter transitions.
NS
Use this keyword to specify the number of samples in the output filter image.
NL
Use this keyword to specify the number of lines in the output filter image.
ENVI Reference Guide ENVI_FILTER_DOIT
232 Chapter 2: ENVI Routines
RADIUS
For circular filters, this keyword specifies the filter radius in pixels. For band-pass filters, this keyword is a two-element array of integers specifying the inner and outer filter radius in pixels. This keyword is not used for user-defined filters.
Example
pro example_envi_filter_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the necessary variables ; ns = 512L nl = 512L radius = [60,150] out_name ='testfilter.img' ; ; Call the doit ; envi_doit, 'envi_filter_doit', $ ns=ns, nl=nl, filter=2, $ radius=radius, nbp=0, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI_FILTER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 233
ENVI_FX_DOIT
This procedure automates the Feature Extraction workflow for programmatic access using various segmentation and classification parameters. For a description of these parameters, refer to the topic "Introduction to Feature Extraction" in ENVI Zoom Help or ENVI EX Help.
NoteThis procedure is only available if you have both ENVI and ENVI EX installed and licensed.
Syntax
ENVI_DOIT, 'ENVI_FX_DOIT' [, A_FID=array] [, A_POS=array] [, BR_BANDS=array] [, CENTERLINE_OPTIONS=array] [, CONF_THRESHOLD=floating point] [, CS_BANDS=array], DIMS=array, [, /EXPORT_ATTRIBUTES] [, /EXPORT_RASTER], FID=file ID [, KERNEL_SIZE=long integer] [, /INVERSE_MASK] [, MERGE_LEVEL=floating point], [, M_FID=file ID], POS=array [, R_FID=variable] [, RASTER_FILENAME=string or string array] [, /RAW_ATTRIBUTES] [, RAW_FILENAME=string] [, REFINE_BAND=integer] [, /REFINE_INVERSE] [, /REFINE_MASK] [, RULESET_FILENAME=string], SCALE_LEVEL=floating point [, SEGMENT_BANDS=array] [, SMOOTHING_THRESHOLD=floating point] [, TD_FILENAME=string] [, THRESHOLD_LOWER=floating point] [, THRESHOLD_UPPER=floating point] [, VECTOR_FILENAME=string] [, VECTOR_OPTIONS=string array]
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
DIMS
FID
POS
A_FID (optional)Set this keyword to an array of long integers representing file IDs of ancillary data files. Use this keyword in conjunction with the A_POS keyword. The number of elements of A_FID must equal the number of elements of A_POS.
A_POS (optional)Set this keyword to an array of long integers representing band numbers to process in the ancillary data files. Use this keyword in conjunction with the A_FID keyword. Specify bands starting with zero (Band 1=0, Band 2=1, etc.)
Each element in the A_POS array corresponds to an element in the A_FID array. For example, suppose you have two ancillary files whose file IDs are 100 and 200. You want to process Band 1 from file ID 200, and you want to process Bands 2, 3, 4, and 5 from file ID 100. Write the code as follows:
ENVI Reference Guide ENVI_FX_DOIT
234 Chapter 2: ENVI Routines
A_FID = [200, 100, 100, 100, 100]A_POS = [0, 1, 2, 3, 4]
Or, to process all bands from the same file (100), write the code as follows:
A_FID = [100, 100, 100, 100, 100]A_POS = [0, 1, 2, 3, 4]
BR_BANDS (optional)Set this keyword to a two-element array of long integers representing band numbers used to calculate the Band Ratio attribute, in the following order: [redband, NIRband]. If you do not use this keyword, ENVI Zoom determines the red and near-infrared bands using wavelength information from the input file. If no wavelength information is available, ENVI Zoom uses the first two bands in the input file to calculate the Band Ratio attribute.
CENTERLINE_OPTIONS (optional)If you export vector results to a polyline shapefile, set this keyword to a five-element array of floating-point values, where each element represents a centerline parameter:
[distance, angle, prune, remove spurs, spur threshold]
• distance [0]: Minimum distance allowed for the weighted medial axis. The default value is 0. This is a unitless parameter; values can be equal to or greater than 0.
• angle [1]: Minimum angle (in degrees) allowed for the medial axis. Values range from 0 to 180.0 degrees. The default value is 60.0 degrees.
• prune [2]: This option is set to 1.0 by default, which means that unwanted edges will be removed from the medial axis. Set this array element to 0 if you do not want to enable pruning.
• remove spurs [3]: This option is set to 1.0 by default, which means that spurs will be removed from polylines. Set this array element to 0 if you do not want to remove spurs.
• spur threshold [4]: If you set the remove spurs option (array element [3]) to 1, then set the spur threshold element to the maximum spur length. Values range from 0.1 to 1. The default value is 0.5.
Following is an example of using this keyword when you want to perform pruning and removing spurs:
centerline_options = [0.0, 60.0, 1.0, 1.0, 0.5]
CONF_THRESHOLD (optional)Set this keyword to a floating-point value representing the Confidence Threshold parameter used in rule-based classification and in the Support Vector Machine (SVM) method of supervised classification. Values range from 0.0 to 1.0. The default value is 0.0.
NoteThe default value for this parameter in the Feature Extraction dialog in ENVI Zoom is 0.0 for supervised classification and 0.40 for rule-based classification.
CS_BANDS (optional)
ENVI_FX_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 235
Set this keyword to a three-element array of long integers representing band numbers used to calculate the Color Space attribute, in the following order: [redband, greenband, blueband]. If you do not use this keyword, ENVI Zoom determines the RGB bands using wavelength information from the input file. If no wavelength information is available, ENVI Zoom uses the first three bands in the input file to calculate the Color Space attribute.
EXPORT_ATTRIBUTES (optional)Use this keyword in conjunction with the VECTOR_FILENAME keyword. Set this keyword if you want to write attributes associated with the vector objects (following classification) to the output shapefile (.dbf).
EXPORT_RASTER (optional)Use this keyword in conjunction with the RASTER_FILENAME keyword. Set this keyword if you want to output classification results to a classification image and/or rule confidence image.
INVERSE_MASK (optional)Set this keyword if you want to invert the mask specified by the M_FID keyword. Inverting the mask means that Feature Extraction will process the areas with pixel values of 0.
KERNEL_SIZE (optional)Set this keyword to a long-integer odd number representing the size of the kernel used in texture attribute calculations. The default value is 3.
MERGE_LEVEL (optional)Set this keyword to a floating-point value (between 0.0 and 100.0) for the Merge Level parameter used during segmentation. If the value is 0.0, then no merging will be performed.
M_FID (optional)Set this keyword to the file ID of a raster mask image. If you specify this keyword, then Feature Extraction will ignore areas with pixel values of 0 in the mask.
R_FID
This keyword is a returned variable containing a file ID. One of the following values will be returned:
• If processing fails for any reason, then R_FID = -1.
• If you specify the RASTER_FILENAME keyword and processing is successful, R_FID will contain the file ID of the classification image.
• If you do not specify the RASTER_FILENAME keyword and processing is successful, R_FID will contain the file ID of the input file (R_FID = FID).
RASTER_FILENAME (optional)Use this keyword to specify the filenames of an output classification image and/or rule image when you set the EXPORT_RASTER keyword. If you do not set this keyword, then ENVI does not create output raster files.
ENVI Reference Guide ENVI_FX_DOIT
236 Chapter 2: ENVI Routines
To create an output classification image only, set RASTER_FILENAME to a string value, for example: RASTER_FILENAME='class.img'.
To create both classification and rule confidence images, set RASTER_FILENAME to a two-element string array as follows: RASTER_FILENAME=['class.img', 'rule.img'].
To create a rule image only, set RASTER_FILENAME to a two-element string array with the first element as a null string, for example: RASTER_FILENAME=['', 'rule.img'].
RAW_ATTRIBUTES (optional)Use this keyword in conjunction with the RAW_FILENAME keyword. Set this keyword if you want to output the raw attributes (prior to classification) to the output shapefile (.dbf).
RAW_FILENAME (optional)Set this keyword to a string value with the filename of a shapefile where you can output the raw vectors (prior to classification). If you use this keyword, ENVI_FX_DOIT skips classification and ignores the following keywords: CONF_THRESHOLD, VECTOR_FILENAME, VECTOR_OPTIONS, SMOOTHING_THRESHOLD, and RASTER_FILENAME.
REFINE_BAND (optional)Set this keyword to a long-integer value representing the band of the Region Means image used during the Refine step. You must also specify the THRESHOLD_LOWER and THRESHOLD_UPPER keywords.
If you also set the SEGMENT_BANDS keyword, then the Region Means image will only consist of the bands specified by SEGMENT_BANDS instead of all bands in the image. In this case, REFINE_BAND must correspond to one of the bands in the resulting Region Means image rather than a band from the original image.
REFINE_INVERSE (optional)Set this keyword if you want to invert the mask created during the Refine step (if any). You must set the REFINE_MASK keyword. Inverting the mask means that Feature Extraction will process the areas with pixel values of 0.
REFINE_MASK (optional)Set this keyword if you want to create a mask during the Refine step. To set this keyword, you must also set the THRESHOLD_LOWER and THRESHOLD_UPPER keywords. Feature Extraction will ignore areas with pixel values of 0 in the mask.
RULESET_FILENAME (optional)Set this keyword to a string value with the filename (.xml) of an input rule set if you are performing rule-based classification. ENVI_FX_DOIT uses this keyword to read in the attributes computed for rule-based classification.
NoteYou must use the RULESET_FILENAME or TD_FILENAME keyword when performing classification, but not both.
ENVI_FX_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 237
SCALE_LEVEL
Set this keyword to a floating-point value (between 0.0 and 100.0) for the Scale Level parameter used during segmentation.
SEGMENT_BANDS (optional)Set this keyword to an array of long integers representing the band numbers used for segmentation. The default is to use all bands in the input image: SEGMENT_BANDS=lindgen(nbands).
SMOOTHING_THRESHOLD (optional)Set this keyword to a floating-point value (in units of pixels) to use during vector smoothing. The default value is 1.0. Setting this keyword to 0.0 disables vector smoothing. This keyword has no effect if you do not set the VECTOR_FILENAME keyword.
TD_FILENAME (optional)Set this keyword to a string value with the filename of a training dataset if you are performing supervised classification. ENVI_FX_DOIT uses this keyword to read in the attributes computed for supervised classification.
NoteYou must use the RULESET_FILENAME or TD_FILENAME keyword when performing classification, but not both.
THRESHOLD_LOWER (optional)Set this keyword to a floating-point value representing the low threshold for the Refine step. The default value is 0.0.
NoteThe Refine step will be performed only if THRESHOLD_LOWER < THRESHOLD_UPPER.
THRESHOLD_UPPER (optional)Set this keyword to a floating-point value representing the upper threshold for the Refine step. The default value is 0.0.
VECTOR_FILENAME (optional)Set this keyword to a string value with the full path to a file or directory where the vector shapefiles will be output. If you set this keyword to a directory name, then ENVI creates separate shapefiles for each feature and writes them to this directory. If you set this keyword to a filename with a .shp extension, then ENVI creates a single shapefile containing all the features. If you do not set this keyword, then no vectors are created.
VECTOR_OPTIONS (optional)Set this keyword to a string array indicating the type of vector output desired for each feature. Valid values are 'Point', 'Line', or 'Polygon'. The default value is 'Polygon'. The number of elements in this array is determined by the number of features that have been extracted. This keyword has no effect if you did not set the VECTOR_FILENAME keyword.
ENVI Reference Guide ENVI_FX_DOIT
238 Chapter 2: ENVI Routines
If you set VECTOR_FILENAME to a filename, only the first value in the VECTOR_OPTIONS array is used to determine the output type.
Example
The following example uses ENVI_FX_DOIT to automatically extract water and healthy vegetation from a QuickBird multispectral image of Boulder, Colorado. It uses the files qb_boulder_msi and qb_boulder_msi_ruleset.xml, which are provided in the Data\feature_extraction directory of the ENVI Resource DVD that shipped with your software. The example code performs segmentation and merging with no refinement. It computes spatial, spectral, and texture attributes. It performs rule-based classification using an existing rule set (qb_boulder_msi_ruleset.xml) and creates separate, smoothed, polygon shapefiles for the vegetation and water features in the specified output directory.
pro example_fx_doit compile_opt strictarr, hidden ; ; First restore all the base save files ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file = 'batch.txt' ; ; Specify the input image file, rule set, ; and output directory for vector shapefiles ; imgFile = 'qb_boulder_msi' rulesetfilename = 'qb_boulder_msi_ruleset.xml' vectorFilename = 'vector_out' ; ; Open the image file ; envi_open_file, imgFile, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the necessary variables ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) ; ; Call the doit ; envi_doit, 'envi_fx_doit', fid=fid, dims=dims, $ pos=pos, scale_level=60.0, merge_level=67.0, $ conf_threshold=0.20, ruleset_filename=rulesetfilename, $ vector_filename=vectorfilename, r_fid=r_fid ; if (r_fid eq -1) then begin str = 'Processing failed for ' + imgFile envi_error, str endif
ENVI_FX_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 239
; ; Exit ENVI ; envi_batch_exit ;end
To output the raw vectors to a shapefile in the above example (without performing classification), call ENVI_FX_DOIT as follows. Outputting raw vectors requires you to compute attributes, so you should also specify the RULESET_FILENAME or TD_FILENAME keyword.
envi_doit, 'envi_fx_doit', fid=fid, dims=dims, $pos=pos, scale_level=60.0, merge_level=67.0, $ruleset_filename=rulesetfilename, $raw_filename=rawFilename, /raw_attributes, $rfid=r_fid
ENVI Reference Guide ENVI_FX_DOIT
240 Chapter 2: ENVI Routines
ENVI_GEOREF_FROM_GLT_DOIT
Use this procedure to georeference a file from a GLT file, which contains the map projection information for the specified input file. Each pixel location in the input file is directly mapped to a specified output map location. The procedure ENVI_GLT_DOIT is used to build the input GLT file.
Syntax
ENVI_DOIT, 'ENVI_GEOREF_FROM_GLT_DOIT' [, BACKGROUND=value],FID=file ID [, GLT_DIMS=array], GLT_FID=file ID, /IN_MEMORY
[, KERNEL_MAX=value] [, KERNEL_MIN=value] [, MIN_PIXELS=value], OUT_NAME=string, POS=array [, R_FID=variable] [, SGL_NAME=string [, /SUBSET] [, /SUPER]
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
FID
IN_MEMORY
OUT_NAME
POS
R_FID (optional)
BACKGROUND (optional)Use this keyword to specify the value for all background pixels. The default is 0.
GLT_DIMS (optional)Use this keyword to specify the spatial dimensions on which to perform the operation. GLT_DIMS is a five-element array of long integers with the following definitions:
• GLT_DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• GLT_DIMS[1]: The starting sample number. The first x pixel is 0.
• GLT_DIMS[2]: The ending sample number
• GLT_DIMS[3]: The starting line number. The first y pixel is 0.
• GLT_DIMS[4]: The ending line number
GLT_FID
Use this keyword to specify the file ID of the input GLT file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. GLT_FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
ENVI_GEOREF_FROM_GLT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 241
KERNEL_MAX
Use this keyword to specify the maximum kernel size, which is used with KERNEL_MIN as a set of resampling parameters.
KERNEL_MIN (optional)Use this keyword to specify the minimum kernel size, which is used in the resampling unless the kernel contains fewer than the minimum number of pixels to resample, or valid pixels. If the former, then the kernel size increases until either the minimum number of valid pixels is met or the maximum kernel size is met.
MIN_PIXELS (optional)Use this keyword to specify the minimum number of pixels. If the maximum kernel size has fewer than the minimum number of pixels, then the output pixel value is set to the background value.
SGL_NAME (optional)Use this keyword to specify the filename of the super GLT file (on disk) that results from GLT_DOIT. This keyword is required if you set the SUPER keyword.
SUBSET (optional)Set this keyword to indicate that the file specified by FID is a subset of the GLT file. Output dimensions will be determined by the minimum and maximum samples and lines of the GLT file. If you set this keyword, then GLT_DIMS is ignored.
SUPER (optional)Set this keyword to perform a super GLT operation. If you set this keyword, you must also specify SGL_NAME.
Example
pro example_glt_usage
compile_opt strictarr
; Select an image and it's associated input geometry.envi_select, title='Please select an image to georeference', $ dims=dims, fid=fid, pos=posif fid eq -1 then returnenvi_select, title='Please select the longitude band', $ fid=x_fid, dims=dims, pos=x_pos, /band_only, /no_dimsif x_fid eq -1 then returnenvi_select, title='Please select the latitude band', $ fid=y_fid, dims=dims, pos=y_pos, /band_only, /no_dimsif y_fid eq -1 then return
; Figure out what UTM zone we're in.query_dims = [-1L, long(dims[2]/2), long(dims[2]/2), long(dims[4]/2), long(dims[4]/2)]lat_lon = [envi_get_data(fid=y_fid, dims=query_dims, pos=y_pos), $
envi_get_data(fid=x_fid, dims=query_dims, pos=x_pos)]zone = fix(31.0 + lat_lon[1]/6.0)
ENVI Reference Guide ENVI_GEOREF_FROM_GLT_DOIT
242 Chapter 2: ENVI Routines
south = (lat_lon[0] lt 0)
; Make the GLT.envi_file_query, fid, sname=snameout_name=sname+'_glt'pixel_size=1000.0Drotation=0.0i_proj = envi_proj_create(/geographic)o_proj = envi_proj_create(/utm, zone=zone, south=south)envi_glt_doit, i_proj=i_proj, $ o_proj=o_proj, out_name=out_name, $ pixel_size=pixel_size, r_fid=glt_fid, $ rotation=rotation, x_fid=x_fid, y_fid=y_fid, $ x_pos=x_pos, y_pos=y_posif glt_fid eq -1 then return
; Georeference the image from the GLT.out_name=sname+'_georef'envi_doit, 'envi_georef_from_glt_doit', fid=fid, $ glt_fid=glt_fid, out_name=out_name, pos=pos, $ subset=dims, r_fid=r_fidend
See Also
ENVI_GLT_DOITENVI_REGISTER_DOIT
ENVI_GEOREF_FROM_GLT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 243
ENVI_GET_CONFIGURATION_VALUES
Use this function to return an anonymous structure of the current ENVI configuration settings. The tag names of the structure are the configuration item, and the values represent the current setting.
Syntax
Result = ENVI_GET_CONFIGURATION_VALUES
Example
This example retrieves the current ENVI configuration values.
cfg = envi_get_configuration_values()help, cfg, /structure
ENVI Reference Guide ENVI_GET_CONFIGURATION_VALUES
244 Chapter 2: ENVI Routines
ENVI_GET_DATA
Use this function to retrieve spatial image data for any open file. The DIMS keyword allows full control over the spatial dimensions of the returned data, which allows you to retrieve a full band or any spatial subset. The band is specified with the POS keyword, and only a single band is returned. Additional optional parameters allow you to automatically resample the spatial data to smaller or larger pixel sizes. This function will work with any open image, regardless of the format or physical storage order of the file.
You can use this function, along with ENVI_GET_SLICE, in place of tiled processing. However, requests for large images may be limited by the amount of available RAM in your your system.
Syntax
Result = ENVI_GET_DATA(/COMPLEX, DIMS=array, FID=file ID [, INTERP={0 | 1 | 2 | 3}], POS=long integer [, XFACTOR=integer] [, YFACTOR=integer])
Keywords
See “Common Keywords” on page 34 for definitions of the following two keywords.
FID
POS
COMPLEX
Set this keyword to return the output data as complex.
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).
• DIMS[0]: Unused for this routine; set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
INTERP (optional)
ENVI_GET_DATA ENVI Reference Guide
Chapter 2: ENVI Routines 245
Set this keyword to one of the following values to indicate the interpolation type. Use this keyword only when XFACTOR or YFACTOR is not equal to 1.
• 0: Nearest neighbor
• 1: Bilinear
• 2: Cubic convolution
• 3: Pixel aggregate
XFACTOR (optional)Use this keyword to specify the x magnification factor for the data. A value of 1 does not change the data. Values greater than 1 cause the size to increase; values less than 1 cause the size to decrease.
YFACTOR (optional)Use this keyword to specify the y magnification factor for the data. A value of 1 does not change the data. Values greater than 1 cause the size to increase; values less than 1 cause the size to decrease.
Example
This example opens a file, determines its spatial size, and requests that all of the data for the first band are stored in the variable DATA. The procedure ENVI_OPEN_FILE is used to programmatically open the desired file. Subsequent references to this file will use the file ID returned in the keyword R_FID. Once the file is open, ENVI_FILE_QUERY determines the number of samples and lines. These are used to set the DIMS keyword for the function ENVI_GET_DATA. A call to ENVI_GET_DATA with the full band specified by DIMS and the first band specified by POS returns all image data for the first band in a samples-by-lines 2D array.
ENVI_OPEN_FILE, 'can_tmr.img', r_fid=fidENVI_FILE_QUERY, fid, dims=dimsdata = ENVI_GET_DATA(fid=fid, dims=dims, pos=0)
See Also
ENVI_GET_IMAGEENVI_INIT_TILEENVI_OPEN_FILEENVI_GET_SLICE
ENVI Reference Guide ENVI_GET_DATA
246 Chapter 2: ENVI Routines
ENVI_GET_DISPLAY_NUMBERS
Use this function to get a list of display numbers.
NoteAn interactive ENVI session is required to run this function.
Syntax
Result = ENVI_GET_DISPLAY_NUMBERS([, /COLOR] [, /GEOREF] [, /LOADED])
Keywords
COLOR (optional)Set this keyword to specify that the function return only display group windows with RGB color images. Use this keyword in conjunction with the other keywords.
GEOREF (optional)Set this keyword to specify that the function return only display group windows with georeferenced images. Use this keyword in conjunction with the other keywords.
LOADED (optional)Set this keyword to specify that the function return only display group windows that are loaded with an image. Use this keyword in conjunction with the other keywords.
ENVI_GET_DISPLAY_NUMBERS ENVI Reference Guide
Chapter 2: ENVI Routines 247
ENVI_GET_FILE_IDS
This function returns an array of file IDs for all open ENVI files. A file ID is a long integer with a value greater than 0. If no files are open, then a value of -1 is returned.
NoteMore than one file ID may be associated with a single open file in ENVI. For example, if ENVI_GET_FILE_IDS is applied to a virtual mosaic, it returns not only the file ID of the virtual mosaic but also the IDs of the files used to create the mosaic.
Syntax
Result = ENVI_GET_FILE_IDS()
Example
This example returns all the file IDs and prints the corresponding filename.
fids = envi_get_file_ids()if (fids[0] eq -1) then returnfor i = 0, n_elements(fids) - 1 do begin
envi_file_query, fids[i], fname = fnameprint, fname
endfor
See Also
ENVI_FILE_MNGENVI_FILE_QUERYENVI_OPEN_FILE
ENVI Reference Guide ENVI_GET_FILE_IDS
248 Chapter 2: ENVI Routines
ENVI_GET_HEADER_VALUE
Use this procedure to retrieve user-defined header values using the argument User_Keyword. All standard header information is available by using the procedure ENVI_FILE_QUERY. However, to access user-defined header values, you must use ENVI_GET_HEADER_VALUE. Optional keywords allow you to set the returned data type.
Syntax
Result = ENVI_GET_HEADER_VALUE(FID, User_Keyword [, /BYTE] [, /DOUBLE] [, DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}] [, /FIX] [, /FLOAT] [, /L64] [, /LONG] [, /UL64] [, /ULONG] [, UNDEFINED=variable])
Arguments
FID
This is the file ID of the open file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
User_Keyword
This is a case-insensitive string that must exactly match the string you specified in the KEYWORD keyword to ENVI_ASSIGN_HEADER_VALUE.
Keywords
BYTE (optional)Set this keyword to return the User_Keyword values as byte numbers. You should not set this keyword if you use the keywords DOUBLE, DT, FIX, FLOAT, L64, LONG, UL64, or ULONG. The default is to return the values as a string.
DOUBLE (optional)
Set this keyword to return the User_Keyword values as double-precision numbers. You should not set this keyword if you use the keywords BYTE, DT, FIX, FLOAT, L64, LONG, UL64, or ULONG. The default is to return the values as a string.
DT (optional)
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
ENVI_GET_HEADER_VALUE ENVI Reference Guide
Chapter 2: ENVI Routines 249
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
FIX (optional)Set this keyword to return the User_Keyword values as integer numbers. You should not set this keyword if you use the keywords BYTE, DOUBLE, DT, FLOAT, L64, LONG, UL64, or ULONG. The default is to return the values as a string.
FLOAT (optional)Set this keyword to return the User_Keyword values as floating-point numbers. You should not set this keyword if you use the keywords BYTE, DOUBLE, DT, FIX, L64, LONG, UL64, or ULONG. The default is to return the values as a string.
L64 (optional)Set this keyword to return the User_Keyword values as 64-bit integers. You should not set this keyword if you use the keywords BYTE, DOUBLE, DT, FIX, FLOAT, LONG, UL64, or ULONG. The default is to return the values as a string.
LONG (optional)Set this keyword to return the User_Keyword values as long numbers. You should not set this keyword if you use the keywords BYTE, DOUBLE, DT, FIX, FLOAT, L64, UL64, or ULONG. The default is to return the values as a string.
UL64 (optional)Set this keyword to return the User_Keyword values as unsigned 64-bit integers. You should not set this keyword if you use the keywords BYTE, DOUBLE, DT, FIX, FLOAT, L64, LONG, or ULONG. The default is to return the values as a string.
ULONG (optional)Set this keyword to return the User_Keyword values as unsigned long numbers. You should not set this keyword if you use the keywords BYTE, DOUBLE, DT, FIX, FLOAT, LONG, L64, or UL64. The default is to return the values as a string.
UNDEFINED (optional)Use this keyword to specify a named variable that is set to 1 if User_Keyword is not present, or 1 if this argument is present.
Example
The following example opens the image file can_tmr.img using the ENVI_OPEN_FILE procedure. Once the file is open and a valid file ID is returned, a user-defined header value for “My Scale Factors” is stored to the header using ENVI_ASSIGN_HEADER_VALUE. The
ENVI Reference Guide ENVI_GET_HEADER_VALUE
250 Chapter 2: ENVI Routines
change is queried using ENVI_GET_HEADER_VALUE with the keyword to return floating-point values. The returned result is printed to the ENVI log window. At this point, the header change exists only in the current ENVI session. In order to preserve this change to the disk file, the procedure ENVI_WRITE_FILE_HEADER is called to write an updated header to disk.
envi_open_file, 'can_tmr.img', r_fid=fidif (fid eq -1) then returnscale_factors = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]envi_assign_header_value, fid=fid, keyword='My Scale Factors', $ value=scale_factors, precision=3values = envi_get_header_value(fid, 'My Scale Factors', /float)print, 'My Scale Factors', valuesenvi_write_file_header, fid
See Also
ENVI_ASSIGN_HEADER_VALUEENVI_WRITE_FILE_HEADER
ENVI_GET_HEADER_VALUE ENVI Reference Guide
Chapter 2: ENVI Routines 251
ENVI_GET_IMAGE
This function returns the display data for the associated display group. ENVI_GET_IMAGE returns either one band (ns, nl) or three bands (ns, nl, 3).
NoteAn interactive ENVI session is required to run this function.
Syntax
Result = ENVI_GET_IMAGE(BAND_POS=value, DIMS=array, DN=integer)
Keywords
BAND_POS
Use this keyword to specify the band position of an RGB image to return. If left undefined, then all three RGB bands are returned. For gray scale images, set BAND_POS=0.
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing.
• DIMS[0]: Unused for this routine; set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
DN
Use this keyword to specify the display number for the data request. Display numbers can be retrieved in the event handler of user-managed display events. Retrieve the uvalue for ev.top:
widget_control, ev.top, get_uvalue=dn
For user-managed display routines, just add a menu item to the display.men file. See “Modifying the ENVI Menus” in the ENVI Programmer’s Guide for more details.
Example
Retrieve all data in the display group. Check to see what type of image is displayed, and set BAND_POS accordingly.
ENVI Reference Guide ENVI_GET_IMAGE
252 Chapter 2: ENVI Routines
widget_control, ev.top, get_uvalue=dnenvi_disp_query, dn, xds=xds, yds=yds, color=colorif (color eq 0) then band_pos = 0data=envi_get_image(dn=dn, band_pos=band_pos, $
dims=[-1, 0, xds[0]-1, 0, yds[0]-1])
See Also
ENVI_DISP_QUERY
ENVI_GET_IMAGE ENVI Reference Guide
Chapter 2: ENVI Routines 253
ENVI_GET_MAP_INFO
Use this function to return a map information structure for the specified file or display group. If there is no map information associated with the FID or DN, then the UNDEFINED keyword returns a value of 1. The result of this function can be used for other functions that require an input MAP_INFO structure, such as ENVI_SETUP_HEAD.
Syntax
Result = ENVI_GET_MAP_INFO([, DN=integer] [, FID=file ID] [, UNDEFINED=variable])
Keywords
DN (optional)Use this keyword to specify the display number for the returned projection information. The function will return the map information structure for the data in the display group. If the displayed data are not georeferenced, an Arbitrary projection is returned.
FID (optional)Use this keyword to specify the file ID for the returned map information. If the file is not georeferenced, an Arbitrary projection is returned. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
UNDEFINED (optional)Set this keyword to a named variable that contains either 0 or 1. A value of 0 indicates the returned projection is valid. A value of 1 indicates no projection exists for the given DN or FID, and the resulting map information structure is invalid.
Example
; Select an input fileenvi_select, fid=fid
; Get the associated map information structuremap_info = envi_get_map_info(fid=fid)
See Also
ENVI_DISP_QUERYENVI_FILE_QUERYENVI_MAP_INFO_CREATE
ENVI Reference Guide ENVI_GET_MAP_INFO
254 Chapter 2: ENVI Routines
ENVI_GET_PATH
This function returns the path where the current version of ENVI is installed. There are no arguments or keywords associated with this function.
Syntax
ENVI_GET_PATH()
Examples
At the ENVI command line, use ENVI_GET_PATH with the PRINT command:
ENVI> print, ENVI_GET_PATH()C:\Program Files\ITT\IDLxx\products\envixx
(The xx refers to the software version.)
To access the path programmatically, you can use something similar to the following:
my_file = filepath('bhtmref.img', root=envi_get_path(), $ subdir=['data'])
ENVI_GET_PATH ENVI Reference Guide
Chapter 2: ENVI Routines 255
ENVI_GET_PROJECTION
Use this function to return projection information for the specified file, display group, or map information handle.
Syntax
Result = ENVI_GET_PROJECTION([, DN=integer] [, FID=file ID] [, PIXEL_SIZE=variable] [, UNITS=variable])
Keywords
DN (optional)Use this keyword to specify the display number for the returned projection information. The function returns the projection information for the data in the display group. If the displayed data are not georeferenced, an Arbitrary projection is returned.
FID (optional)Use this keyword to specify the file ID for the returned projection information. If the file is not georeferenced, an Arbitrary projection is returned. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
PIXEL_SIZE (optional)Use this keyword to specify a named variable that contains the x and y pixel size of the returned projection. The returned pixel size is a two-element, double-precision array. The first element is the x pixel size, and the second element is the y pixel size.
UNITS (optional)Use this keyword to specify a named variable that contains the projection units. This is an integer value that you can transform into a string using the procedure ENVI_TRANSLATE_PROJECTION_UNITS.
Example
PRO atest
; Select a fileENVI_SELECT, FID = fidIF (fid EQ -1) THEN RETURN
; Get the projection informationproj = ENVI_GET_PROJECTION(FID = fid)PRINT, proj
END
ENVI Reference Guide ENVI_GET_PROJECTION
256 Chapter 2: ENVI Routines
See Also
ENVI_PROJ_CREATE
ENVI_GET_PROJECTION ENVI Reference Guide
Chapter 2: ENVI Routines 257
ENVI_GET_RGB_TRIPLETS
Use this procedure to get the RGB triplets associated with a graphics color index.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
ENVI_GET_RGB_TRIPLETS, Index, R, G, B
Arguments
Index
This is the graphics color index for the desired triplet. The modulo operator that uses the total number of graphics colors is applied to Index prior accessing the color triplets.
R
This is the red color value.
G
This is the green color value.
B
This is the blue color value.
Example
pro example_envi_get_rgb_triplets ; ; Save the RGB values for 5 ; graphics colors into the ; array lookup ; lookup = bytarr(3,5) ; for i=0L,4 do begin envi_get_rgb_triplets, i+2, r, g, b lookup[0,i] = [r,g,b] endfor ; ; Print the resulting array ; lookup ; print, lookupend
ENVI Reference Guide ENVI_GET_RGB_TRIPLETS
258 Chapter 2: ENVI Routines
ENVI_GET_ROI
This function returns the 1D spatial addresses (pointers) of each point in an ROI. The address of an ROI pixel at (r_sample, r_line) is calculated as:
r_sample + r_line * ns.
Syntax
Result = ENVI_GET_ROI(ROI_ID, ROI_COLOR=variable, ROI_NAME=variable)
Arguments
ROI_ID
This is a single ID returned from the function ENVI_GET_ROI_IDS.
Keywords
ROI_COLOR
Use this keyword to specify a named variable that contains the RGB color value for ROI_ID. ROI_COLOR is a byte array of size three.
ROI_NAME
Use this keyword to specify a named variable that contains a string with the ROI name.
Example
Use ENVI_GET_ROI to return the address and name of each ROI associated with display DN. Then print the ROI name and number of points.
roi_ids = envi_get_roi_ids(dn=dn)for i=0, n_elements(roi_ids)-1 do begin
roi_addr = envi_get_roi(roi_ids[i], roi_name=name)print, 'ROI: ', name, n_elements(roi_addr)
endfor
See Also
ENVI_CREATE_ROIENVI_DEFINE_ROIENVI_GET_ROI_DATAENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_IDSENVI_RESTORE_ROISENVI_SAVE_ROIS
ENVI_GET_ROI ENVI Reference Guide
Chapter 2: ENVI Routines 259
ENVI_GET_ROI_DATA
This function returns the data associated with an ROI address.
Syntax
Result = ENVI_GET_ROI_DATA(ROI_ID [, ADDR=value], FID=file ID, POS=value)
Arguments
ROI_ID
This is a single ID returned from the function ENVI_GET_ROI_IDS.
Keywords
ADDR (optional)Use this keyword to specify the addresses of each ROI data value returned from the function ENVI_GET_ROI. The returned data values match the corresponding input addresses.
FID
See “Common Keywords” on page 34 for a definition of this keyword.
POS
Use this keyword to specify the band position(s) to get ROI data for. If POS is a single element, the result is Result(npts). Otherwise, the result is Result(n_elements(POS), npts).
Example
Use ENVI_GET_ROI_DATA to get the data values for bands 0, 1, and 2.
data = envi_get_roi_data(roi_id[0], fid=fid, pos=[0,1,2])
Notes
If you have a large ROI and many bands in the POS array, then the memory requirements may exceed the capacity of your machine. One way to break up the problem is to request fewer bands in the POS array, process the data, and get the ROI for the next set of bands. To use less memory, only request one band at a time and loop on the number of bands.
The order of ROI locations within the returned array ADDR can be different when ENVI_GET_ROI_DATA() is called with POS set to one band versus when it is called with POS set to more than one band. ADDR matches the order of the data in the returned array in either case (i.e., DATA[0] comes from location ADDR[0]). But the order of ADDR may be different for each case (i.e., ADDR1 may not match ADDR2).
ENVI Reference Guide ENVI_GET_ROI_DATA
260 Chapter 2: ENVI Routines
See Also
ENVI_CREATE_ROIENVI_DEFINE_ROIENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_IDSENVI_RESTORE_ROISENVI_SAVE_ROIS
ENVI_GET_ROI_DATA ENVI Reference Guide
Chapter 2: ENVI Routines 261
ENVI_GET_ROI_DIMS_PTR
This function returns the DIMS ROI pointer value used in DIMS[0]. Since ROI pointer values are likely to change as ROIs are created, updated or removed, you should always use the ROI_ID argument to get the current ROI pointer value.
Syntax
Result = ENVI_GET_ROI_DIMS_PTR(ROI_ID)
Arguments
ROI_ID
ROI_ID is a single ID returned from the function ENVI_GET_ROI_IDS.
Example
Set the first element of the DIMS array using ROI_ID[0]. To get the nth DIMS pointer, use ROI_ID[n].
roi_ids = envi_get_roi_ids(fid = fid)dims = [envi_get_roi_dims_ptr(roi_ids[0]), 0, 0, 0, 0]
See Also
ENVI_CREATE_ROIENVI_DEFINE_ROIENVI_GET_ROIENVI_GET_ROI_DATAENVI_GET_ROI_IDSENVI_RESTORE_ROISENVI_SAVE_ROIS
ENVI Reference Guide ENVI_GET_ROI_DIMS_PTR
262 Chapter 2: ENVI Routines
ENVI_GET_ROI_IDS
This function returns an array of ROI IDs associated with a display group, a file, or a spatial size [ns, nl].
Syntax
Result = ENVI_GET_ROI_IDS([, DN=integer] [, FID=file ID] [, /LONG_NAME] [, NL=integer] [, NS=integer] [, ROI_COLORS=variable] [, ROI_NAMES=variable] [, /SHORT_NAME])
Keywords
DN (optional)Use this keyword to specify the display number for the data request. Display numbers can be retrieved in the event handler of user-managed display events. Retrieve the uvalue for ev.top:
widget_control, ev.top, get_uvalue=dn
For user-managed display routines, just add a menu item to the display.men file. See “Modifying the ENVI Menus” in the ENVI Programmer’s Guide for more details.
FID (optional)See “Common Keywords” on page 34 for a definition of this keyword.
LONG_NAME (optional)Set this keyword to return the ROI name, ROI color, number of points, and associated image size in the variable specified by ROI_NAMES. You cannot set this keyword if you set SHORT_NAME.
NL (optional)Use this keyword to specify the number of lines associated with the desired ROIs. If you specify NL, then you must also specify NS.
NS (optional)Use this keyword to specify the number of samples associated with the desired ROIs. If you specify NS, then you must also specify NL.
ROI_COLORS (optional)Use this keyword to specify a named variable that contains the RGB color value for each ROI ID. ROI_COLORS is a byte array of size [3, #ROI IDs].
ROI_NAMES (optional)Use this keyword to specify a named variable that contains a string array of ROI names for each ROI ID. The default name includes the ROI name, ROI color, and number of points. Set the keyword SHORT_NAME or LONG_NAME to modify the default ROI_NAMES.
SHORT_NAME (optional)
ENVI_GET_ROI_IDS ENVI Reference Guide
Chapter 2: ENVI Routines 263
Set this keyword to return only the ROI name in the variable specified by ROI_NAMES. You cannot set this keyword if you set LONG_NAME.
Example
Get the ROI IDs associated with a display group. When a routine is called from the display group menu, the uvalue of ev.top contains the display number.
widget_control, ev.top, get_uvalue=dnroi_ids = envi_get_roi_ids(dn=dn, roi_names=roi_names, $
roi_colors=roi_colors)
See Also
ENVI_CREATE_ROIENVI_DEFINE_ROIENVI_GET_ROIENVI_GET_ROI_DATAENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_INFORMATIONENVI_RESTORE_ROISENVI_SAVE_ROIS
ENVI Reference Guide ENVI_GET_ROI_IDS
264 Chapter 2: ENVI Routines
ENVI_GET_ROI_INFORMATION
This procedure returns information associated with defined ROIs.
Syntax
ENVI_GET_ROI_INFORMATION, ROI_IDS [, /LONG_NAME] [, NL=variable] [, NPTS=variable] [, NS=variable] [, ROI_COLORS=variable] [, ROI_NAMES=variable] [, /SHORT_NAME ]
Arguments
ROI_IDS
This argument contains the IDs of defined ROIs from which to get information. ROI_IDS is returned from the function ENVI_GET_ROI_IDS.
Keywords
LONG_NAME (optional)Set this keyword to return the ROI name, ROI color, number of points, and associated image size in the variable specified by ROI_NAMES. You cannot set this keyword if you set SHORT_NAME.
NL (optional)Use this keyword to specify a named variable containing the number of lines associated with the desired ROIs.
NPTS (optional)Use this keyword to specify a named variable that contains the number of points associated with each ROI ID.
NS (optional)Use this keyword to specify the number of samples associated with the desired ROIs.
ROI_COLORS (optional)Use this keyword to specify a named variable that contains the RGB color value for each ROI ID. ROI_COLORS is a byte array of size [3, #ROI IDs].
ROI_NAMES (optional)Use this keyword to specify a named variable that contains a string array of ROI names for each ROI ID. The default name includes the ROI name, ROI color, and number of points. Set the keyword SHORT_NAME or LONG_NAME to modify the default ROI_NAMES.
SHORT_NAME (optional)Set this keyword to return only the ROI name in the variable specified by ROI_NAMES. You cannot set this keyword if you set LONG_NAME.
ENVI_GET_ROI_INFORMATION ENVI Reference Guide
Chapter 2: ENVI Routines 265
See Also
ENVI_CREATE_ROIENVI_DEFINE_ROIENVI_GET_ROIENVI_GET_ROI_DATAENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_IDSENVI_RESTORE_ROISENVI_SAVE_ROIS
ENVI Reference Guide ENVI_GET_ROI_INFORMATION
266 Chapter 2: ENVI Routines
ENVI_GET_SLICE
This function returns the requested spectral slice of data in BIP or BIL storage order. The dimensions of a BIL slice are always [number of samples, number of bands]. A BIP slice is the transpose of the BIL slice, so dimensions are [number of bands, number of samples].
Syntax
Result = ENVI_GET_SLICE(/BIL, /BIP, FID=file ID, LINE=integer, POS=array, XE=value, XS=value)
Keywords
BIL
Set this keyword to return the data in BIL format.
BIP
Set this keyword to return the data in BIP format.
FID
See “Common Keywords” on page 34 for a definition of this keyword.
POS
See “Common Keywords” on page 34 for a definition of this keyword.
LINE
Use this keyword to specify the line number to extract the slice from. LINE is a zero-based number.
XE
Use this keyword to specify the x ending value. XE is a zero-based number.
XS
Use this keyword to specify the x starting value. XS is a zero-based number.
Example
Return line 20, pixels 20 through 40, bands 1 and 3.
data = envi_get_slice(fid=fid, line=20, pos=[1,3], $xs=20, xe=40)
ENVI_GET_SLICE ENVI Reference Guide
Chapter 2: ENVI Routines 267
ENVI_GET_STATISTICS
This procedure reads data from an ENVI statistics file (.sta). The value of POS and CPOS, depending on the statistics retrieved, indicate which bands have valid statistics values.
NoteThe existence of a statistics file does not guarantee that statistics are computed for all bands. Always check POS and CPOS. In fact, a NULL statistics file may exist where POS= -1 and CPOS= -1.
Syntax
ENVI_GET_STATISTICS, STA_Name, COV=variable, CPOS=variable, DMAX=variable, DMIN=variable, EVAL=variable, EVEC=variable, MEAN=variable, POS=variable, STDV=variable
Arguments
STA_Name
This is the filename of an ENVI statistics file (.sta).
Keywords
COV
Set this keyword to specify a named variable that contains the covariance for the image. If COV is undefined, the covariance was not calculated. COV is a [nb, nb] array, where nb is defined by CPOS.
CPOS
Set this keyword to specify a named variable that contains the array of band indices used to calculate COV, EVAL, and EVEC. The value of CPOS can be [-1], in which case COV, EVAL, and EVEC are invalid.
DMAX
Set this keyword to specify a named variable that contains the image maximums. If DMAX is undefined, the basic statistics were not calculated. DMAX is a [nb] array, where nb is defined by POS.
DMIN
Set this keyword to specify a named variable that contains the image minimum. If DMIN is undefined, the basic statistics were not calculated. DMIN is a [nb] array, where nb is defined by POS.
ENVI Reference Guide ENVI_GET_STATISTICS
268 Chapter 2: ENVI Routines
EVAL
Set this keyword to specify a named variable that contains the eigenvalues for the image. If EVAL is undefined, the eigenvalues were not calculated. EVAL is a [nb, nb] array, where nb is defined by CPOS.
EVEC
Set this keyword to specify a named variable that contains the eigenvectors for the image. If EVEC is undefined, the eigenvectors were not calculated. EVEC is a [nb, nb] array, where nb is defined by CPOS.
MEAN
Set this keyword to specify a named variable that contains the image mean. If MEAN is undefined, the basic statistics were not calculated. MEAN is a [nb] array, where nb is defined by POS.
POS
Set this keyword to specify a named variable that contains the array of band indices used to calculate basic statistics, DMIN, DMAX, MEAN, and STD. The value of POS can be [-1], in which case DMIN, DMAX, MEAN and STD are invalid.
STDV
Set this keyword to specify a named variable that contains the image standard deviation. If STDV is undefined, the basic statistics were not calculated. STDV is a [nb] array, where nb is defined by POS.
Example
This example calculates statistics from the file myimage.sta and prints the minimum, maximum, and mean for each band for which statistics were calculated.
envi_get_statistics, '/data/myimage.sta', mean=mean, $dmax=dmax, dmin=dmin, pos=pos
if (pos[0] eq -1) then returnfor i=0, n_elements(pos)-1 do $
print, 'Band ', pos[i], dmin[i], dmax[i], mean[i]
ENVI_GET_STATISTICS ENVI Reference Guide
Chapter 2: ENVI Routines 269
ENVI_GET_TILE
This function returns the requested tile data. Tiles may be requested multiple times and in any order between the ENVI_INIT_TILE and ENVI_TILE_DONE calls.
Syntax
Result = ENVI_GET_TILE(Tile_ID, Cur_tile, BAND_INDEX=variable, YE=variable, YS=variable)
Arguments
Tile_ID
This is the tile ID returned from ENVI_INIT_TILE.
Cur_tile
This is the tile number for the requested tile. This number must be between 0 and the number of tiles minus 1.
Keywords
BAND_INDEX
If the current file is in BSQ tile interleave format, use this keyword to specify a named variable that contains the index to the current band.
YE
Use this keyword to specify a named variable that contains the ending y value for the current tile, in file coordinates.
YS
Use this keyword to specify a named variable that contains the starting y value for the current tile, in file coordinates. For spatially subsetted images, the first YS is equal to the first line in the subset image, which is not necessarily line 0.
ENVI Reference Guide ENVI_GET_TILE
270 Chapter 2: ENVI Routines
Example
This example illustrates the tile processing loop.
for i=0, num_tiles-1 do begin tile_data=envi_get_tile(tile_id, i, ys=ys).tile processing commands here
endfor
Notes
When trying to determine the output line number, be sure to subtract the spatial subset index DIMS[3] from the returned YS:
ys_memory = ys-dims[3]
See Also
ENVI_INIT_TILEENVI_TILE_DONE
ENVI_GET_TILE ENVI Reference Guide
Chapter 2: ENVI Routines 271
ENVI_GLT_DOIT
This procedure builds a GLT file for the corresponding x and y map location images. These and the associated map projection are used to build the GLT file in the specified output projection. You can also specify a rotation for the output GLT image. GLT images are then used to georeference additional images.
Syntax
ENVI_DOIT, 'ENVI_GLT_DOIT', DIMS=array, I_PROJ=structure, /IN_MEMORY, O_PROJ=structure, OUT_NAME=string, PIXEL_SIZE=value [, R_FID=file ID] [, ROTATION=value] [, /SUPER] , X_FID=file ID, X_POS=array, Y_FID=file ID, Y_POS=array
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
DIMS
IN_MEMORY
OUT_NAME
R_FID (optional)
I_PROJ
Use this keyword to specify the input projection for the x and y map location images. Both x and y must be in the same projection. You cannot set I_PROJ to the Arbitrary projection. I_PROJ is a projection structure returned from ENVI_PROJ_CREATE or ENVI_GET_PROJECTION.
O_PROJ
Use this keyword to specify the output projection for the GLT file. You cannot set O_PROJ to the Arbitrary projection. O_PROJ is a projection structure returned from ENVI_PROJ_CREATE or ENVI_GET_PROJECTION.
PIXEL_SIZE
Set this keyword to a scalar value that represents both the x and y pixel size of the output GLT image. Set these individually to this scalar value. The default value is calculated from the pixel size of the input projection.
ROTATION (optional)Use this keyword to specify the rotation of the GLT image in the defined output projection. Rotation is expressed in degrees clockwise from north. The default is to calculate the rotation of the input x and y map location images. To set the GLT output image to north up, specify ROTATION=0.
ENVI Reference Guide ENVI_GLT_DOIT
272 Chapter 2: ENVI Routines
SUPER (optional)Set this keyword to output a super GLT file. If you set this keyword, then you must specify OUT_NAME, in which case the keyword IN_MEMORY is ignored.
X_FID
Use this keyword to specify the file ID for the x map projection values file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. X_FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
X_POS
Use this keyword to specify the band position of the x map projection values. X_POS is an array of long integers, ranging from 0 to the number of bands minus 1.
Y_FID
Use this keyword to specify the file ID for the y map projection values file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. Y_FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
Y_POS
Use this keyword to specify the band position of the y map projection values. Y_POS is an array of long integers, ranging from 0 to the number of bands minus 1.
Example
See ENVI_GEOREF_FROM_GLT_DOIT for an example of using ENVI_GLT_DOIT.
See Also
ENVI_GEOREF_FROM_GLT_DOITENVI_REGISTER_DOIT
ENVI_GLT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 273
ENVI_GRID_DOIT
Use this procedure to convert a set of irregularly gridded x,y,z points to a raster image.
Syntax
ENVI_DOIT, 'ENVI_GRID_DOIT' [, /EXTRAP] [, I_PROJ=structure], /IN_MEMORY, INTERP={0 | 1}, O_PROJ=structure, OUT_DT={1 | 2 | 3 | 4 | 5 | 6}, OUT_NAME=string, PIXEL_SIZE=array, R_FID=variable [, XMAX=value] [, XMIN=value], X_PTS=array [, YMAX=value] [, YMIN=value], Y_PTS=array, Z_PTS=array
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
IN_MEMORY
OUT_NAME
R_FID
EXTRAP (optional)Set this keyword to allow extrapolation to the outer edge of the image. Otherwise, the image is defined by the bounding polygon around the exterior points, and all other points are set to 0.
I_PROJ (optional)Use this keyword to specify the input map projection structure for the irregularly gridded arrays of points, X_PTS and Y_PTS. Use ENVI_PROJ_CREATE to define a projection. ENVI projection structures are defined in greater detail in Appendix D, “ENVI Map Projections” in the ENVI User’s Guide.
INTERP
Set this keyword to one of the following values to specify the type of interpolation.
• 0: Linear
• 1: Quintic
O_PROJ
Use this keyword to specify the output map projection structure for the gridded points. The points are automatically converted from the input projection to the output projection. Use ENVI_PROJ_CREATE to define a projection. ENVI projection structures are defined in greater detail in Appendix D, “ENVI Map Projections”in the ENVI User’s Guide.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
ENVI Reference Guide ENVI_GRID_DOIT
274 Chapter 2: ENVI Routines
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
PIXEL_SIZE
Use this keyword to specify the pixel size of the output image. PIXEL_SIZE is a two-element array of floating-point values representing the x and y pixel sizes, respectively.
XMAX (optional)Use this keyword to specify the maximum x value to use. The default is to use the maximum of the X_PTS array.
XMIN (optional)Use this keyword to specify the minimum x value to use. The default is to use the minimum of the X_PTS array.
X_PTS
Use this keyword to specify a corresponding array of irregularly gridded x points. The number of elements of X_PTS, Y_PTS, and Z_PTS must be equal.
YMAX (optional)Use this keyword to specify the maximum y value to use. The default is to use the maximum of the Y_PTS array.
YMIN (optional)Use this keyword to specify the minimum y value to use. The default is to use the minimum of the Y_PTS array.
Y_PTS
Use this keyword to specify a corresponding array of irregularly gridded y points. The number of elements of X_PTS, Y_PTS, and Z_PTS must be equal.
Z_PTS
Use this keyword to specify a corresponding array of irregularly gridded z points. The number of elements of X_PTS, Y_PTS, and Z_PTS must be equal.
Example
forward_function envi_proj_create
pro example_envi_grid_doit ;
ENVI_GRID_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 275
; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the necessary variables ; x_pts = [0, 500, 500, 0, 250] y_pts = [0, 0, 500, 500, 250] z_pts = [0, 100, 200, 300, 1000] o_proj = envi_proj_create(/arbitrary) pixel_size = [1.,1.] out_name ='testimg' ; ; Call the doit ; envi_doit, 'envi_grid_doit', $ x_pts=x_pts, y_pts=y_pts, $ z_pts=z_pts, out_dt=2, $ pixel_size=pixel_size, $ o_proj=o_proj, extrap=1, $ out_name=out_name, interp=1, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide ENVI_GRID_DOIT
276 Chapter 2: ENVI Routines
ENVI_GS_SHARPEN_DOIT
This procedure performs Gram-Schmidt spectral sharpening, which sharpens a low spatial resolution multispectral image using associated high spatial resolution panchromatic bands. These two datasets are coregistered on the fly if they are both georeferenced. You can specify the low spatial resolution spectral band, or it can be determined from the low spatial resolution multispectral image.
NoteEnsure that you have adequate disk space before performing a Gram-Schmidt transformation, because this process creates an output file and several temporary files. An error message will appear during the process if you do not have adequate disk space.
Syntax
ENVI_DOIT, 'ENVI_GS_SHARPEN_DOIT', DIMS=array, FID=file ID [, FILTER_FID=variable] [, HIRES_DIMS=array], HIRES_FID=file ID, HIRES_POS=array, /IN_MEMORY [, INTERP={0 | 1 | 2}] [, LORES_DIMS=array] [, LORES_FID=array] [, LORES_POS=array] [, M_FID=file ID] [, M_POS=array] [, MASK_VALUE=value], METHOD={0 | 1} [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=file ID]
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY
M_FID (optional)
M_POS (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
FILTER_FID (optional)Use this keyword to specify a named variable representing the filter file ID to be used with METHOD=2 or 3. The filter file is in the form of a spectral library and contains the spectral response functions for the bands in a multispectral image. This file is only needed if the functions do not already exist in ENVI.
ENVI_GS_SHARPEN_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 277
FILTER_POS (optional)Use this keyword to specify a scalar representing the index (position/location) of the filter function in the specified spectral library. If you do not specify a value for FILTER_POS, the default value is 0, and the first filter function in the library is used.
HIRES_DIMS (optional)Use this keyword to specify the spatial dimensions of the high spatial resolution panchromatic band. HIRES_DIMS is a five-element array of long integers with the following definitions:
• HIRES_DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• HIRES_DIMS[1]: The starting sample number. The first x pixel is 0.
• HIRES_DIMS[2]: The ending sample number
• HIRES_DIMS[3]: The starting line number. The first y pixel is 0.
• HIRES_DIMS[4]: The ending line number
HIRES_FID
Use this keyword to specify the file ID for the high spatial resolution panchromatic file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
HIRES_POS
Use this keyword to specify the band position of the high spatial resolution panchromatic band. HIRES_POS is an array of long integers, ranging from 0 to the number of bands minus 1.
INTERP (optional)Set this keyword to one of the following values to specify the resampling method:
• 0: Nearest neighbor
• 1: Bilinear interpolation
• 2: Cubic convolution
The low spatial resolution images are resampled to the high resolution space using the specified resampling method. The default method is nearest neighbor.
LORES_DIMS (optional)Use this keyword to specify the spatial dimensions of the low spatial resolution spectral band. You must specify LORES_DIMS if METHOD=1. LORES_DIMS is a five-element array of long integers with the following definitions:
• LORES_DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• LORES_DIMS[1]: The starting sample number. The first x pixel is 0.
• LORES_DIMS[2]: The ending sample number
ENVI Reference Guide ENVI_GS_SHARPEN_DOIT
278 Chapter 2: ENVI Routines
• LORES_DIMS[3]: The starting line number. The first y pixel is 0.
• LORES_DIMS[4]: The ending line number
LORES_FID (optional)Use this keyword to specify the file ID for the low spatial resolution multispectral file. You must specify LORES_FID if METHOD=1. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. LORES_FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
LORES_POS (optional)Use this keyword to specify the band position of the low spatial resolution spectral band. You must specify LORES_POS if METHOD=1. LORES_POS is an array of long integers, ranging from 0 to the number of bands-1.
MASK_VALUE (optional)Use this keyword to specify the output value for the masked pixels. MASK_VALUE is only used when you specify M_FID and M_POS. The default value is 0.
METHOD
Use this keyword to specify the method for creating the low spatial resolution simulated panchromatic image. Set METHOD to one of the following values.
• 0: Average all the bands specified by POS to simulate a low resolution simulated panchromatic image
• 1: Use the low spatial resolution spectral band specified by LORES_FID, LORES_DIMS, and LORES_POS. The algorithm assumes that the low spatial resolution spectral bands correspond to the high spatial resolution panchromatic band.
• 2: Create a low spatial resolution simulated panchromatic image using a high spatial resolution panchromatic filter function. If you specify this value, you must use the keyword F_FID. The low spatial resolution spectral bands must fall in the range of the high spatial resolution panchromatic band or they will not be included in the resampling process.
• 3: Create a low spatial resolution simulated panchromatic image using a user-defined filter function. If you specify this value, you must use the F_FID keyword. The low spatial resolution spectral bands must fall in the range of the high spatial resolution panchromatic band or they will not be included in the resampling process.
See Also
ENVI_PC_SHARPEN_DOITSHARPEN_DOIT
ENVI_GS_SHARPEN_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 279
ENVI_ICA_DOIT
Syntax | Keywords | Example | See Also
Use the Independent Component Analysis (ICA) procedure to transform a set of mixed, random signals into components that are mutually independent.
Syntax
ENVI_DOIT, 'ENVI_ICA_DOIT', FID=file ID, POS=array, DIMS=array [, M_FID=file ID] [, M_POS=value] [, /IN_MEMORY] [, MASK_VAL=value], OUT_NAME=string [, OUT_BNAME=string array] [, OUT_NB=long integer] [, SAMPLE_DIMS=array] [, SAMPLE_XFAC=floating point] [, SAMPLE_YFAC=floating point] [, FUNC_INDEX={0 | 1 | 2}] [, COEFF=variable] [, THRESH=value] [, ITERATIONS=integer] [, STABILIZE_ITERATIONS=integer] [, OUT_TRANS_NAME=string] [, /SORT_OUTPUT}] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
IN_MEMORY (optional)
OUT_NAME
OUT_BNAME (optional)
R_FID (optional)
MASK_VAL (optional)
Use this keyword to specify the value for the masked pixels output. This keyword is valid only when you specify the M_FID and M_POS keywords. The default is 0.0.
OUT_NB (optional)
Use this keyword to specify the number of output IC bands. The default value is the number of input bands. For anomaly detection where the feature of interest occupies only a small portion of all pixels, it is not recommended to reduce the dimension of the data, as the anomaly will be buried in the noisy bands of PCA during data whitening.
ENVI Reference Guide ENVI_ICA_DOIT
280 Chapter 2: ENVI Routines
SAMPLE_DIMS (optional)
Use this five-element array of long integers that defines the spatial subset to define IC sample data. The default is the value set for the DIMS keyword. Defining a sample spatial subset smaller than the whole image can fit the IC sample into memory and increase computation speed, and helps concentrate the IC analysis on the features of interest in the spatial subset or ROI.
SAMPLE_XFAC (optional)
Use this keyword to specify the x resize factor for the IC sample data. The default is 1 (does not change the data). A value less than 1 causes the size to decrease. For example, using a resize factor of 0.5 will use every other pixel in the IC sample. Beware that setting this value to a small number could lose features of interest, as those pixels may be discarded.
SAMPLE_YFAC (optional)
Use this keyword to specify the y resize factor for the IC sample data. The default is 1 (does not change the data). A value less than 1 causes the size to decrease. For example, using a resize factor of 0.5 will use every other pixel in the IC sample. Beware that setting this value to a small number could lose features of interest, as those pixels may be discarded.
FUNC_INDEX (optional)
Use this keyword to specify the contrast function to use. Choose one of the following:
• 0: LogCosh (default)
• 1: Kurtosis
• 2: Gaussian
LogCosh is a good general-purpose contrast function.
COEFF (optional)
Use this keyword when using LogCosh as the contrast function. Specify a coefficient value between 1.0 and 2.0. The default is 1.0.
THRESH (optional)
Use this keyword to specify a floating-point or double-precision minimum change threshold for IC optimization. Specify a value from 0 to 1. The default is 0.0001. The allowable range is 10-8 to 10-2. Increasing this value increases the speed of convergence, but may provide a less optimal solution.
ITERATIONS (optional)
Use this keyword to specify the maximization iterations for IC optimization using a fixed-point algorithm. The default value is 100. More iterations helps ENVI find more optimal components; however, each iteration adds to processing time, depending on the CPU and system load.
ENVI_ICA_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 281
STABILIZE_ITERATIONS (optional)
Use this keyword to specify the maximization iterations for IC optimization using a stabilized fixed-point algorithm. When estimating one independent component, the fixed-point algorithm runs first. If the algorithm does not converge after maximization iterations, then the stabilized fixed-point algorithm runs to improve convergence. The default is 100. Enabling stabilization and increasing stabilization iterations helps ENVI find the optimal components; however, each iteration adds to processing time, depending on the CPU and system load.
OUT_TRANS_NAME (optional)
Use this keyword to specify the output transform filename and path. You can use this file in future IC calculations on the same image, or on an image with similar features.
SORT_OUTPUT (optional)
If the keyword is set, ENVI sorts output IC bands by decreasing spatial coherence. Use this option if a noisy band could appear as the first IC.
Example
This example performs a forward transform.
pro example_envi_ica_doit
; First restore all the base save files envi, /restore_base_save_files ; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt envi_batch_init, log_file=’batch.txt’
; Open the input file filename = filepath(’cup95eff.int’, $ root=envi_get_path(), subdir=[’data’]) envi_open_file, filename, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; Set forward IC rotation parameters envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_nb = 12L out_name = ’cuprite_ica’ out_trans_name = ’cuprite_ica.trans’
; Call the forward IC rotation doit routine envi_doit, ’envi_ica_doit’, $ fid=fid, pos=pos, dims=dims, $ /sort_output, out_nb=out_nb, $ out_name=out_name, $ out_trans_name=out_trans_name
; Exit ENVI
ENVI Reference Guide ENVI_ICA_DOIT
282 Chapter 2: ENVI Routines
envi_batch_exit end
See Also
ENVI_ICA_INV_DOIT
ENVI_ICA_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 283
ENVI_ICA_INV_DOIT
Syntax | Keywords | Example | See Also
Use the Independent Component Analysis (ICA) inverse procedure to transform independent components back into their original data space.
Syntax
ENVI_DOIT, 'ENVI_ICA_INV_DOIT', FID=file ID, POS=array, DIMS=array [, M_FID=file ID] [, M_POS=value], TRANS_NAME=string [, /IN_MEMORY], OUT_NAME=string [, OUT_BNAME=string array] [, OUT_DT={1 | 2 | 3 | 4 | 5 | 12 | 13 | 14 | 15}] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
IN_MEMORY (optional)
OUT_NAME
OUT_BNAME (optional)
R_FID (optional)
TRANS_NAME
Use this keyword to specify the name of the transform file (.trans) to use.
OUT_DT (optional)
This keyword specifies the data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits) (default)
• 5: Double-precision floating-point (64 bits)
ENVI Reference Guide ENVI_ICA_INV_DOIT
284 Chapter 2: ENVI Routines
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
Example
This example first performs a forward transform to achieve dimension reduction, then follows with an inverse transform.
pro example_envi_ica_inv_doit
; First restore all the base save files envi, /restore_base_save_files ; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt envi_batch_init, log_file=’batch.txt’
; Open the input file filename = filepath(’cup95eff.int’, $ root=envi_get_path(), subdir=[’data’]) envi_open_file, filename, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; Set forward IC rotation parameters envi_file_query, fid, dims=dims, nb=nb, $ data_type=data_type pos = lindgen(nb) out_nb = 12L out_name = ’cuprite_ica’ trans_name = ’cuprite_ica.trans’
; Call the forward IC rotation doit routine envi_doit, ’envi_ica_doit’, $ fid=fid, pos=pos, dims=dims, $ /sort_output, out_name=out_name, $ out_nb=out_nb, out_trans_name=trans_name, $ r_fid=r_fid
; Set inverse IC rotation parameters out_name = ’cuprite_ica_inv’ pos = lindgen(out_nb) ; Call the inverse IC rotation doit routine envi_doit, ’envi_ica_inv_doit’, $ fid=r_fid, pos=pos, dims=dims, $ trans_name=trans_name, out_dt=data_type, $ out_name=out_name ; Exit ENVI envi_batch_exit
ENVI_ICA_INV_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 285
end
See Also
ENVI_ICA_DOIT
ENVI Reference Guide ENVI_ICA_INV_DOIT
286 Chapter 2: ENVI Routines
ENVI_INFO_WID
Use this procedure to display an ENVI report widget. The contents of the string argument are displayed in a text widget. An interactive ENVI session is required to run this procedure.
Syntax
ENVI_INFO_WID, Str [, TITLE=string] [, XS=integer] [, YS=integer]
Arguments
Str
This is an array of strings to display in the text widget. Each element in the string array is displayed on a separate line. Use a null value ('') for a blank line.
Keywords
TITLE (optional)Use this optional string keyword to specify the title of the report widget.
XS (optional)Use this keyword to specify the number of columns in the text widget.
YS (optional)Use this keyword to specify the number of rows in the text widget.
Example
This example displays three lines of text with one blank line in a report widget.
str = ['Line 1', 'Next line is blank', '', 'Line 4']envi_info_wid, str, title='Report'
Figure 14-2: ENVI Report Widget
ENVI_INFO_WID ENVI Reference Guide
Chapter 2: ENVI Routines 287
ENVI_INIT_TILE
This function is used to initialize processing of tile data. The returned value is the tile ID used to access the data.
Syntax
Result = ENVI_INIT_TILE(FID, POS [, /COMPLEX] [, INTERLEAVE={0 | 1 | 2}] [, MATCH_ID=value] [, NUM_TILES=variable] [, OVERLAP=value] [, TILE_SCALE=integer] [, XE=value] [, XS=value] [, YE=value] [, YS=value])
Arguments
FID
This is the file ID of the file to process.
POS
This is the array of band positions to process.
Keywords
COMPLEX (optional)Set this keyword to return the output data type as complex.
INTERLEAVE (optional)Set this keyword to one of the following integer values to specify the interleave output. The default is to perform the same type of interleave as the file.
• 0: BSQ
• 1: BIL
• 2: BIP
MATCH_ID (optional)Set this keyword equal to the tile ID of a previously initialized piece of tile data to match the tile size of the current data to the size of the previously initialized data. MATCH_ID acquires the same spatial tile from multiple bands or images so that processing is done on the same area in each case. Do not use this keyword in combination with the XE, XS, YE, and YS keywords.
NUM_TILES (optional)Use this keyword to specify a named variable that contains the number of tiles in the request.
OVERLAP (optional)Use this keyword to specify the pixel overlap wanted for each spatial tile. Use OVERLAP only when INTERLEAVE=0.
ENVI Reference Guide ENVI_INIT_TILE
288 Chapter 2: ENVI Routines
TILE_SCALE (optional)Use this keyword to adjust the size (in bytes) of the default spatial tile size in ENVI. A value of 2 causes the tile to be half as large. A value of 4 causes the tile to be a quarter as large. This keyword overrides the Image Tile Size preference in ENVI.
XE (optional)Use this keyword to specify the x ending index. The default is the last sample.
XS (optional)Use this keyword to specify the x starting index. The default is the first sample.
YE (optional)Use this keyword to specify the y ending index. The default is the last line.
YS (optional)Use this keyword to specify the y starting index. The default is the first line.
Example
This example initializes the file processing for FID and the bands in the POS array. The value of NUM_TILES is now the total loop count for processes all the tiles.
tile_id=envi_init_tile(fid, pos, num_tiles=num_tiles)
Notes
You must run ENVI_INIT_TILE before requesting tiled data.
See Also
ENVI_GET_TILEENVI_TILE_DONE
ENVI_INIT_TILE ENVI Reference Guide
Chapter 2: ENVI Routines 289
ENVI_IO_ERROR
Use this procedure to report I/O processing errors.
Syntax
ENVI_IO_ERROR, Proc [, UNIT=integer]
Arguments
Proc
This is a text string to be echoed to the terminal when an I/O error occurs. Generally, Proc should be the name of the procedure in which ENVI_IO_ERROR is called.
Keywords
UNIT (optional)Use this keyword to specify the unit number of the output file being generated. If you specify UNIT and an error occurs, ENVI_IO_ERROR will delete this file.
Example
The following example shows how to display an I/O error when MY_ERROR does not equal 0.
if (my_error ne 0) then $envi_io_error, 'An error occurred in my processing.'
ENVI Reference Guide ENVI_IO_ERROR
290 Chapter 2: ENVI Routines
ENVI_LAYER_STACKING_DOIT
Use this procedure to build a new multi-band file from georeferenced images of various pixel sizes, extents, and projections. The input bands will be resampled and reprojected to a common output projection and pixel size. The output file will contain only data based on the map extent of the input images. You can select either an inclusive (encompass all the files) or exclusive (encompass file overlap) output image.
Syntax
ENVI_DOIT, 'ENVI_LAYER_STACKING_DOIT', DIMS=array [, /EXCLUSIVE], FID=file ID [, /IN_MEMORY] [, INTERP={0 | 1 | 2}] [, OUT_BNAME=string array] [, OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}], OUT_NAME=string, OUT_PROJ=structure, OUT_PS=array, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
R_FID
EXCLUSIVE (optional)
Set this keyword to specify an exclusive range (encompassing file overlap) based on the map extent of each input layer. The default is an inclusive range, encompassing all files. The spatial size of a layer-stacked image generated with the EXCLUSIVE keyword set will always be equal to or smaller than the inclusive result.
FID
Use this keyword to specify the file IDs for the input files. FID is an array of input file IDs with one file ID for each input file (layer). This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1. The number of elements of POS and FID correspond to the number of input files to stack together, one entry for each file.
INTERP (optional)
Set this keyword to one of the following values to specify the resampling method.
• 0: Nearest neighbor
• 1: Bilinear
• 2: Cubic convolution
ENVI_LAYER_STACKING_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 291
The default method is nearest neighbor.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
OUT_PROJ
Use this keyword to specify the output projection for the layer-stacked file. OUT_PROJ is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE.
OUT_PS
Use this keyword to specify the output x and y pixel size. OUT_PS is a two-element, double-precision array of the output x and y pixel sizes, respectively. OUT_PS has the same units specified in OUT_PROJ.
POS
Use this keyword to specify an array of band positions, indicating the band numbers on which to perform the operation. POS is an array of long integers with one entry for each input file, with values ranging from 0 to the number of bands minus 1. The number of elements of POS and FID correspond to the number of input files to stack together, one entry for each file.
Example
The following example is used to layer stack the Bighorn TM and DEM images. This example uses the following files found in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number):
• bhtmref.img
• bhtmref.hdr
and the following files found in the bh_3d directory of the ENVI Resource DVD that shipped with your software:
ENVI Reference Guide ENVI_LAYER_STACKING_DOIT
292 Chapter 2: ENVI Routines
• Bhdemsub.img
• bhdemsub.hdr
The example uses an inclusive range (encompassing all the files) with cubic convolution resampling. Each of the six TM bands and the single DEM band are output to a new layer-stacked image with the same projection as the TM data.
forward_function envi_get_projection
pro example_envi_layer_stacking_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the first input file. ; We will also open the one band ; dem file to layer stack with ; this file. ; envi_open_file, 'bhtmref.img', r_fid=t_fid if (t_fid eq -1) then begin envi_batch_exit return endif ; ; Open the second input file. ; envi_open_file, 'bhdemsub.img', r_fid=d_fid if (d_fid eq -1) then begin envi_batch_exit return endif ; ; Use all the bands from both files ; and all spatial pixels. First build the ; array of FID, POS and DIMS for both ; files. ; envi_file_query, t_fid, $ ns=t_ns, nl=t_nl, nb=t_nb envi_file_query, d_fid, $ ns=d_ns, nl=d_nl, nb=d_nb ; nb = t_nb + d_nb fid = lonarr(nb) pos = lonarr(nb) dims = lonarr(5,nb) ; for i=0L,t_nb-1 do begin fid[i] = t_fid pos[i] = i dims[0,i] = [-1,0,t_ns-1,0,t_nl-1]
ENVI_LAYER_STACKING_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 293
endfor ; for i=t_nb,nb-1 do begin fid[i] = d_fid pos[i] = i-t_nb dims[0,i] = [-1,0,d_ns-1,0,d_nl-1] endfor ; ; Set the output projection and ; pixel size from the TM file. Save ; the result to disk and use floating ; point output data. ; out_proj = envi_get_projection(fid=t_fid, $ pixel_size=out_ps) out_name = 'testimg' out_dt = 4 ; ; Call the layer stacking routine. Do not ; set the exclusive keyword allow for an ; inclusive result. Use cubic convolution ; for the interpolation method. ; envi_doit, 'envi_layer_stacking_doit', $ fid=fid, pos=pos, dims=dims, $ out_dt=out_dt, out_name=out_name, $ interp=2, out_ps=out_ps, $ out_proj=out_proj, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_CONVERT_FILE_MAP_PROJECTIONMOSAIC_DOIT
ENVI Reference Guide ENVI_LAYER_STACKING_DOIT
294 Chapter 2: ENVI Routines
ENVI_MAP_INFO_CREATE
This function returns an ENVI map information structure for any of the supported map projections; see “Map Projections” in the ENVI User’s Guide. Arbitrary, Geographic, UTM, and State Plane map information structures use their corresponding keyword. All other projections use the PROJ keyword to define the associated projection. You can define projections using the procedure ENVI_PROJ_CREATE. With optional keywords, you can define the datum, name, units, projection parameters, pixel size, rotation, and map coordinates. The result of this function can be used for functions that require an input MAP_INFO structure. For example, to georeference an image, ENVI_SETUP_HEAD requires an input MAP_INFO structure.
NoteUse this function instead of accessing the map information structure directly.
Syntax
Result = ENVI_MAP_INFO_CREATE([, /ARBITRARY] [, DATUM=value] [, /GEOGRAPHIC] [, /MAP_BASED], MC=array [, NAME=string] [, PARAMS=array] [, PE_COORD_SYS_CODE=integer] [, PE_COORD_SYS_STR=string] [, PROJ=structure], PS=array [, ROTATION=value] [, /SOUTH] [, /STATE_PLANE] [, TYPE=integer] [, UNITS=integer] [, /UTM] [, ZONE=integer])
Keywords
ARBITRARY (optional)Set this keyword to create an Arbitrary projection for the map information. Set the keyword MAP_BASED to create a map-based projection. The default is a non-map based projection. A map-based projection uses the lower-left corner of the image as the projection origin, while a pixel-based projection (non-map based) uses the upper-left corner as the origin.
DATUM
Use this keyword to specify the datum for the map information projection. The default for a Geographic projection is WGS-84, and the default for UTM and State Plane projections is North America 1927 (NAD27). All other projections default to no datum. The exact name that ENVI uses for each datum is listed in the datum.txt file in the map_proj directory of your ENVI installation.
GEOGRAPHIC (optional)Set this keyword to create a Geographic projection for the map information.
MAP_BASED (optional)Set this keyword to interpret the Arbitrary projection as map-based. This keyword does not have any effect for other projections.
ENVI_MAP_INFO_CREATE ENVI Reference Guide
Chapter 2: ENVI Routines 295
MC
Set this keyword to specify the map location tie point, which is the reference point for a pixel at a known map coordinate. MC is a four-element double-precision array where,
• MC[0]: x pixel location corresponding to the x map location, MC[2]
• MC[1]: y pixel location corresponding to the y map location, MC[3]
• MC[2]: is the x map location corresponding to the x pixel location, MC[0]
• MC[3]: is the y map location corresponding to the y pixel location, MC[1]
NAME (optional)Use this keyword to specify a string variable with the name of the map information projection.
PARAMS (optional)Use this keyword to specify the parameters for the map information projection. PARAMS is a array of double-precision values with 1 to 15 elements. The number of elements is determined by the projection type (see the TYPE keyword). Do not use PARAMS with Arbitrary, Geographic, State Plane, or UTM projections. See “ENVI Map Projections” in the ENVI User’s Guide for a full list of projection types and their corresponding projection parameters. The PARAMS keyword must contain all projection parameters listed in the above document (for the specified projection) except the datum and name, which you specify using the DATUM and NAME keywords, respectively.
PE_COORD_SYS_CODE (optional)Use this keyword to pass in a valid geographic (GEOGCS) or projected (PROJCS) coordinate system code, typically a five-digit number. Refer to the Tech Tips on the ITT Visual Information Solutions website for predefined GEOGCS and PROJCS coordinate systems,which include the valid codes to use.
1. Go to http://www.ittvis.com/services/search.asp.
2. In the Enter Keyword field, type projection engine.
3. Click Submit.
4. In the search results, open the Tech Tip titled, “ESRI Projection Engine Reference v1.0.”
Set the TYPE keyword to 1 when passing in a GEOGCS code, or set TYPE to 42 when passing in a PROJCS code.
PE_COORD_SYS_STR (optional)Use this keyword to pass in a a geographic (GEOGCS) or projected (PROJCS) coordinate system string. See the instructions under PE_COORD_SYS_CODE to access the pertinent Tech Tip that provides predefined GEOGCS and PROJCS coordinate systems,which include the valid strings to use.
Set the TYPE keyword to 1 when passing in a GEOGCS string, or set TYPE to 42 when passing in a PROJCS string. See Example.
PROJ (optional)
ENVI Reference Guide ENVI_MAP_INFO_CREATE
296 Chapter 2: ENVI Routines
Set this keyword to specify the projection for the map information. PROJ is an ENVI projection structure returned from ENVI_PROJ_CREATE or ENVI_GET_PROJECTION. PROJ is not needed if the keyword ARBITRARY, GEOGRAPHIC, STATE_PLANE, or UTM is used. For all other projections, either set the PROJ keyword or define the projection using the keywords DATUM, NAME, PARAMS, SOUTH, TYPE, UNITS, and ZONE.
PS
Set this keyword to specify the pixel size of the image. PS is a two-element, double-precision array, where:
• PS[0]: x pixel size
• PS[1]: y pixel size
ROTATION (optional)Set this keyword to specify the rotation of the image in the defined projection. Rotation is expressed in degrees clockwise from north.
SOUTH (optional)Set this keyword to specify that the UTM projection is in the southern hemisphere.
STATE_PLANE (optional)Set this keyword to create a State Plane projection for the map information.
TYPE (optional)Use this keyword to specify the map information projection type. TYPE is an integer value corresponding to the projection type. See “ENVI Map Projections” in the ENVI User’s Guide for a full list of projection types and their corresponding projection values.
UNITS (optional)Use this keyword to specify the projection units. UNITS is an integer value indicating the projection units. The function ENVI_TRANSLATE_PROJECTION_UNITS converts projection unit strings to integer values. The default units are degrees for Geographic, feet for State Plane, and meters for all other projections.
UTM (optional)Set this keyword to create a UTM projection for the map information.
ZONE (optional)Use this keyword only with UTM and State Plane projections to specify the zone number.
Example
This example creates a Geographic map information structure with a Geographic projection, default datum of WGS-84, default units of degrees, and a pixel size of one second (1. / 3600). Set the map tie point for the center of the first pixel (0.5, 0.5) to 34.5 degrees north, 117.4 degrees west. This is one of the simplest uses of ENVI_MAP_INFO_CREATE.
;; Set the pixel size and map tie point
ENVI_MAP_INFO_CREATE ENVI Reference Guide
Chapter 2: ENVI Routines 297
; ps = [1D/3600, 1D/3600] mc = [0.5D, 0.5D, -117.4D, 34.5D];; Create the map information; map_info = envi_map_info_create(/geographic, $ mc=mc, ps=ps)
This example creates map information for a UTM projection Zone 23 South with units of kilometers and a North America 1983 datum. Set the map tie point for the upper-left corner of the first pixel to 8339330 North and 177246 East. Use the keywords for ENVI_MAP_INFO_CREATE instead of first creating a projection structure and then using the PROJ keyword.
;; First convert the kilometers to its integer representation; using ENVI_TRANSLATE_PROJECTION_UNITS;units = ENVI_TRANSLATE_PROJECTION_UNITS('km'); Set the datum and map tie points; datum = 'North America 1983'mc = [0D, 0, 177246, 8339330]ps=[30, 30];; Now create the UTM map information;map_info = ENVI_MAP_INFO_CREATE(/UTM, ZONE=23, /SOUT, $
DATUM = datum, UNITS = units, MC = mc, PS = ps)
See Also
ENVI_CONVERT_PROJECTION_COORDINATESENVI_PROJ_CREATEENVI_TRANSLATE_PROJECTION_NAMEENVI_TRANSLATE_PROJECTION_UNITS
ENVI Reference Guide ENVI_MAP_INFO_CREATE
298 Chapter 2: ENVI Routines
ENVI_MASK_APPLY_DOIT
Use this procedure to apply a mask to a file.
Syntax
ENVI_DOIT, 'ENVI_MASK_APPLY_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, M_FID=file ID, M_POS=value, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, VALUE=integer
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY
M_FID
M_POS
OUT_BNAME
OUT_NAME
POS
R_FID
VALUE
Use this keyword to specify the value for each masked pixel in the output image.
Example
PRO apply_mask_example
; Initialize ENVIENVI, /RESTORE_BASE_SAVE_FILESENVI_BATCH_INIT, LOG_FILE = 'batch_log.txt'
; Set the input and output file namesout_name = 'out_file'ENVI_OPEN_FILE, 'image_file.bil', R_FID = fidENVI_OPEN_FILE, 'mask_file.dat', R_FID = m_fidIF (fid EQ -1 OR m_fid EQ -1) THEN BEGIN
ENVI_BATCH_EXITRETURN
ENDIF
ENVI_MASK_APPLY_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 299
; Get some useful information about the input data.ENVI_FILE_QUERY, fid, dims=dims, NB = nb
; Set the keyword parameterspos = LINDGEN(nb)m_pos = [0]
; Call the 'doit'ENVI_MASK_APPLY_DOIT, FID = fid, POS = pos, DIMS = dims, $
M_FID = m_fid, M_POS = m_pos, VALUE = 0, OUT_NAME = out_name, $IN_MEMORY = 0, R_FID = r_fid
; Exit ENVIENVI_BATCH_EXIT
END
ENVI Reference Guide ENVI_MASK_APPLY_DOIT
300 Chapter 2: ENVI Routines
ENVI_NEURAL_NET_DOIT
Use this procedure to perform neural net classification, which is a supervised classification where the net is trained on a set of input ROIs. The keywords ALPHA, ETA, THETA, NUM_SWEEPS, NUM_LAYERS, and RMS_CRIT are associated with training the net. You can use the optional keyword THRESH to set the minimum activation threshold a class must satisfy in order to be classified.
Syntax
ENVI_DOIT, 'ENVI_NEURAL_NET_DOIT', ACT_TYPE={0 | 1}, ALPHA=value, CLASS_NAMES=string array, DIMS=array, ETA=value, FID=file ID, /IN_MEMORY, LOOKUP=array, NUM_CLASSES=integer, NUM_LAYERS=integer, NUM_SWEEPS=integer, OUT_BNAME=string array, OUT_NAME=string, POS=array [, R_FID=variable], RMS_CRIT=value, ROI_ID=array [, RULE_FID=variable] [, /RULE_IN_MEMORY] [, RULE_OUT_BNAME=string array] [, RULE_OUT_NAME=string], THETA=value [, THRESH=value], /TRAIN
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID (optional)
ACT_TYPE
Set this keyword to one of the following values to specify the activation function for training the neural net.
• 0: Logistic
• 1: Hyperbolic
ALPHA
Use this keyword to specify the training momentum. ALPHA is a floating-point or double-precision number between 0.0 and 1.0.
ENVI_NEURAL_NET_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 301
CLASS_NAMES
Use this keyword to specify a string array of class names for classification images. The first element (Class 0) is “Unclassified.” The array has num_classes+1 elements.
ETA
Use this keyword to specify the training rate. ETA is a floating-point or double-precision number between 0.0 and 1.0.
LOOKUP
Use this keyword to specify an byte array of size [3, num_classes+1], containing color tables for the classification image. Each output class can have a unique RGB triplet, ordered as [r, g , b], and the “Unclassified” class typically uses the RGB triplet [0, 0, 0] for black.
NUM_CLASSES
Use this keyword to specify the number of output classes, which is equal to the number of input ROIs as specified by ROI_PTR.
NUM_LAYERS
Use this keyword to specify the number of hidden layers in the neural net classifier. Typically this value is set to 0, 1, or 2.
NUM_SWEEPS
Use this keyword to specify the maximum number of training sweeps to perform count. The actual number of training sweeps may be less than NUM_SWEEPS if error criteria have been met. See the keyword RMS_CRIT below.
RMS_CRIT
Use this keyword to specify the RMS training error criteria. During training, if the RMS error is less than RMS_CRIT, then the training ends and the image is classified according to the trained neural net.
ROI_ID
Use this keyword to specify an array of ROI IDs returned from a call to ENVI_GET_ROI_IDS. Each ID in the array will use the corresponding ROI to train the neural net.
RULE_FID (optional)Use this keyword to specify a named variable that contains the file ID for the processed rule image. This file ID can be used to access the processed data.
RULE_OUT_BNAME (optional)Use this keyword to specify a string array that contains the output band names for the rule image.
RULE_OUT_NAME (optional)
ENVI Reference Guide ENVI_NEURAL_NET_DOIT
302 Chapter 2: ENVI Routines
Use this keyword to specify an output filename for the rule image. If this item is present, the rule image is automatically saved.
RULE_IN_MEMORY (optional)Set this keyword to store output rule images in memory.
THETA
Use this keyword to specify the training threshold contribution. THETA is a floating-point or double-precision number between 0.0 and 1.0.
THRESH (optional)Use this keyword to specify an minimum activation threshold a class must have in order to be classified.
TRAIN
Set this keyword to train the neural net prior to classification.
Example
forward_function envi_get_roi_ids, envi_get_roi_dims_ptrpro example_envi_neural_net_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtm_mnf.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to classify all ; data (spectrally) in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Restore the ROI file used as the ; trainig pixels. Each ROI in the file ; will be considered on input class ; envi_restore_rois, 'bhtm_nd.roi' roi_ids = envi_get_roi_ids(fid=fid, $ roi_colors=lookup, roi_names=class_names) ;
ENVI_NEURAL_NET_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 303
; Specify the neural net training ; criteria. ; theta = .9 eta = .2 alpha = .9 act_type = 0 rms_crit = .1 num_layers = 3 num_sweeps = 1000 ; ; Set the classification variables ; num_classes = n_elements(roi_ids) class_names = ['Unclassified', class_names] lookup = reform([0,0,0, $ reform(lookup,3*num_classes)],3,num_classes+1) ; ; Call the doit ; envi_doit, 'envi_neural_net_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, rule_out_name='', $ theta=theta, eta=eta, alpha=alpha, $ num_classes=num_classes, num_sweeps=num_sweeps, $ num_layers=num_layers, act_type=act_type, $ rms_crit=rms_crit, roi_ids=roi_ids, /train, $ class_names=class_names, lookup=lookup ; ; Exit ENVI ; envi_batch_exitend
See Also
CLASS_DOITCLASS_RULE_DOITCLASS_STATS_DOITENVI_SVM_DOIT
ENVI Reference Guide ENVI_NEURAL_NET_DOIT
304 Chapter 2: ENVI Routines
ENVI_OPEN_DATA_FILE
Use this procedure to open a data file. ENVI supports several standard file types, including formats for selected sensors, military formats, DEM formats, image processing software formats, and generic image formats.
Syntax
ENVI_OPEN_DATA_FILE, Fname [, /ACRES] [, /ADRG] [, /ALOS] [, /ASTER] [, /ATSR] [, /AVHRR] [, /BMP] [, /CADRG] [, /CIB] [, CORRECTED_SRTM_OUT_NAME=filename] [, /COSMOSKYMED] [, /DIMAP] [, /DMSP] [, /DOQ] [, /DRG] [, /ECW] [, /ENVI] [, /ENVISAT] [, /EOSAT_IRS] [, /EOSAT_TM] [, /ERMAPPER] [, /EROS_1A] [, /ERS] [, /ESA_SHARP] [, /ESA_TM] [, /ESRI_GRID] [, /FORMOSAT2] [, /HDF_SD] [, HDFSD_DATASET=value] [, HDFSD_INTERLEAVE={0 | 1 | 2}] [, /IMAGINE] [, /IRS_SUPER] [, /JERS] [, /JP2] [, /JPEG] [, /KOMPSAT2] [, /LANDSAT_METADATA] [, /MAS_50] [, /MRLC] [, /MODIS] [, /MRSID] [, /NITF] [, /NLAPS] [, /PCI] [, /PDS] [, /PICT] [, /PNG] [, /QB_TILE], R_FID=variable [, /RADARSAT] [, /RAPIDEYE] [, /SEAWIFS] [, /SPOT] [, /SRF] [, /SRTM] [, /TIFF] [, /TFRD] [, /TIMS] [, /TOPSAR] [, /WV_TILE] [, /XWD]
Arguments
Fname
Specify the filename to open.
Keywords
Set one of the following optional keywords to specify the type of file being opened.
ACRES (optional)ACRES CCRS Landsat and SPOT data
ADRG (optional)Defense Mapping Agency ARC Digitized Raster Graphics (ADRG) format
ALOS (optional)Advanced Land Observing Satellite. Use this keyword to read data from the Panchromatic Remote sensing Instrument for Stereo Mapping (PRISM) sensor, Advanced Visible Near-Infrared Radiometer (AVNIR-2) sensor, or Phased Array type L-band Synthetic Aperture Radar (PALSAR) sensor on the ALOS satellite.
ASTER (optional)Earth Observing System (EOS) Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER) data
ATSR (optional)
ENVI_OPEN_DATA_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 305
Gridded brightness temperature (GBT), gridded browse (GBROWSE), and gridded SST (GSST) data from ATSR-1 and ATSR-2
AVHRR (optional)• Level 1B data from the NOAA-K through -M satellites (KLMN)
• Standard-family HRPT Archive Request Product (SHARP) format
• Quorum format
NoteTo open an AVHRR file in the ESA_SHARP format, set the keyword ESA_SHARP instead of AVHRR.
BMP (optional)Bitmap
CADRG (optional)Defense Mapping Agency Compressed ARC Digitized Raster Graphics (CADRG) format
CIB (optional)Defense Mapping Agency Controlled Image Base (CIB) format
CORRECTED_SRTM_OUT_NAME (optional)If you are reading SRTM data (and you set the SRTM keyword), you can choose to automatically correct bad data points. Set CORRECTED_SRTM_OUT_NAME to a filename to store the corrected data points. If you do not want to automatically correct bad data points in SRTM data, do not use CORRECTED_SRTM_OUT_NAME.
COSMOSKYMED (optional)Set this keyword to read COSMO-SkyMed data in HDF5 format. ENVI supports the following COSMO-SkyMed products:
• Level-1A Single look, complex, slant range (SCS)
• Level-1B Detected Ground Multilook (DGM)
• Level-1C Geocoded Ellipsoid Corrected (GEC)
DIMAP (optional)SPOT-5 Digital Image Map
DMSP (optional)NOAA Defense Meteorological Satellite Program (DMSP) Operational Linescan System (OLS) format
DOQ (optional)USGS Digital Orthophoto Quadrangle data
DRG (optional)
ENVI Reference Guide ENVI_OPEN_DATA_FILE
306 Chapter 2: ENVI Routines
USGS Digital Raster Graphics data
ECW (optional)Enhanced Compressed Wavelet
ENVI (optional)ENVI standard file formats
ENVISAT (optional)AATSR, ASAR, or MERIS data
EOSAT_IRS (optional)Indian Remote Sensing (IRS) data in Earth Observation Satellite Company (EOSAT) Fast format
EOSAT_TM (optional)Landsat TM data in EOSAT Fast format
ERMAPPER (optional)ER Mapper
EROS_1A (optional)Earth Resources Observation System 1A data
ERS (optional)European Remote Sensing Satellite-1 or -2
ESA_SHARP (optional)European Space Agency SHARP data
ESA_TM (optional)European Space Agency CEOS Landsat TM data
ESRI_GRID (optional)Environmental Systems Research Institute (ESRI®) GRID raster format. The Fname argument must use the full path name to the GRID file when you use this keyword. You must have a licensed version of ESRI ArcGIS 8.x or later on your system to open an ESRI GRID raster file.
FORMOSAT2 (optional)FORMOSAT-2 DIMAP (.dim) data
HDF_SD (optional)HDF Scientific Data
HDFSD_DATASET (optional)
ENVI_OPEN_DATA_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 307
This keyword prevents the HDF Dataset Selection dialog from appearing if you set the keyword HDF_SD. The keyword HDFSD_DATASET allows you to select an HDF dataset without any user interaction. Set this keyword to the index of the specific HDF dataset you want to open within an HDF file. If this dataset contains three dimensions, you must specify a HDFSD_INTERLEAVE value. If the dataset has only two dimensions, then interleave is ignored.
HDFSD_INTERLEAVE (optional)Set this keyword to one of the following values if the dataset index you specified in HDFSD_DATASET has three dimensions.
• 0: BSQ (default)
• 1: BIL
• 2: BIP
IMAGINE (optional)ERDAS IMAGINE 8.x (or later) file. This keyword opens both .img and .ige IMAGINE files.
IRS_SUPER (optional)IRS Super Structured data
JERS (optional)Japanese Earth Resources Satellite
JP2 (optional)JPEG2000
JPEG (optional)JPEG
KOMPSAT2 (optional)KOMPSAT-2 Level 1G and Level 1R data
LANDSAT_METADATA (optional)Landsat MSS, TM, or ETM+ GeoTIFF files with metadata. Set the FNAME keyword to the full path of the .txt or .met metadata file, not to the GeoTIFF file.
MAS_50 (optional)MODIS/ASTER Simulator (MASTER) MAS-50 HDF data
MRLC (optional)Multi-Resolution Land Characteristic format for Landsat TM and DEM data
MODIS (optional)EOS Moderate Resolution Imaging Spectroradiometer (MODIS) data
ENVI Reference Guide ENVI_OPEN_DATA_FILE
308 Chapter 2: ENVI Routines
MRSID (optional)Multi-resolution Seamless Image Database
NITF (optional)National Imagery Transmission Format (includes data from IKONOS, QuickBird, and Orbview-3)
NLAPS (optional)National Landsat Archive Production System (NLAPS) format for Landsat TM and MSS data
PCI (optional)PCI Geomatics format (.pix)
PDS (optional)Planetary Data System format
PICT (optional)QuickDraw Picture
PNG (optional)Portable Network Graphics
QB_TILE (optional)Open a tiled QuickBird dataset as a virtual mosaic. A single file ID is returned for the virtual mosaic.
R_FID
See “Common Keywords” on page 34 for a definition of this keyword.
RADARSAT (optional)Canadian Radar Satellite data
RAPIDEYE (optional)RapidEye Level-1B and Level-3A data. You will need to select a *_metadata.xml RapidEye metadata file.
SEAWIFS (optional)SeaWiFS data in HDF or OrbImage-distributed CEOS LAC formats
SPOT (optional)SPOT Standard Digital product format (CAP)
SRF (optional)Spectral Response Function
SRTM (optional)
ENVI_OPEN_DATA_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 309
Shuttle Radar Topography Mission DEM
TIFF (optional)Tagged Image File Format (TIFF) and GeoTIFF formats
TFRD (optional)TFRD format
TIMS (optional)Thermal Infrared Multispectral Scanner data
TOPSAR (optional)Raw AIRSAR Integrated Processor Data format (Cvv, incidence angle, correlation image, or DEM)
VEGETATION (optional)SPOT vegetation data
WV_TILE (optional)Open a tiled WorldView-1 dataset as a virtual mosaic. A single file ID is returned for the virtual mosaic.
XWD (optional)X Window Dump
Example
pro example_envi_open_data_file ; ; Open a data file ; fname = ’lon_spot’ envi_open_data_file, fname, /ermapper, r_fid=fid if (fid eq -1) then return ; ; Query and print the dims and nb ; envi_file_query, fid, dims=dims, nb=nb print, dims, nbend
ENVI Reference Guide ENVI_OPEN_DATA_FILE
310 Chapter 2: ENVI Routines
ENVI_OPEN_FILE
Use this procedure to open an ENVI file. The value of R_FID will be the reference for accessing any information about this file. See “Managing Files” in the ENVI Programmer’s Guide for more information.
Syntax
ENVI_OPEN_FILE, Fname [, /NO_INTERACTIVE_QUERY] [, /NO_REALIZE] [, R_FID=variable]
Arguments
Fname
This is the name and path of the file to open.
Keywords
NO_INTERACTIVE_QUERY (optional)Set this keyword to suppress bringing up the ENVI Header Information dialog when a valid header file does not exist for Fname. If you set this keyword is set and a valid header file does not exist, the file cannot be opened and an invalid file ID is returned in the keyword R_FID.
NO_REALIZE (optional)Set this keyword to suppress opening the Available Bands List. If it is already open, this keyword has no effect.
R_FID (optional)See “Common Keywords” on page 34 for a definition of this keyword.
Example
Use ENVI_OPEN_FILE to open a file. Check that the file opened properly before using the returned file ID to perform an ENVI_FILE_QUERY.
; Input file definitionfname = '/data/img_001'envi_open_file, fname, r_fid=fid
if (fid eq -1) then returnenvi_file_query, fid, dims=dims, nb=nb
See Also
ENVI_FILE_MNGENVI_FILE_QUERYENVI_PICKFILE
ENVI_OPEN_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 311
ENVI_OSP_DOIT
Syntax | Keywords | Example | See Also
Use this procedure to run the Orthogonal Subspace Projection (OSP) target detection analysis. The OSP first designs an orthogonal subspace projector to eliminate the response of specified non-targets, then Matched Filtering (MF) is applied to match the desired target from the data. OSP is efficient and effective when target signatures are distinct. When the spectral angle between the target signature and the non-target signature is small, the attenuation of the target signal is dramatic and the performance of the OSP could be poor.
Syntax
ENVI_DOIT, 'ENVI_OSP_DOIT', FID=file ID, POS=array, DIMS=array [,M_FID=file ID] [,M_POS=value], TARGET=array [, NON_TARGET=array] [, /IN_MEMORY], OUT_NAME=string [, OUT_BNAME=string array] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
IN_MEMORY (optional)
OUT_NAME
OUT_BNAME (optional)
R_FID (optional)
TARGET
Use this keyword to specify the target spectra. It is a floating-point array. The array size is [number of input bands, number of target spectra].
NON_TARGET (optional)Use this keyword to specify the non-target spectra. It is a floating-point array. The array size is [number of input bands, number of non-target spectra]. OSP designs an orthogonal subspace projector to disallow the response of non-targets. If this keyword is not defined, you need to define at least two target spectra so that each target can use the other as non-target information.
ENVI Reference Guide ENVI_OSP_DOIT
312 Chapter 2: ENVI Routines
Example
pro example_envi_osp_doit
; First restore all the base save files. envi, /restore_base_save_files ; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt. envi_batch_init, log_file=’batch.txt’
; Open the input file envi_open_file, ’mof94av.bil’, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Set the POS keyword ; to process all spectral data. ; Output the result to disk. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’mof94av_osp’ ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for OSP. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. envi_read_cols, ’m94_em.asc’, $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = ’OSP (’ + em_names[2:*] + ’)’ ; Call the Orthogonal Subspace Projection ; processing routine. envi_doit,’envi_osp_doit’, $ fid=fid, pos=pos, dims=dims, $ target=endmem, out_name=out_name, $ out_bname=out_bname, r_fid=r_fid
; Exit ENVI envi_batch_exit end
See Also
ENVI_ACE_DOITENVI_CEM_DOITENVI_TCIMF_DOIT
ENVI_OSP_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 313
ENVI_TCIMF_MF_DOITMATCH_FILTER_DOITMATCH_FILTER_MT_DOIT
ENVI Reference Guide ENVI_OSP_DOIT
314 Chapter 2: ENVI Routines
ENVI_OUTPUT_TO_EXTERNAL_FORMAT
Use this procedure to output image data to external formats.
Syntax
ENVI_OUTPUT_TO_EXTERNAL_FORMAT [, /ARCVIEW] [, /ASCII] [, BLOCK_HEIGHT=long integer] [, BLOCK_WIDTH=long integer], DIMS=array [, /ENVI] [, /ERDAS] [, /ERMAPPER] [, /ESRI_GRID], FID=file ID [, FIELD=array] [, /IMAGINE] [, /JP2] [, /NITF] [, OUT_BNAME=string array], OUT_NAME=string [, /PCI], POS=array [, /TIFF]
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
FID
OUT_BNAME (optional)
OUT_NAME
POS
ARCVIEW (optional)Set this keyword to specify output to ArcView® format.
ASCII (optional)Set this keyword to specify output to ASCII format. If you set this keyword, you must also specify the FIELD keyword.
BLOCK_WIDTH (optional)Use this keyword to specify a long integer representing the horizontal size (in pixels) of the image block. This keyword is only valid when you set the IMAGINE keyword. Valid values are positive integers less than or equal to the image width. The default value is determined for each image, and is a block size (in pixels) optimized for writing from ENVI.
BLOCK_HEIGHT (optional)Use this keyword to specify a long integer representing the vertical size (in pixels) of the image block. This keyword is only valid when you set the IMAGINE keyword. Valid values are positive integers less than or equal to the image height. The default value is determined for each image, and is a block size (in pixels) optimized for writing from ENVI.
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing.
• DIMS[0]: Unused for this routine; set to -1L.
ENVI_OUTPUT_TO_EXTERNAL_FORMAT ENVI Reference Guide
Chapter 2: ENVI Routines 315
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
ENVI (optional)Set this keyword to specify output to ENVI format. If you set this keyword, you may optionally specify band names using the keyword OUT_BNAME.
ERDAS (optional)Set this keyword to specify output to an ERDAS .lan format.
ERMAPPER (optional)Set this keyword to specify output to ER Mapper format.
ESRI_GRID (optional)Set this keyword to specify output to ESRI® GRID raster format.
IMAGINE (optional)Set this keyword to specify output to ERDAS IMAGINE 8.x format. Any character in the OUT_NAME string that is not valid for the ERDAS filename convention is changed to an underscore character (_) when you use this keyword.
JP2 (optional)Set this keyword to specify output to JPEG2000 format.
FIELD (optional)Use this keyword to specify a two-element array of long integers representing the ASCII character field width and precision, respectively. The first element of the array specifies the number of characters in the external field, and the second element specifies the number of positions after the decimal point.
NITF (optional)Set this keyword to specify output to an NITF formatted file. To write multiple image segments, pass the FID array returned by ENVI_OPEN_DATA_FILE to ENVI_OUTPUT_TO_EXTERNAL_FORMAT. The NITF file will not be written if you pass only the FID for the composite image segment, if you pass an FID array containing FIDs from different image segments, or if you do not pass an array containing all FIDs for the file.
PCI (optional)Set this keyword to specify output to PCI Geomatics format.
ENVI Reference Guide ENVI_OUTPUT_TO_EXTERNAL_FORMAT
316 Chapter 2: ENVI Routines
TIFF (optional)Set this keyword to specify output to TIFF format.
ENVI_OUTPUT_TO_EXTERNAL_FORMAT ENVI Reference Guide
Chapter 2: ENVI Routines 317
ENVI_PC_SHARPEN_DOIT
This procedure computes principal components spectral sharpening, which sharpens a low spatial resolution multi-band image using an associated high spatial resolution panchromatic band. The algorithm assumes that the low spatial resolution spectral bands correspond to the high spatial resolution panchromatic band. These two datasets are coregistered on the fly if they are both georeferenced.
Syntax
ENVI_DOIT, 'ENVI_PC_SHARPEN_DOIT', DIMS=array, FID=file ID, HIRES_DIMS=array, HIRES_FID=file ID, HIRES_POS=array [, /IN_MEMORY] [, INTERP={0 | 1 | 2}] [, M_FID=file ID] [, M_POS=array] [, MASK_VALUE=value] [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=file ID]
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY (optional)
M_FID (optional)
M_POS (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
HIRES_DIMS
Use this keyword to specify the spatial dimensions of the high spatial resolution panchromatic band. HIRES_DIMS is a five-element array of long integers with the following definitions:
• HIRES_DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• HIRES_DIMS[1]: The starting sample number. The first x pixel is 0.
• HIRES_DIMS[2]: The ending sample number
• HIRES_DIMS[3]: The starting line number. The first y pixel is 0.
• HIRES_DIMS[4]: The ending line number
ENVI Reference Guide ENVI_PC_SHARPEN_DOIT
318 Chapter 2: ENVI Routines
HIRES_FID
Use this keyword to specify the file ID for the high spatial resolution panchromatic file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. HIRES_FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
HIRES_POS
Use this keyword to specify the band position of the high spatial resolution panchromatic band. HIRES_POS is an array of long integers, ranging from 0 to the number of bands minus 1.
INTERP (optional)Set this keyword to one of the following values to specify the resampling method.
• 0: Nearest neighbor
• 1: Bilinear interpolation
• 2: Cubic convolution
The low spatial resolution images are resampled to the high resolution space using the specified resampling method. The default method is nearest neighbor.
MASK_VALUE (optional)Use this keyword to specify the output value for the masked pixels. Only use MASK_VALUE when you specify M_FID and M_POS. The default value is 0.
See Also
ENVI_GS_SHARPEN_DOITSHARPEN_DOIT
ENVI_PC_SHARPEN_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 319
ENVI_PICKFILE
This function produces a widget that prompts you to choose a file on disk. This is different than ENVI_SELECT, which selects a file or band already open in ENVI. ENVI_PICKFILE produces the same widget as choosing File Open Image File from the ENVI main menu bar. This routine does not actually open a file; instead, it returns the fully qualified file path as a string. It is often used when you know a user will open a new file from disk, or when you do not intend to use ENVI routines to process the file (for example, when you just need to get the name of the file).
NoteAn interactive ENVI session is required to run this function.
Syntax
Result = ENVI_PICKFILE([, DEFAULT=string] [, /DIRECTORY] [, FILTER=string] [, /MULTIPLE_FILES] [, /NO_CHANGE] [, /OUTPUT] [, TITLE=string])
Keywords
DEFAULT (optional)
Figure 19-3: ENVI Filename Selection Widget
ENVI Reference Guide ENVI_PICKFILE
320 Chapter 2: ENVI Routines
Use this keyword to specify a default filename and output path. You must use the keyword OUTPUT for DEFAULT to take effect.
DIRECTORY (optional)Set this keyword to select an output directory instead of a file.
FILTER (optional)Use this keyword to specify the filename filter to apply to the file list. This keyword is ignored if you set the OUTPUT keyword.
MULTIPLE_FILES (optional)Set this keyword to select multiple files using Shift-click (to select multiple contiguous files) or Ctrl-click (to individually select multiple files) methods.
NO_CHANGE (optional)Set this keyword to inhibit changing the current ENVI output or data directory, regardless of what directory the file was selected from. Normally the directory is updated to the location of the selected file.
OUTPUT (optional)Set this keyword to use the current ENVI output directory instead of the current ENVI data directory.
TITLE
Use this keyword to specify the title of the file selection widget.
Example
Use ENVI_PICKFILE to select a filename, which by default, only lists files with a.txt extension.
name = envi_pickfile(title='Pick a text file', $filter='*.txt')
if (name eq '') then returnprint, 'The selected filename is: ', name
See Also
ENVI_OPEN_FILEENVI_SELECT
ENVI_PICKFILE ENVI Reference Guide
Chapter 2: ENVI Routines 321
ENVI_PLOT_DATA
Use this procedure to display an x,y plot in a new ENVI plot window. Depending on the dimensions of the y array, one or more plots display.
Syntax
ENVI_PLOT_DATA, X, Y [, BASE=variable] [, GROUP=value] [, PLOT_COLORS=array] [, PLOT_NAMES=string array] [, PLOT_STYLES=array] [, PLOT_TITLE=string] [, TITLE=string] [, XOFF=integer] [, XTITLE=string] [, YOFF=integer] [, YTITLE=string]
Arguments
X
This is an array of N points representing the x values to plot.
Y
This is an array with dimensions [N, number of plots] representing the y values to plot.
Keywords
BASE (optional)Use this keyword to specify a named variable that contains the returned widget base of the plot window.
GROUP (optional)Use this keyword to specify the group leader for this widget. The default is the ENVI main base, which removes the plot window when you exit ENVI.
PLOT_COLORS (optional)Use this keyword to specify the plot graphic color index. PLOT_COLORS is an array of long integers with [number of plots] elements.
PLOT_NAMES (optional)Use this keyword to specify the plot names. PLOT_NAMES is a string array with [number of plots] elements.
PLOT_STYLES (optional)Use this keyword to specify the plot styles. PLOT_STYLES is an array of long integers with the form [number of plots], specifying the style index. Set this keyword to one of the following values:
• 0: Solid
• 1: Dotted
• 2: Dashed
ENVI Reference Guide ENVI_PLOT_DATA
322 Chapter 2: ENVI Routines
• 3: Dash dot
• 4: Dash dot dot dot
• 5: Long dashes
PLOT_TITLE (optional)Use this keyword to specify the plot title. PLOT_TITLE is a string.
TITLE (optional)Use this keyword to specify the plot window title. The default is 'ENVI Plot Window'.
XOFF (optional)Use this keyword to specify the x offset (in pixels) of the upper-left corner of the plot window relative to the upper-left corner of the screen. If you do not specify XOFF, the plot window is centered horizontally on the screen.
XTITLE (optional)Use this keyword to specify the x-axis title.
YOFF (optional)Use this keyword to specify the y offset (in pixels) of the upper-left corner of the plot window relative to the upper-left corner of the screen. If you do not specify YOFF, the plot window is centered vertically on the screen.
YTITLE (optional)Use this keyword to specify the y-axis title.
Example
The example plot creates a plot window with two plots.
x = findgen(100)y = reform([x, sin(x)], 100, 2)plot_names = ['XY Line', 'SIN(X)']envi_plot_data, x, y, plot_names=plot_names
See Also
ENVI_READ_COLS
ENVI_PLOT_DATA ENVI Reference Guide
Chapter 2: ENVI Routines 323
ENVI_PROJ_CREATE
Use this function to create an ENVI projection structure for any of the supported projections. See “ENVI Map Projections” in the ENVI User’s Guide. You should use this function instead of accessing the projection structure directly.
Syntax
Result = ENVI_PROJ_CREATE([, /ARBITRARY] [, DATUM=value] [, /GEOGRAPHIC] [, /MAP_BASED] [, NAME=string] [, PARAMS=array] [, PE_COORD_SYS_CODE=integer] [, PE_COORD_SYS_STR=string] [, /SOUTH] [, /STATE_PLANE] [, TYPE=integer] [, UNITS=integer] [, /UTM] [, ZONE=integer])
Keywords
ARBITRARY (optional)Set this keyword to create an Arbitrary projection. See the keyword MAP_BASED below.
DATUM
Use this keyword to specify the datum for the map information projection. The default for a Geographic projection is WGS-84, and the default for UTM and State Plane projections is North America 1927 (NAD27). All other projections default to no datum. The exact name that ENVI uses for each datum is listed in the datum.txt file in the map_proj directory of your ENVI installation.
GEOGRAPHIC (optional)Set this keyword to create a Geographic projection.
MAP_BASED (optional)Set this keyword to interpret the Arbitrary projection as map-based. This keyword does not have any effect for other projections. The default is a non-map based projection. A map-based projection uses the lower-left corner of the image as the projection origin, while a pixel-based projection (non-map based) uses the upper-left corner as the origin.
NAME
Use this keyword to specify a name for the projection. NAME is a string variable. The actual projection type is not determined by the value of NAME. Instead, the projection type is determined by the keyword TYPE, ARBITRARY, GEOGRAPHIC, STATE_PLANE, or UTM.
PARAMS (optional)Use this keyword to specify the parameters for the map information projection. PARAMS is a array of double-precision values with 1 to 15 elements. The number of elements is determined by the projection type (see the TYPE keyword). Do not use PARAMS with Arbitrary, Geographic, State Plane, or UTM projections. See “ENVI Map Projections” in the ENVI User’s Guide for a full list of projection types and their corresponding projection parameters. The PARAMS keyword must contain all projection parameters listed in “ENVI Map
ENVI Reference Guide ENVI_PROJ_CREATE
324 Chapter 2: ENVI Routines
Projections” in the ENVI User’s Guide (for the specified projection) except the datum and name. The datum and name are specified using the DATUM and NAME keywords, respectively.
PE_COORD_SYS_CODE (optional)Use this keyword to pass in a valid geographic (GEOGCS) or projected (PROJCS) coordinate system code, typically a five-digit number. Refer to the Tech Tips on the ITT Visual Information Solutions website for predefined GEOGCS and PROJCS coordinate systems,which include the valid codes to use.
1. Go to http://www.ittvis.com/services/search.asp.
2. In the Enter Keyword field, type projection engine.
3. Click Submit.
4. In the search results, open the Tech Tip titled, “ESRI Projection Engine Reference v1.0.”
Set the TYPE keyword to 1 when passing in a GEOGCS code, or set TYPE to 42 when passing in a PROJCS code.
PE_COORD_SYS_STR (optional)Use this keyword to pass in a a geographic (GEOGCS) or projected (PROJCS) coordinate system string. See the instructions under PE_COORD_SYS_CODE to access the pertinent Tech Tip that provides predefined GEOGCS and PROJCS coordinate systems,which include the valid strings to use.
Set the TYPE keyword to 1 when passing in a GEOGCS string, or set TYPE to 42 when passing in a PROJCS string. See Example.
SOUTH (optional)Set this keyword to specify that the UTM projection is in the southern hemisphere.
STATE_PLANE (optional)Set this keyword to create a State Plane projection.
TYPE (optional)Use this keyword to specify the projection type. TYPE is an integer value corresponding to the projection type. See “ENVI Map Projections” in the ENVI User’s Guide for a full list of projection types and their corresponding projection values.
UNITS (optional)Use this optional integer keyword to specify the projection units. The function ENVI_TRANSLATE_PROJECTION_UNITS converts projection unit strings to integer values. The default units are degrees for Geographic, feet for State Plane, and meters for all other projections.
UTM (optional)Set this keyword to create a UTM projection.
ZONE (optional)
ENVI_PROJ_CREATE ENVI Reference Guide
Chapter 2: ENVI Routines 325
Use this keyword only with UTM and State Plane projections to specify the zone number.
Example
The following example creates a Geographic projection with default values for the datum (WGS-84), name (Geographic), and units (degrees). This is one of the simplest uses of ENVI_PROJ_CREATE.
proj = ENVI_PROJ_CREATE(/geographic)
The following example creates a UTM projection for Zone 23 South using the North America 1983 datum. The projection units are in kilometers.
;; First convert the kilometers to its integer representation; using ENVI_TRANSLATE_PROJECTION_UNITS and set ; the datum;units = ENVI_TRANSLATE_PROJECTION_UNITS('km')datum = 'North America 1983';; Now create the UTM projection;Proj = ENVI_PROJ_CREATE(/utm, zone=23, /south, $ datum=datum, units=units)
The following example creates a Transverse Mercator projection. Using the information in “ENVI Map Projections” in the ENVI User’s Guide, you can see that this projection (ENVI projection type “3”) requires the following parameters:
a, b, lat0, lon0, x0, y0, and k0
where
a - the equatorial radius (semi-major axis) b - the polar radius (semi-minor axis) lat0 - Latitude of origin of projection lon0 - Longitude of central meridian x0 - False easting y0 - False Northing k0 - Scale factor at central meridian
The actual values for the parameters are based on the projection being defined. In this example, the datum uses the Australian National ellipsoid, which provides the values for a and b. The latitude of origin is 0.0 degrees, and the longitude of central meridian is 99 degrees. The false northing and easting are 10000000 and 500000, respectively. The scale factor is set to 0.9996. In addition to these parameters, this projection uses the Australian Geodetic 1966 datum with the name Australian Map Grid (AGD 66) Zone 47. This example uses the default map units of meters.
;; Define the PARAMS values; Params = [6378160.0, 6356774.7, $ 0.000000, 99.000000, $ 500000., 10000000., $ .9996];
ENVI Reference Guide ENVI_PROJ_CREATE
326 Chapter 2: ENVI Routines
; Define the Datum and projection namedatum = 'Australian Geodetic 1966'name = 'Australian Map Grid (AGD 66) Zone 47';; Create the projection;proj = ENVI_PROJ_CREATE(type=3, $ name=name, datum=datum, params=params)
The following example shows how to define a string for a projected coordinate system (indicated by PROJCS), and how to create a projection structure using the PE_COORD_SYS_STR keyword:
; define the projection stringprojcsStr = 'PROJCS["SAD_1969_UTM_Zone_18N", $
GEOGCS["GCS_South_American_1969", $DATUM["D_South_American_1969", $SPHEROID["GRS_1967_Truncated",6378160.0,298.25]], $PRIMEM["Greenwich",0.0], $UNIT["Degree",0.0174532925199433]], $PROJECTION["Transverse_Mercator"], $PARAMETER["False_Easting",500000.0], $PARAMETER["False_Northing",0.0], $PARAMETER["Central_Meridian",-75.0], $PARAMETER["Scale_Factor",0.9996], $PARAMETER["Latitude_Of_Origin",0.0], $UNIT["Meter",1.0]]'
;; create the projection structureproj29118Str = ENVI_PROJ_CREATE(type = 42, pe_coord_sys_str=projcsStr)
See Also
ENVI_CONVERT_PROJECTION_COORDINATESENVI_MAP_INFO_CREATEENVI_TRANSLATE_PROJECTION_NAMEENVI_TRANSLATE_PROJECTION_UNITS
ENVI_PROJ_CREATE ENVI Reference Guide
Chapter 2: ENVI Routines 327
ENVI Reference Guide ENVI_PROJ_CREATE
328 Chapter 2: ENVI Routines
ENVI_QUAC_DOIT
This procedure automates the QUick Atmospheric Correction (QUAC) workflow for programmatic access.
Syntax
ENVI_DOIT, 'ENVI_QUAC_DOIT' [, DIMS=array], FID=file ID [, /IN_MEMORY] [, M_FID=file ID] [, M_POS=value] [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, QUAC_SENSOR=string] [, R_FID=variable]
Keywords
QUAC_SENSOR
Use this keyword to specify a string value of a particular sensor type. The predefined sensor types are shown below. If this keyword is not defined, the routine will define the input sensor as Unknown.
The string descriptors are not case-sensitive and may contain spaces. Following is a list of valid string descriptors for QUAC_SENSOR:
AISA, ASAS, AVIRIS, CAP ARCHER, COMPASS, HYCAS, HYDICE, HyMap, Hyperion, IKONOS, Landsat TM, LASH, MASTER, MODIS, MTI, QuickBird, and RGB.
See “Common Keywords” on page 34 for definitions of the following keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
M_FID (optional)
M_POS (optional)
Example
This example uses the files provided in the Data\flaash\hyperspectral\input_files directory of the ENVI Resource DVD that shipped with your software.
pro example_envi_quac_doit;; First restore all the base save files.;
ENVI_QUAC_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 329
envi, /restore_base_save_files;; Initialize ENVI in the batch mode; and send all errors and warnings; to the file batch.txt.;envi_batch_init, log_file='batch.txt';; Open the input fileenvi_open_file, 'JasperRidge98av.img', r_fid=fidif (fid eq -1) then beginenvi_batch_exitreturn
endif;; Set the keywords. We will perform the ; QUick Atmospheric Correction on all ; pixels and all bands in the file. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'JasperRidge98av_quac' ;; Perform QUick Atmospheric Correction envi_doit, 'envi_quac_doit', $ fid=fid, pos=pos, dims=dims, $ quac_sensor='AVIRIS', $ out_name=out_name, r_fid=r_fid
;; Exit ENVI envi_batch_exit;
end
ENVI Reference Guide ENVI_QUAC_DOIT
330 Chapter 2: ENVI Routines
ENVI_QUERY_VERSION
This function returns a string containing the current version number of ENVI.
Syntax
Result = ENVI_QUERY_VERSION()
Examples
Following is an example for ENVI:
version = ENVI_QUERY_VERSION()HELP, version
ENVI printed:
VERSION STRING 'x.x'
Where x.x is the software version.
ENVI_QUERY_VERSION ENVI Reference Guide
Chapter 2: ENVI Routines 331
ENVI_RADARSAT_GEOREF_DOIT
Use this procedure to extract embedded geolocation points from a processed RADARSAT file. The points are then used to georeference the RADARSAT data to a specific map projection.
NoteNot all RADARSAT files contain embedded geolocation points. If the RADARSAT input data does not have geolocation points, ENVI_RADARSAT_GEOREF_DOIT cannot georegister the file.
Syntax
ENVI_DOIT, 'ENVI_RADARSAT_GEOREF_DOIT' [, BACKGROUND=value] [, DEGREE=value] [, DIMS=array], FID=file ID [, GCP_NAME=string], /IN_MEMORY [, METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}], OUT_FNAME=string [, PIXEL_SIZE=array] [, PROJ=structure] [, R_FID=variable] [, SKIP_LINES=value]
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
DIMS (optional)
FID
IN_MEMORY
R_FID (optional)
BACKGROUND (optional)Use this keyword to specify the value for all background pixels. The default is 0.
DEGREE (optional)Use this keyword to specify the degree of the polynomial warp when METHOD=3, 4, or 5. The default is DEGREE=1.
GCP_NAME (optional)Use this keyword to specify the name of the output file to contain the extracted geolocation points. If you do not set this keyword, the points are not saved to disk.
METHOD (optional)Set this keyword to one of the following values to specify the warping method to use.
• 0: RST with nearest neighbor
• 1: RST with bilinear
• 2: RST with cubic convolution
• 3: Polynomial with nearest neighbor (default)
ENVI Reference Guide ENVI_RADARSAT_GEOREF_DOIT
332 Chapter 2: ENVI Routines
• 4: Polynomial with bilinear
• 5: Polynomial with cubic convolution
• 6: Triangulation with nearest neighbor
• 7: Triangulation with bilinear
• 8: Triangulation with cubic convolution
OUT_FNAME (optional)Use this keyword to specify an output filename for the resulting data. If you do not set OUT_FNAME, the default output is to memory. If you set the keyword IN_MEMORY, you do not need this keyword.
PIXEL_SIZE (optional)Use this keyword to specify a two-element array for the output pixel size [x, y]. If you do not specify a value for PIXEL_SIZE, the default is [12.5, 12.5] in meters.
PROJ (optional)Use this keyword to specify the projection of the resulting data. You cannot set PROJ to the Arbitrary projection. PROJ is a projection structure returned from ENVI_PROJ_CREATE or ENVI_GET_PROJECTION. The default projection is UTM.
SKIP_LINES (optional)Use this keyword to specify the number of lines to skip when extracting the GCPs. The default value is 100.
Example
The following code shows an example of using the programmatic interface.
fname = 'C:\my_radarsat_data'
ENVI_OPEN_DATA_FILE, fname, R_FID = fileID, /RADARSAT
projection = ENVI_PROJ_CREATE(/UTM, ZONE = 13)pixelSize = [10, 10] gcpFile = 'C:\temp\DAT_01.pts'outputFilename = 'C:\temp\radarsat'background = 100ENVI_DOIT, 'ENVI_RADARSAT_GEOREF_DOIT', FID = fileID,$
PROJ = projection, PIXEL_SIZE = pixelSize, METHOD = 3, $DEGREE = 1, SKIP_LINES = 100, GCP_NAME = gcpFile, $OUT_FNAME = outputFilename
ENVI_RADARSAT_GEOREF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 333
ENVI_READ_COLS
Use this procedure to read ASCII column data.
Syntax
ENVI_READ_COLS, Name, Values [, ERROR=variable] [, HEAD=string array] [, /READ_HEAD] [, /READ_SKIP] [, SKIP=string array]
Arguments
Name
This is the filename to read from.
Values
This is a named variable containing the values to read from Name.
Keywords
ERROR (optional)Use this keyword to specify a named variable that holds the value of the error flag. If this variable is set to a value of 1, there was a read error. A value of 0 indicates no error.
HEAD (optional)Use this keyword to specify a string array that contains the first five rows of data from the file being read.
READ_HEAD (optional)Set this keyword to read the column header and store the result in the string array specified by the keyword HEAD.
READ_SKIP (optional)Set this keyword to save all skipped lines in the array specified by the SKIP keyword. Lines are only skipped when they cannot be decoded into the proper values.
SKIP (optional)Use this keyword to specify a string array that contains skipped lines. You must use this keyword if you set READ_SKIP.
Example
The following example is similar to that of ENVI_REGISTER_DOIT, but it uses ENVI_READ_COLS to read an ASCII file of ground control points (GCPs) instead of explicitly defining the GCPs in the code. The example performs image-to-map registration using GCPs on a Boulder, Colorado, Landsat scene. The files bldr_tm.img and bldrtm_m.pts are available in the Bldr_reg directory of the ENVI Resource DVD that
ENVI Reference Guide ENVI_READ_COLS
334 Chapter 2: ENVI Routines
shipped with your ENVI software. Be sure to put them in the same directory as the following program for it to work properly.
pro example_envi_read_cols ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file=’batch.txt’ ; ; Open the input file ; input_file = ’bldr_tm.img’ envi_open_file, input_file, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the DIMS and POS to keywords ; to processes all spatial and all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’testimg’ ; ; Read the points file with the map ; coordinates for known pixel locations and ; create projection for the map coordinates. ; Set the output pixel size to 30 meters. ; pts_file=’bldrtm_m.pts’ envi_read_cols, pts_file, pts ; ; Create the projection of the map coordinates ; units = envi_translate_projection_units(’Meters’) proj = envi_proj_create(/utm, zone=13, $ datum=’North America 1927’, units=units) pixel_size = [30., 30.] ; ; Perform the image-to-map registration. envi_doit, ’envi_register_doit’, $ w_fid=fid, w_pos=pos, w_dims=dims, $ method=2, out_name=out_name, $ pts=pts, pixel_size=pixel_size, $ proj=proj, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI_READ_COLS ENVI Reference Guide
Chapter 2: ENVI Routines 335
ENVI_REGISTER_DOIT
Use this procedure to warp (georeference) image data, such as image-to-image or image-to-map registration. Use the keyword PTS to specify the base points and the corresponding input image warp points. The goal is to warp the image so that the warp points align with the base points. If the base and warp points are in pixel coordinates, image-to-image registration is performed, and you must specify both a base and warp file ID. If the base points are in map coordinates and the warp points are in pixel coordinates, then image-to-map registration is performed and you only specify the warp file ID. See “Registration” in the ENVI User’s Guide for more information.
Syntax
ENVI_DOIT, 'ENVI_REGISTER_DOIT' [, B_FID=file ID] [, BACKGROUND=integer] [, DEGREE=value] [, /IN_MEMORY] [, METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}] [, OUT_BNAME=string array] [, OUT_NAME=string] [, PIXEL_SIZE=array] [, PROJ=structure], PTS=array [, R_FID=variable], W_DIMS=array, W_FID=file ID, W_POS=array [, X0=value] [, XSIZE=value] [, Y0=value] [, YSIZE=value] [, /ZERO_EDGE]
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME (optional)
R_FID (optional)
B_FID (optional)Use this keyword to specify the file ID for the base file. B_FID is only specified when performing image-to-image warping (georeferencing). The goal is to warp the warp image (W_FID) so it aligns with the base image (B_FID). This is the value returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
BACKGROUND (optional)Use this keyword to specify the value for all background pixels. The default is 0.
DEGREE (optional)Use this keyword to specify the degree of the warping polynomial for the polynomial method. The degree of the polynomial is limited by the number of GCPs, and you must be sure that #GCPs >= (degree + 1)2. DEGREE has no effect for RST and triangulation methods. The default is DEGREE=1.
METHOD (optional)
ENVI Reference Guide ENVI_REGISTER_DOIT
336 Chapter 2: ENVI Routines
Set this keyword to one of the following values to specify the warping method to use.
• 0: RST with nearest neighbor
• 1: RST with bilinear
• 2: RST with cubic convolution
• 3: Polynomial with nearest neighbor (default)
• 4: Polynomial with bilinear
• 5: Polynomial with cubic convolution
• 6: Triangulation with nearest neighbor
• 7: Triangulation with bilinear
• 8: Triangulation with cubic convolution
PIXEL_SIZE (optional)Use this keyword only when performing image-to-map warping. Set this keyword to an array of double-precision values containing the x and y pixel sizes of the output image. You should specify the pixel sizes in the units contained in the projection structure passed to the PROJ keyword. The default is PIXEL_SIZE = [1.0d, 1.0d].
PROJ (optional)Use this keyword to specify the projection of the x and y map coordinates listed in the PTS array when performing image-to-map registration. You must set PROJ when performing image-to-map registration. PROJ is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE.
PTS
Use this keyword to specify an array of double-precision values representing the x and y positions of the base and warp tie points. The dimensions of the array are [4, #points], where the base and warp points for image-to-image are defined as follows.
• PTS[0, #points]: x base points
• PTS[1, #points]: y base points
• PTS[2, #points]: x warp points
• PTS[3, #points]: y warp points
Image-to-map warp points are defined as follows:
• PTS[0, #points]: x map points
• PTS[1, #points]: y map points
• PTS[2, #points]: x image points
• PTS[3, #points]: y image points
NoteThis procedure converts any variable used for PTS to double-precision. It also converts x and y base points to x and y map points.
ENVI_REGISTER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 337
W_DIMS Use this keyword to specify the spatial dimensions of the warp image (W_FID) on which to perform the operation. W_DIMS is a five-element array of long integers with the following definitions:
• W_DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• W_DIMS[1]: The starting sample number. The first x pixel is 0.
• W_DIMS[2]: The ending sample number
• W_DIMS[3]: The starting line number. The first y pixel is 0.
• W_DIMS[4]: The ending line number
W_FID Use this keyword to specify the file ID for the warp file. This is the file ID of the image that is warped to the base points. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
W_POS Use this keyword to specify an array of band positions for the warp image indicating the band numbers on which to perform the operation. W_POS is an array of long integers, ranging from 0 to the number of bands minus 1.
X0 (optional)Use this keyword to specify the x location (in pixel coordinates for image-to-image or map coordinates for image-to-map) of the upper-left pixel of the output image.
XSIZE (optional)Use this keyword to specify the output image x size. This value is in pixels for image-to-image or output map units for image-to-map.
Y0 (optional)Use this keyword to specify the y location (in pixel coordinates for image-to-image or map coordinates for image-to-map) of the upper-left pixel of the output image.
YSIZE (optional)Use this keyword to specify the output image y size. This value is in pixels for image-to-image or output map units for image-to-map.
ZERO_EDGE (optional)Set this keyword to set the edges outside of any triangles to the value specified by BACKGROUND. Use this keyword only when METHOD=6, 7, or 8.
Example
forward_function envi_translate_projection_units, $ envi_proj_create
ENVI Reference Guide ENVI_REGISTER_DOIT
338 Chapter 2: ENVI Routines
pro example_envi_register_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the DIMS and POS to keywords ; to processes all spatial and all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Setup the points file with the map ; coordinates for know pixel locations and ; create projection for the map coordinates. ; Set the output pixel size to 30 meters. ; pts = [[474367.50, 4264987.50, 0.0, 0.0], $ [491895.00, 4261155.00, dims[2], 0.0], $ [489720.00, 4250587.50, dims[2], dims[4]], $ [471847.50, 4254292.50, 0.0, dims[4]]] ; ; Create the projection of the map coordinates ; units = envi_translate_projection_units('Meters') proj = envi_proj_create(/utm, zone=13, $ datum='North America 1927', units=units) pixel_size = [30., 30.] ; ; Perform the image-to-map registration. envi_doit, 'envi_register_doit', $ w_fid=fid, w_pos=pos, w_dims=dims, $ method=2, out_name=out_name, $ pts=pts, pixel_size=pixel_size, $ proj=proj, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI_REGISTER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 339
See Also
ENVI_CONVERT_FILE_COORDINATESENVI_CONVERT_FILE_MAP_PROJECTIONENVI_CONVERT_PROJECTION_COORDINATES
ENVI Reference Guide ENVI_REGISTER_DOIT
340 Chapter 2: ENVI Routines
ENVI_REPORT_ERROR
The ENVI_REPORT_ERROR procedure reports error message strings through the standard ENVI error reporting mechanism. The default title of the displayed dialog provided by this procedure is ENVI Error. The default button on the displayed dialog is OK.
Syntax
ENVI_REPORT_ERROR, Err_string [, /CANCEL] [, /MESSAGE] [, /QUESTION] [, VALUE=variable] [, /WARNING]
Arguments
Err_string
Specify a string containing the text that follows the title and precedes any buttons within the dialog provided by this procedure.
Keywords
CANCEL (optional)Use this keyword to display a Cancel button after the OK or Yes button within the dialog. If the Cancel button is pressed, the VALUE keyword returns a value of -1.
MESSAGE (optional)Use this keyword to change the title of the dialog to ENVI Message.
QUESTION (optional)Use this keyword to change the title of the dialog to ENVI Question and the OK button to Yes and No buttons. If Yes is pressed, the VALUE keyword returns a value of -1. If No is pressed, the VALUE keyword returns a value of -1.
VALUE (optional)Use this keyword to specify a named variable that contains the value of any button pressed within the dialog.
WARNING (optional)Use this keyword to change the title of the dialog to ENVI Warning.
ENVI_REPORT_ERROR ENVI Reference Guide
Chapter 2: ENVI Routines 341
ENVI_REPORT_INC
Use this procedure to set the increment used for tiled processing. This value appears in ENVI status windows in the field labeled Inc:
Syntax
ENVI_REPORT_INC, Base, Num_tiles
Arguments
Base
This is the base ID of the status window widget.
Num_tiles
This is the total number of processing cycles. This is typically equal to the number of tiles.
Example
ENVI_REPORT_INC should be called before the actual processing loop begins:
envi_report_inc, base, num_tilesfor i=0,num_tiles-1 do beginenvi_report_stat,base, i, num_tiles
.
.algorithm here..
endfor
See Also
ENVI_REPORT_STATENVI_REPORT_INIT
ENVI Reference Guide ENVI_REPORT_INC
342 Chapter 2: ENVI Routines
ENVI_REPORT_INIT
This procedure displays an ENVI status reporting box that shows the percent of the function completed and the increment in use. It also provides a Cancel button for the function. This function is called to initialize the status window and again after the processing is finished.
Syntax
ENVI_REPORT_INIT, Rstr, BASE=variable, /FINISH, /INTERRUPT, TITLE=string
Arguments
Rstr
This is an array of strings to display in the status window. Each element in the array is displayed on a new line.
Keywords
BASE
Use this keyword to specify a named variable that contains the widget base used to display the status window. You must specify the base value returned from initialization to ENVI_REPORT_INIT when removing the status window.
FINISH
Set this keyword to remove the status window after processing has finished. Note that you must set the BASE keyword equal to the same base value you specified when the window was created.
INTERRUPT
Set this keyword to allow processing interrupts using the Cancel button.
TITLE
Set this keyword equal to the string to display in the status window’s title bar.
Figure 21-4: Processing Status Dialog
ENVI_REPORT_INIT ENVI Reference Guide
Chapter 2: ENVI Routines 343
Example
The following commands create a window like the one shown above.
if(in_memory) then ostr = 'Output to Memory' $else ostr = 'Output File: ' + out_fnamerstr = ["Input File :" + fname, ostr]envi_report_init, rstr, title="USGS Munsell", base=base
This function also must be called at the end of processing to remove the report widget:
envi_report_init, base=base, /finish
See Also
ENVI_REPORT_STATENVI_REPORT_INC
ENVI Reference Guide ENVI_REPORT_INIT
344 Chapter 2: ENVI Routines
ENVI_REPORT_STAT
This procedure updates the percent of tile processing completed. Each time this procedure is called, the widget is updated based on the values of the arguments Num and Den.
Syntax
ENVI_REPORT_STAT, Base, Num, Den, CANCEL=variable
Arguments
Base
This is the base ID of the status window widget to be updated. This value is returned from ENVI_REPORT_INIT at initialization.
Num
This is a variable that serves as a counter for the number of tiles processed. The percent completed is determined by the ratio of Num over Den.
Den
This is the total number of tiles to be processed. The percent completed is determined by the ratio of Num over Den.
Keywords
CANCEL
Use this keyword to specify a named variable that returns the status of the Cancel button. A returned value of 1 indicates the Cancel button was pressed. A value of 0 is returned otherwise. This keyword only has meaning if you specify a value for INTERRUPT in ENVI_REPORT_INIT.
Example
This example shows how to update the percentage completed for an ENVI status report window created with ENVI_REPORT_INIT.
for i=0, num_tiles-1 do beginenvi_report_stat, base, i, num_tiles.the user function and tiling is done here.
endfor
Notes
The parameters Num and Den are used to form the ratio (Num/Den)*100 to calculate the percent completed. In the example above, the percent complete is calculated as (i/num_tiles)*100.
ENVI_REPORT_STAT ENVI Reference Guide
Chapter 2: ENVI Routines 345
See Also
ENVI_REPORT_INITENVI_REPORT_INC
ENVI Reference Guide ENVI_REPORT_STAT
346 Chapter 2: ENVI Routines
ENVI_RESAMPLE_SPECTRA
This procedure spectrally resamples individual spectra.
Syntax
ENVI_RESAMPLE_SPECTRA, I_WL, I_Spec, O_WL, O_Spec [, BAD_VALUE=value] [, INTERLEAVE={0 | 1 | 2}] , OUT_DT=integer [, OUT_FWHM=array]
Arguments
I_WL
This is a vector of input wavelengths corresponding to the input spectra (I_Spec).
I_Spec
This is a vector of input spectra to be resampled.
O_WL
This is a vector containing the output wavelengths to resample to. This argument must have the same units as I_WL.
O_Spec
This is a vector containing the resampled output spectra.
Keywords
BAD_VALUE (optional)Use this keyword to specify a value for spectra that fall outside the input wavelength range. In this case, no extrapolation will be performed. All spectra values equal to BAD_VALUE are considered bad values. BAD_VALUE is a single number.
INTERLEAVE (optional)Set this keyword to one of the following values to specify an interleave type:
• 0: BSQ
• 1: BIL
• 2: BIP
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
ENVI_RESAMPLE_SPECTRA ENVI Reference Guide
Chapter 2: ENVI Routines 347
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
OUT_FWHM (optional)Use this keyword to specify an array of floating-point values representing full-width-half-maximum responses for each output band. The number of elements in this array is equal to the number of output bands.
ENVI Reference Guide ENVI_RESAMPLE_SPECTRA
348 Chapter 2: ENVI Routines
ENVI_RESTORE_ROIS
This procedure is used to restore a previously saved ROI file.
Syntax
ENVI_RESTORE_ROIS, Fname
Arguments
Fname
This is the filename of the saved ROI file.
Example
Restore the ROI file wetlands.roi, saved in the directory d:\data\tm.
envi_restore_rois, 'd:\data\tm\wetlands.roi'
See Also
ENVI_GET_ROIENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_IDSENVI_SAVE_ROIS
ENVI_RESTORE_ROIS ENVI Reference Guide
Chapter 2: ENVI Routines 349
ENVI_ROI_TO_IMAGE_DOIT
Use this procedure to create a classification image from ROIs. Each input ROI represents a class in the output image.
Syntax
ENVI_DOIT, 'ENVI_ROI_TO_IMAGE_DOIT', CLASS_VALUES=array, FID=file ID, [, /IN_MEMORY], OUT_NAME=string [, R_FID=variable], ROI_IDS=value
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
IN_MEMORY (optional)
OUT_NAME
R_FID (optional)
CLASS_VALUES
Set this keyword to specify the values for the output classes. CLASS_VALUES is an array of long integers specifying the class value for the corresponding ROI_IDS. A value of 0 is reserved for the “Unclassified” class.
FID
Use this keyword to specify the file ID associated with the ROIs. FID is used to get the number of samples and number of lines for the output file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
ROI_IDS
Use this keyword to specify the ROI ID to turn into classes. Each ROI takes the class values specified by CLASS_VALUES. A value of 0 is reserved for the “Unclassified” class. ROI_ID is an array of ROI IDS returned from the function ENVI_GET_ROI_IDS.
Example
forward_function envi_get_roi_ids
pro example_envi_roi_to_image_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt'
ENVI Reference Guide ENVI_ROI_TO_IMAGE_DOIT
350 Chapter 2: ENVI Routines
; ; Open the input file associated with ; the ROIs ; envi_open_file, 'bhtm_mnf.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Restore the ROI file and get all ; the available ROI ids. ; envi_restore_rois, 'bhtm_nd.roi' roi_ids = envi_get_roi_ids() if (roi_ids[0] eq -1) then return ; ; Set the necessary variables ; out_name = 'testimg' class_values = lindgen(n_elements(roi_ids))+1 ; ; Call the doit ; envi_doit, 'envi_roi_to_image_doit', $ fid=fid, roi_ids=roi_ids, out_name=out_name, $ class_values=class_values ; ; Exit ENVI ; envi_batch_exitend
ENVI_ROI_TO_IMAGE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 351
ENVI_RXD_DOIT
Use this procedure to perform Reed-Xiaoli anomaly detection on a multispectral or hyperspectral image. Reed-Xiaoli Detector (RXD) is an unsupervised anomaly detection algorithm that detects the spectral or color differences between a region to be tested and its neighboring pixels or the entire dataset. Bright pixels in the output image represent targets that are spectrally distinct from the image background.
Syntax
ENVI_DOIT, 'ENVI_RXD_DOIT' [, DIMS=array], FID=file ID [, /IN_MEMORY] [, /LOCAL] [, M_FID=variable] [, M_POS=array] [, METHOD={0 | 1 | 2}] [, OUT_NAME=string] [, POS=array] [, KERNEL_SIZE=integer] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following eight keywords.
DIMS (optional)
FID
IN_MEMORY (optional)
M_FID (optional)
M_POS (optional)
OUT_NAME (optional)
POS (optional)
R_FID (optional)
LOCAL (optional)Set this keyword to use a local mean spectrum rather than a global mean spectrum (based on the entire dataset). If you set this keyword, you must specify the local kernel size using the KERNEL_SIZE keyword.
METHOD (optional)Use this keyword to specify the specific anomaly detection algorithm to use. Set METHOD to one of the following values:
• 0: RXD (default): Standard RXD algorithm
• 1: UTD: Uniform Target Detector algorithm
• 2: RXD-UTD: A hybrid of the RXD and UTD algorithms
See “RX Anomaly Detection” in ENVI Help for the differences among these algorithms.
KERNEL_SIZE (optional)
ENVI Reference Guide ENVI_RXD_DOIT
352 Chapter 2: ENVI Routines
Use this keyword to specify a square kernel size, in pixels, around a given pixel that will be used to create a mean spectrum. If you do not set the LOCAL keyword, this keyword is ignored. The minimum value is 1, and the maximum value is (ns - 1) < (nl - 1).
Example
envi_doit, 'envi_rxd_doit', fid=fid, dims=dims, pos=pos, $m_fid=m_fid, m_pos=m_pos, /local, method=0, $kernel_size=15, out_name='out_rxd', r_fid=r_fid
ENVI_RXD_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 353
ENVI_SAVE_ROIS
Use this procedure to save ROIs from within ENVI. The program accepts the output ROI filename and a list of ROIs to save.
Syntax
ENVI_SAVE_ROIS, Filename, ROI_ID
Arguments
Filename
This is the output filename for the saved ROIs.
ROI_ID
This argument contains the ROI IDs to save to Filename. This value is returned from ENVI_GET_ROI_IDS or ENVI_CREATE_ROI.
Example
roi_ids = envi_get_roi_ids()envi_save_rois, 'test.roi', roi_ids
See Also
ENVI_CREATE_ROIENVI_DEFINE_ROIENVI_GET_ROIENVI_GET_ROI_DATAENVI_GET_ROI_DIMS_PTRENVI_GET_ROI_IDSENVI_GET_ROI_INFORMATIONENVI_RESTORE_ROIS
ENVI Reference Guide ENVI_SAVE_ROIS
354 Chapter 2: ENVI Routines
ENVI_SEAWIFS_GEOMETRY_DOIT
Use this procedure to calculate the geometry for HDF- and CEOS-format SeaWiFS data. This procedure extracts header information and calculates the following geometry values for each pixel.
• Latitude and longitude
• Sensor and solar positions
• Azimuth angle: The direction from each pixel to the sensor or sun. North equals 0 degrees, and the angles increase in a clockwise direction (for example, east equals 90).
• Zenith angle: The direction measured vertically from each pixel to the sensor or sun. Straight above the pixel equals 0 degrees.
• Universal Coordinated Time (UTC)
ENVI uses the same solar geometry calculations as the NOAA Earth System Research Laboratory (see http://www.srrb.noaa.gov/), except that it uses lookup tables to obtain equations for time, declination, and Julian day.
Syntax
ENVI_DOIT, 'ENVI_SEAWIFS_GEOMETRY_DOIT' [, CEOS=string] [, COMP_FLAG=integer], DIMS=array, FID=file ID, /IN_MEMORY, [, OUT_BNAME=string array], OUT_NAME=string [, OUT_DT={4 | 5}] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME (optional)
OUT_NAME
R_FID (optional)
CEOS (optional)Use this keyword to specify the name of the CEOS annotation file containing the geospatial parameters. If you do not set this keyword, the file is assumed to be in HDF format.
COMP_FLAG (optional)Set this keyword to one of the following values to indicate what geometry values are calculated.
ENVI_SEAWIFS_GEOMETRY_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 355
• 1: Latitude
• 2: Longitude
• 4: Sensor azimuth
• 16: Solar azimuth
• 32: Solar zenith
• 64: UTC time
Set this keyword bitwise to allow multiple results by adding integer values. For example, to only calculate longitude (COMP_FLAG=2) and UTC time (COMP_FLAG=64), set COMP_FLAG to a value of 66.
If you do not set this keyword, all the geometry values are calculated by default.
OUT_DT (optional)This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
NoteYou may lose precision if you specify any data type other than floating-point or double-precision floating-point.
The default data type is floating-point.
See Also
ENVI_SEAWIFS_GEOREF_DOIT
ENVI Reference Guide ENVI_SEAWIFS_GEOMETRY_DOIT
356 Chapter 2: ENVI Routines
ENVI_SEAWIFS_GEOREF_DOIT
The ENVI_SEAWIFS_GEOREF_DOIT procedure georeferences HDF- and CEOS-format SeaWiFS data. This procedure extracts header information to perform a precision geocoding of SeaWiFS data based on a complete geometry model of the earth and satellite orbit.
Syntax
ENVI_DOIT, 'ENVI_SEAWIFS_GEOREF_DOIT' [, BACKGROUND=value] [, CEOS=string] [, DEGREE=value], DIMS=array, FID=file ID [, GCP_NAME=string] [, GCP_PTS=variable], /IN_MEMORY [, OUT_BNAME=string array], OUT_NAME=string, OUT_PROJ=structure, POS=array [, /PTS_ONLY] [, R_FID=variable] [, WARP_X=integer] [, WARP_Y=integer], WARP_METHOD={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8} [, ZERO_EDGE=0]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
BACKGROUND (optional)Use this keyword to specify the value for all background pixels. The default is 0.
CEOS (optional)Use this keyword to specify the name of the CEOS annotation file containing the geospatial parameters.
NoteIf you do not set this keyword, the file is assumed to be in HDF format.
DEGREE (optional)Use this keyword to specify the degree of the polynomial warp when METHOD=3, 4, or 5. The default is DEGREE=1.
GCP_NAME (optional)
ENVI_SEAWIFS_GEOREF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 357
Use this keyword to specify the name of the output file that contains the GCPs. If you do not set this keyword, the points are not saved to disk.
GCP_PTS (optional)Use this keyword to specify a named variable that contains the GCPs.
OUT_PROJ
Use this keyword to specify the projection of the resulting data. You cannot set OUT_PROJ to the Arbitrary projection. OUT_PROJ is a projection structure returned from ENVI_PROJ_CREATE or ENVI_GET_PROJECTION.
PTS_ONLY (optional)Set this keyword to compute only the GCPs. If you set this keyword, the input image is not warped.
WARP_X (optional)Use this keyword to specify the number of x warp points to use for the georeferencing process. The default value is 50.
WARP_Y (optional)Use this keyword to specify the number of y warp points to use for the georeferencing process. The default value is 50.
WARP_METHOD
Use this keyword to specify an integer value indicating a combination of methods used to warp and resample the image.
• 0: RST with nearest neighbor (default)
• 1: RST with bilinear
• 2: RST with cubic convolution
• 3: Polynomial with nearest neighbor
• 4: Polynomial with bilinear
• 5: Polynomial with cubic convolution
• 6: Triangulation with nearest neighbor
• 7: Triangulation with bilinear
• 8: Triangulation with cubic convolution
ZERO_EDGE (optional)Set this keyword to set the edges outside of any triangles for the triangulation method to the value specified by the BACKGROUND keyword. Use the ZERO_EDGE keyword only when WARP_METHOD=6, 7, or 8.
ENVI Reference Guide ENVI_SEAWIFS_GEOREF_DOIT
358 Chapter 2: ENVI Routines
NoteThe ZERO_EDGE keyword is set by default. To disable this default behavior, explicitly set the ZERO_EDGE keyword to 0.
Examples
The following sample lines of code show how to call this procedure to georeference an HDF-format SeaWiFS file named S1998036093739.L1A_HORB:
name = "S1998036093739.L1A_HORB"ENVI_OPEN_FILE, name, R_FID = fid, /NO_REALIZE
out_name = 'seawifs_warp.img'out_proj = ENVI_PROJ_CREATE(/GEOGRAPHIC)warp_method = 6
dims = [-1, 0, 500, 0, 500]pos = [0, 1, 2, 3]warp_x = 50warp_y = 50
ENVI_SEAWIFS_GEOREF_DOIT, FID = fid, OUT_NAME = out_name, $OUT_PROJ = out_proj, DIMS = dims, POS = pos, WARP_X = warp_x, $WARP_Y = warp_y, WARP_METHOD = warp_method, BACKGROUND = 0, $/ZERO_EDGE, R_FID = r_fid
out_name = 'c:\temp\test_geom.img'comp_flag = 42ENVI_SEAWIFS_GEOMETRY_DOIT, FID = fid, DIMS = dims, $
OUT_DT = out_dt, OUT_NAME = out_name, OUT_BNAME = out_bname, $COMP_FLAG = comp_flag
See Also
ENVI_SEAWIFS_GEOMETRY_DOIT
ENVI_SEAWIFS_GEOREF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 359
ENVI_SEGMENT_DOIT
Use this procedure to segment a classification image into unique spatially contiguous “blobs.” You can create blobs with a minimum population and either four or eight neighbors.
Syntax
ENVI_DOIT, 'ENVI_SEGMENT_DOIT', ALL_NEIGHBORS={0 | 1}, CLASS_PTR=array, DIMS=array, FID=file ID [, /IN_MEMORY] [, MIN_POPULATION=integer] [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
ALL_NEIGHBORS
Use this keyword to specify the connectivity for segmentation blobs. If you set this keyword to 1, all eight surrounding neighbors are used to connect elements of a blob. Otherwise, set it to 0 to specify that only four (up, down, left, right) pixels form connections.
CLASS_PTR
Use this keyword to specify the classes to segment. CLASS_PTR is an array of long integers representing class numbers ranging from 0 (“Unclassified”) to the number of classes.
MIN_POPULATION (optional)Use this keyword to specify the minimum number of pixels that form a segmentation blob. The default value for MIN_POPULATION is 0.
Example
pro example_envi_segment_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ;
ENVI Reference Guide ENVI_SEGMENT_DOIT
360 Chapter 2: ENVI Routines
; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtm_sam.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform ; the segmentation on all the entire ; spatial image but segment only ; the first class (the Unclassified ; class is the zero class). There must ; at least 50 pixels in a segment ; are connected with any of the ; eight neighbors. ; envi_file_query, fid, dims=dims pos = [0] out_name = 'testimg' min_population = 50 class_ptr = [1] ; ; Perform the segmentation. ; envi_doit, 'envi_segment_doit', $ fid=fid, pos=pos, dims=dims, $ min_population=min_population, $ class_ptr=class_ptr, $ /all_neighbors, out_name=out_name ; ; Exit ENVI ; envi_batch_exitend
See Also
CLASS_CS_DOITCLASS_MAJORITY_DOIT
ENVI_SEGMENT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 361
ENVI_SELECT
This routine produces a widget that prompts you to select a file from those that have already been opened. ENVI_SELECT produces ENVI’s Input Selection Dialog by File/Band, including buttons for spatial and spectral subsetting and for choosing a mask band. This routine also incorporates the functionality of ENVI_PICKFILE because the widget includes a button to open ENVI-format files from disk. ENVI_SELECT not only returns an FID for the selected file, but also the DIMS and POS variables that will likely be required for further processing.
Figure 22-5: Input Selection by File Dialog
ENVI Reference Guide ENVI_SELECT
362 Chapter 2: ENVI Routines
Syntax
ENVI_SELECT [, /BAND_ONLY] [, DIMS=variable] [, FID=variable] [, /FILE_ONLY] [, FILE_TYPE=integer] [, /MASK] [, M_FID=variable] [, M_POS=variable] [, /NO_DIMS] [, /NO_SPEC] [, POS=variable] [, /ROI] [, TITLE=string]
Keywords
BAND_ONLY (optional)Set this keyword to disable selection of files using the Input File toggle button and to only allow band selection.
DIMS (optional)Use this optional keyword to specify a named variable that contains the spatial dimensions of the file.
FID (optional)Use this keyword to specify a named variable that will contain the file ID of the selected file when the OK button is selected. If FID[0] = -1, the Cancel button was selected and the user should take the appropriate action.
FILE_ONLY (optional)
Figure 22-6: Input Selection by Band Dialog
ENVI_SELECT ENVI Reference Guide
Chapter 2: ENVI Routines 363
Set this keyword to disable selection of single bands using the Input band toggle button and only allow file selection.
FILE_TYPE (optional)Set this keyword to an integer value specifying the allowable file type. Only files with matching types are considered valid. See ENVI_FILE_TYPE for details on how to determine the integer value of a file type.
MASK (optional)Set this keyword to allow selection of a mask.
M_FID (optional)Use this keyword to specify a named variable that will contain the file ID of the selected mask file. To enable mask selection, you must set the MASK keyword.
M_POS (optional)Use this keyword to specify a named variable that will contain the band position of the selected mask. To enable mask selection, you must set the MASK keyword.
NO_DIMS (optional)Set this keyword to disable spatial subsetting.
NO_SPEC (optional)Set this keyword to disable spectral subsetting.
POS (optional)Use this keyword to specify a named variable that will contain an array holding the bands selected.
ROI (optional)Set this keyword to allow ROI subsetting. The array element DIMS[0] contains the ROI pointer.
TITLE (optional)Use this keyword to specify the string used in the title bar of the File Selection dialog window.
Example
This example shows how to select a file or band and return the FID, DIMS, and POS information. This is typically the simplest use of ENVI _SELECT. Also, if you click the Cancel button (FID[0] = -1), then return from the current user procedure as shown below.
ENVI_SELECT, fid=fid,dims=dims,pos=posif (fid[0] eq -1) then return
The following example allows you to select a single classification band with no spatial subset. The FILE_TYPE keyword set to “Classification” only allows you to select a classification band and issues a warning on attempts to select non-classification data. You can use the
ENVI Reference Guide ENVI_SELECT
364 Chapter 2: ENVI Routines
keyword FILE_TYPE keyword with any file type, not just classification images. The BAND_ONLY and NO_DIMS keywords limit you to only allow a single band with no spatial subset. The returned file ID and band number are retrieved with the FID and POS keywords, respectively. Use the keyword TITLE to set the dialog title bar to Classification Input File.
;; First get the integer file type value using ENVI_FILE_TYPE ;ftype = ENVI_FILE_TYPE('Classification');; Now prompt the user for the classification bandENVI_SELECT, fid=fid, pos=pos, /band_only, $ /no_dims, file_type=ftype, $ title='Classification Input File'if (fid[0] eq -1) then return
See Also
ENVI_OPEN_FILEENVI_PICKFILE
ENVI_SELECT ENVI Reference Guide
Chapter 2: ENVI Routines 365
ENVI_SENSOR_TYPE
Use this function to get a string or integer value of a particular sensor type. Inputting a string sensor type returns the corresponding integer value. The predefined sensor types are shown below, and you can also add sensor types to the file sensor.txt in the menu directory of the release tree.
Syntax
Result = ENVI_SENSOR_TYPE(Sensor_type)
Arguments
Sensor_type
Sensor_type can be either an integer or a string. If Sensor_type is an integer, the function returns the string-format description of the sensor type specified. If Sensor_type is a string, the function returns the integer code describing the sensor type specified.
NoteInteger codes change each time a new sensor type is added to ENVI, so the codes are not listed in the table below.
The string descriptors are case-sensitive and may contain spaces. Following is a list of valid string descriptors for Sensor_type:
AATSR, ADAR, ADEOS, ADRG, Air Photo, AIRSAR, AISA, ALOS, ASAR, ASTER, AVHRR, AVIRIS, CARTOSAT-1, CASI, COSMO-SkyMed, DMSP, EROS, ERS, GeoEye-1, GER63, GEOSCAN, HYDICE, HyMap, Hyperion, IKONOS, IRS LISSIII, IRS Pan, IRS WIFS, KOMPSAT-2, JERS-1, Landsat ETM, Landsat MSS, Landsat TM, MAS, MASTER, MERIS, MIVIS, MODIS, MOMS-02, OrbView-3, QuickBird, RADARSAT, RapidEye, Scanned Image, SEAWIFS, SEBASS, SIR-C, SPIN-2, SPOT, TIMS, TMS, TRWIS III, USGS DEM, WorldView, X-SAR
Example
The following example prints the sensor type string for the file associated with the file ID FID. The first command stores the integer file type descriptor in the variable SENSOR_TYPE:
envi_file_query, fid, sensor_type=sensor_type
The next line stores the string sensor type descriptor in the variable type_string:
type_string = envi_sensor_type(sensor_type)print, type_string
The following example enters the array DATA into ENVI and sets the sensor type to SPOT. The first line gets the integer sensor type for SPOT. The second line enters the data and sets the SENSOR_TYPE corresponding to SPOT.
sensor_type = envi_sensor_type('SPOT')envi_enter_data, DATA, sensor_type=sensor_type
ENVI Reference Guide ENVI_SENSOR_TYPE
366 Chapter 2: ENVI Routines
See Also
ENVI_FILE_QUERYENVI_FILE_TYPE
ENVI_SENSOR_TYPE ENVI Reference Guide
Chapter 2: ENVI Routines 367
ENVI_SET_INHERITANCE
Use this function to return the ENVI inheritance structure. ENVI inheritance allows a newly created ENVI file to automatically inherit properties from the original data. The result of this function is used to set the INHERIT keyword to the ENVI_SETUP_HEAD or ENVI_ENTER_DATA procedures. Use this function instead of directly accessing the inherit structure.
Syntax
Result = ENVI_SET_INHERITANCE(FID, DIMS [, POS] [, /BBL] [, /FILE_TYPE] [, /FULL] [, /FWHM] [, /GEO_POINTS] [, /MAP_INFO] [, /NO_SPATIAL] [, /PIXEL_SIZE] [, /SENSOR_TYPE] [, /SPATIAL] [, /SPECTRAL] [, /WL] [, /ZRANGE])
Arguments
FID
Use this argument to specify the file ID to inherit information from. The value of FID should be the file ID of the original data used to generate the new output image. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure or the FID keyword to ENVI_SELECT. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
DIMS
Use this argument to specify a five-element array of long integers representing the spatial dimensions to inherit information from. The value of DIMS should be the values used to compute the new output bands.
• DIMS[0]: Unused for this routine; set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
POS
Use this optional argument to specify an array of band positions, indicating the band numbers to inherit information from. The bands specified by POS should be the bands used to generate the new output image. POS is an array of long integers, ranging from 0 to the number of bands minus 1. The default is POS=[0], the first band.
Keywords
BBL (optional)Set this keyword to inherit the bad bands list.
ENVI Reference Guide ENVI_SET_INHERITANCE
368 Chapter 2: ENVI Routines
FILE_TYPE (optional)Set this keyword to inherit the file type.
FULL (optional)Set this keyword to enable full inheritance. The FULL keyword inherits wavelengths, full-width-half-maximum, bad bands list, sensor type, file type, map information, pixel size, (x,y) starting pixel, classification information, spectral library information, Z-plot range, geographic points, default stretch, and default RGB bands. If you set the FULL keyword, then you do not need the SPATIAL or SPECTRAL keywords.
FWHM (optional)Set this keyword to inherit full-width-half-maximum (FWHM) responses for each band.
GEO_POINTS (optional)Set this keyword to inherit geographic coordinates of the image corners.
MAP_INFO (optional)Set this keyword to inherit map information.
NO_SPATIAL (optional)Set this keyword to inhibit spatial inheritance. The NO_SPATIAL keyword turns off inheritance of map information, pixel size, (x,y) starting pixel, and geographic points. Use this keyword only in conjunction with the keyword FULL.
PIXEL_SIZE (optional)Set this keyword to inherit the pixel size from the original data, if the dataset is not georeferenced.
SENSOR_TYPE (optional)Set this keyword to inherit the sensor type.
SPATIAL (optional)Set this keyword to enable spatial inheritance. The SPATIAL keyword inherits map information, pixel size, the (x,y) starting pixel, and geographic points.
SPECTRAL (optional)Set this keyword to enable spectral inheritance. The SPECTRAL keyword inherits wavelengths, full-width-half-maximum, bad bands list, and default RGB bands.
WL (optional)Set this keyword to inherit wavelength information.
ZRANGE (optional)Set this keyword to inherit the lower and upper spectral plot range (Z-values).
ENVI_SET_INHERITANCE ENVI Reference Guide
Chapter 2: ENVI Routines 369
Example
The following example creates an inherit structure that inherits all the information from the original file. This example assumes that FID, DIMS and POS are previously set.
inherit = envi_set_inheritance(fid, dims, pos, /full)
The following example creates an inherit structure that inherits only the spectral information from the original file. This example assumes that FID, DIMS and POS are previously set.
inherit = envi_set_inheritance(fid, dims, pos, /spectral)
See Also
ENVI_ENTER_DATAENVI_SETUP_HEAD
ENVI Reference Guide ENVI_SET_INHERITANCE
370 Chapter 2: ENVI Routines
ENVI_SETUP_HEAD
Use this procedure to create the ENVI header information for a disk file. In order for disk files to be used in ENVI, they need the associated ENVI header information. The required keywords (DATA_TYPE, INTERLEAVE, NB, NL, NS, OFFSET) define the basic set of information needed to access the data in the file. The optional keywords allow you to define more specific file information.
In memory, data files do not need to call ENVI_SETUP_HEAD. Instead, they use ENVI_ENTER_DATA.
Syntax
ENVI_SETUP_HEAD [, BBL=array{0 | 1}] [, BNAMES=string array] [, BYTE_ORDER=variable], CLASS_NAMES=string array [, DATA_GAINS=variable] [, DATA_IGNORE_VALUE=variable] [, DATA_OFFSETS=array], DATA_TYPE={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15} [, DEF_BANDS=array] [, DEF_STRETCH=value] [, DESCRIP=string] [, FILE_TYPE=variable], FNAME=string [, FUNC_COMPLEX={0 | 1 | 2 | 3 | 4}] [, FWHM=array] [, GEO_POINTS=array] [, INFO=value] [, INHERIT=value], INTERLEAVE={0 | 1 | 2} [, LOOKUP=array] [, MAP_INFO=structure], NB=integer, NL=integer, NS=integer [, NUM_CLASSES=integer], OFFSET=integer [, /OPEN] [, PIXEL_SIZE=array] [, POINTER_INFO=structure] [, R_FID=variable] [, READ_PROCEDURE=variable] [, REFLECTANCE_SCALE_FACTOR=variable] [, SENSOR_TYPE=integer] [, SPEC_NAMES=variable] [, UNITS=integer] [, WAVELENGTH_UNIT={0 | 1 | 2 | 3 | 4 | 5 | 6}] [, WL=array] [, /WRITE] [, XSTART=integer] [, YSTART=integer] [, ZPLOT_AVERAGE=array] [, ZPLOT_TITLES=string array] [, ZRANGE=array]
Keywords
BBL (optional)Use this keyword to specify an array of ones and zeros representing the good and bad bands, respectively. The number of elements in BBL must be equal to the number of bands in the image.
BNAMES (optional)Use this keyword to specify the band names assigned to the data. BNAMES is a string array (with num_band elements) of band names. The default band names are [band 1, band 2, etc.]
BYTE_ORDER (optional)Use this keyword to specify a variable that contains a flag indicating the byte order of the data. Set BYTE_ORDER to 1 for big-endian data (generated on SUN, SGI, and PowerMac platforms) or to 0 for little-endian data (generated on PC x86). The default value is the byte order of your platform.
ENVI_SETUP_HEAD ENVI Reference Guide
Chapter 2: ENVI Routines 371
CLASS_NAMES
Use this keyword to specify a string array of class names for classification images. The first element (Class 0) is “Unclassified.” Only use CLASS_NAMES if the result is a classification image, in which case this keyword is required. If the result is not a classification image, this keyword is optional.
DATA_GAINS (optional)Use this keyword to specify a named variable that contains an array of gains for each band in the dataset. You can use DATA_GAINS in conjunction with DATA_OFFSETS in ENVI's general purpose utility, Apply Gain and Offset.
DATA_IGNORE_VALUE (optional)Use this keyword to specify a named variable that contains a scalar number representing the data value to ignore in the dataset. If set, DATA_IGNORE_VALUE is the same type as the input dataset, and an undefined ignore value is represented by the double-precision number 1e-34. Currently, this value is used only in user-written ENVI code.
DATA_OFFSETS (optional)Use this keyword to specify a named variable that contains an array of offsets for each band in the dataset. You can use this keyword in conjunction with DATA_GAINS in ENVI's general purpose utility, Apply Gain and Offset.
DATA_TYPE
Use this keyword to specify the IDL data type of the file, using the following IDL convention.
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
DEF_BANDS (optional)Set this keyword to a one- or three-element array specifying which bands to display upon opening the file in ENVI. If you set DEF_BANDS to a one-element array, ENVI loads a grayscale image in the display group. If you set DEF_BANDS to a three-element array, ENVI loads an RGB image in the display group. The values are zero-based. To load bands 4, 3, and 2 of a 7-band image, set DEF_BANDS to [3, 2, 1].
ENVI Reference Guide ENVI_SETUP_HEAD
372 Chapter 2: ENVI Routines
DEF_STRETCH (optional)Use this keyword to specify the default stretch information. Set DEF_STRETCH equal to the value returned from ENVI_DEFAULT_STRETCH_CREATE.
DESCRIP (optional)Use this keyword to specify a text description of the data or of the type of processing performed.
FILE_TYPE (optional)Use this keyword to specify a named variable that contains the integer file type value. See ENVI_FILE_TYPE for details on how to determine this value.
FNAME
Use this keyword to specify the name and path of the disk file. FNAME is a string variable that ENVI uses to open the file for reading.
FUNC_COMPLEX (optional)Set this keyword to one of the following values to specify the complex lookup function that determines how to display complex data.
• 0: Power (default): The natural log of the magnitude
• 1: Magnitude:
• 2: Real: The real portion of the complex number
• 3: Imaginary: The imaginary part of the complex number
• 4: Phase:
NoteOnly set this keyword if the IDL data type of the image is complex or double-precision complex.
FWHM (optional)Use this keyword to specify an array of full-width-half-maximum responses for each band. The number of elements in this array is equal to the number of bands in the image.
GEO_POINTS (optional)Use this keyword to specify a 16-element array of double-precision, floating-point values representing geographic coordinates for the upper-left, upper-right, lower-left, and lower-right corners of the image. The array consists of four groups of x and y pixel locations and their corresponding latitude and longitude values with the form [x, y, lat, lon]. South latitudes and west longitudes have negative values. The array is defined as follows:
• GEO_POINTS[0:3]: Upper left
• GEO_POINTS[4:7]: Upper right
• GEO_POINTS[8:11]: Lower left
• GEO_POINTS[12:15]: Lower right
real 2 inaryimag 2+
arc inaryimagreal
--------------------------tan
ENVI_SETUP_HEAD ENVI Reference Guide
Chapter 2: ENVI Routines 373
INFO (optional)Use this keyword to store information that is passed to your spatial and spectral readers. INFO is retrieved from ENVI_FILE_QUERY using the keyword H_INFO, which is a handle to the data. Use HANDLE_VALUE and the handle H_INFO to retrieve the data for INFO.
INHERIT (optional)Use this keyword to specify the file inheritance. Set INHERIT equal to the value returned from ENVI_SET_INHERITANCE.
INTERLEAVE
Set this keyword to one of the following integer values to specify the interleave output:
• 0: BSQ
• 1: BIL
• 2: BIP
LOOKUP (optional)Use this keyword to specify an array of long integers representing class RGB values. The LOOKUP array contains an RGB triplet for each class specified by the keyword NUM_CLASSES. The dimensions of the array are [3, num_classes+1], and the RGB triplet is ordered [r, g , b]. You must set LOOKUP when entering a classification image.
MAP_INFO (optional)Use this keyword to specify map information. Set MAP_INFO equal to the structure returned from ENVI_MAP_INFO_CREATE.
NB
Use this keyword to specify the number of bands in the file.
NL
Use this keyword to specify a the number of lines in the file.
NS
Use this keyword to specify the number of samples in the file.
NUM_CLASSES (optional)Use this keyword to specify the number of classes for classification files. Remember to include Class 0 (“Unclassified”) in the number of classes. You should only use this keyword for classification files.
OFFSET
Use this keyword to specify the offset (in bytes) to the start of the data in the file.
OPEN (optional)
ENVI Reference Guide ENVI_SETUP_HEAD
374 Chapter 2: ENVI Routines
Set this keyword to add the file to the Available Bands List. The default is not to add the file to this list.
PIXEL_SIZE (optional)Use this keyword to specify the pixel size of images that are not georeferenced. PIXEL_SIZE is a two-element array of floating-point values representing the x and y pixel sizes, respectively.
POINTER_INFO (optional)If FILE_TYPE='HDF SD', use this keyword to specify an anonymous structure containing data_set and ndims fields. The data_set field is a long integer indicating the HDF SD dataset index in the HDF file. The ndims field is a long integer indicating the number of dimensions of data_set.
R_FID (optional)See “Common Keywords” on page 34 for a definition of this keyword.
READ_PROCEDURE (optional)Use this keyword to specify a named variable that contains a string array of the procedure names for the spatial and spectral readers, respectively.
REFLECTANCE_SCALE_FACTOR (optional)Use this keyword to specify a named variable that contains a single scalar number used to convert the input data into reflectance. For example, you can use REFLECTANCE_SCALE_FACTOR to convert integer scaled reflectance data into floating-point [0, 1] reflectance values.
SENSOR_TYPE (optional)Use this keyword to specify an integer value related to the sensor type. See ENVI_SENSOR_TYPE for details on how to determine the integer sensor type value.
SPEC_NAMES (optional)Use this keyword to specify a named variable that contains a string array of spectral library names. You should set this keyword only for a spectral library file.
UNITS (optional)Use this keyword to specify the PIXEL_SIZE units for images that are not georeferenced. UNITS is an integer value returned from ENVI_TRANSLATE_PROJECTION_UNITS. Georeferenced images do not use this value. Instead, they use the pixel size and units contained in the map information structure.
WAVELENGTH_UNIT (optional)Use this keyword to specify a named variable that contains a value indicating the wavelength units. The valid values are as follows:
• 0: Micrometers
• 1: Nanometers
• 2: Wavenumber
ENVI_SETUP_HEAD ENVI Reference Guide
Chapter 2: ENVI Routines 375
• 3: GHz
• 4: MHz
• 5: Index
• 6: Unknown
WL (optional)Use this keyword to specify an array of wavelength values. The number of elements in this array is equal to the number of bands.
WRITE (optional)Set this keyword to write an output header to disk. The default is to not write an output header. It is valid to add a file to the Available Bands List (using the keyword OPEN) and not write the header file to disk. You should always set the WRITE keyword for files that you wish to open in a later ENVI session.
XSTART (optional)Use this keyword to specify the x starting sample for the first pixel in the file. The default is 0. Use XSTART in conjunction with YSTART to preserve the spatial reference for subsetted files. When processing a file, the XSTART of the output file is typically set to the XSTART of the input file plus the value of DIMS[1] (the starting sample).
YSTART (optional)Use this keyword to specify the y starting line for the first pixel in the file. The default is 0. Use YSTART in conjunction with XSTART to preserve the spatial reference for subsetted files. When processing a file, the YSTART of the output file is typically set to the YSTART of the input file plus the value of DIMS[3] (the starting line).
ZPLOT_AVERAGE (optional)Use this keyword to specify a two-element array of long integers representing the x and y window size (in pixels) for the Z Profile. The window size must be a value of 1 or greater. The Z Profile is formed from the average of the profiles within the specified window. The default window size is [1, 1].
ZPLOT_TITLES (optional)Use this keyword to specify a two-element string array with the x-axis and y-axis plot titles. The default x-axis title is “Band Number” for images with no wavelength information and “Wavelength” for images with wavelength information. The default y-axis title is “Value.”
ZRANGE (optional)Use this keyword to specify a 2D array for the lower and upper spectral plot range.
Example
The following example generates a 256x256, three-band, BSQ, byte ramp image using the function BINDGEN. Save this image to disk using the filename test.img. Once the file is saved to disk, ENVI_SETUP_HEAD will be used to write an ENVI header and add the image to the Available Bands List. This is one of the simplest uses of ENVI_SETUP_HEAD.
ENVI Reference Guide ENVI_SETUP_HEAD
376 Chapter 2: ENVI Routines
; Create the image array;data = BINDGEN(256,256,3);; Open the output file and write; the image to disk;fname = 'test.img'openw, unit, fname, /get_lunwriteu, unit, datafree_lun, unit;; Write the ENVI header and ; add the image to the Available; Bands List;ENVI_SETUP_HEAD, fname=fname, $ ns=256, nl=256, nb=3, $ interleave=0, data_type=1, $ offset=0, /write, /open
The next example creates two classes (plus the Unclassified class) from a single band ramp image, saves the file to disk, and enters the resulting classification image into ENVI. The Unclassified class is Black [0, 0, 0], the first class is Red [255, 0, 0] and the second class is Yellow [255, 255, 0]. The class names are Unclassified, Red, and Yellow. The classification image has the description “Example Classification Image” and the band name “Ramp Classification.”
; Create a 2D ramp and then classify all values ; from 20 to 100 in the first class (classification ; data value equal to one) and classify all values ; from 101 to 220 into the second class ; (classification data value equal to two);data = BINDGEN(256,256)class = BYTE((data ge 20 and data le 100) + $ 2B * (data ge 101 and data le 220));; Save the classification image to disk;fname = 'test.img'openw, unit, fname, /get_lunwriteu, unit, classfree_lun, unit;; Create the classification information;class_names = ['Unclassified','Red','Yellow']lookup = [[0,0,0],[255,0,0],[255,255,0]]bnames = ['Ramp Classification']descrip = 'Example Classification Image'file_type = ENVI_FILE_TYPE('ENVI Classification');; Write the ENVI header and add the image; to the Available Bands List;ENVI_SETUP_HEAD, fname=fname, $ ns=256, nl=256, nb=1, $
ENVI_SETUP_HEAD ENVI Reference Guide
Chapter 2: ENVI Routines 377
interleave=0, data_type=1, $ offset=0, num_classes=3, $ class_names=class_names, $ lookup=lookup, file_type=file_type, $ bnames=bnames, descrip=descrip, $ /write, /open
The next example assigns a geographic projection to a ramp image with the upper-left corner at 15 degrees south, 48 degrees west, and an x and y pixel size of one arc second. The map projection is created using ENVI_MAP_INFO_CREATE, and the resulting structure uses the MAP_INFO keyword when entering the data into ENVI.
; First create the ramp image. The ramp image ; would actually be replaced by a real ; georeferenced image.;data = BINDGEN(256,256);; Open the output file and write; the image to disk;fname = 'test.img'openw, unit, fname, /get_lunwriteu, unit, datafree_lun, unit;; Create the items used for the projection;mc = [.5D,.5, -48,-15]ps = [1D/3600, 1D/3600]units = ENVI_TRANSLATE_PROJECTION_UNITS('Degrees')map_info = ENVI_MAP_INFO_CREATE(/geographic, $ mc=mc, ps=ps, units=units);; Enter the data into ENVI;ENVI_SETUP_HEAD, fname=fname, $ ns=256, nl=256, nb=1, $ interleave=0, data_type=1, $ offset=0, map_info=map_info, $ /write, /open
See Also
ENVI_ENTER_DATA
ENVI Reference Guide ENVI_SETUP_HEAD
378 Chapter 2: ENVI Routines
ENVI_SMACC_DOIT
The ENVI_SMACC_DOIT procedure performs Sequential Maximum Angle Convex Cone (SMACC) processing on an input file. This procedure is designed for use with previously calibrated hyperspectral data or multispectral data.
This procedure applies the SMACC process to a radiance- or reflectance-calibrated hyperspectral image, and it returns the following outputs:
• A spectral library of derived endmembers
• An abundance image with N_ENDMEMBERS number of bands. This is an optional output.
• ROIs representing the set of endmembers. This is an optional output.
Syntax
ENVI_DOIT, 'ENVI_SMACC_DOIT' [, /ABUND_IN_MEMORY] [, ABUND_NAME=string] [, ABUND_R_FID=variable] [, COALESCE=value] , DIMS=array, FID=file ID, /IN_MEMORY [, M_FID=file ID] [, M_POS=integer], [, METHOD={0 | 1 | 2}], N_ENDMEMBERS=integer, OUT_NAME=string [, PLOT_FLAG=bitwise operator], POS=array, R_FID=variable [, ROI_NAME=string] [, THRESH=value]
Keywords
See “Common Keywords” on page 34 for definitions of the following eight keywords.
DIMS
FID
IN_MEMORY
M_FID (optional)
M_POS (optional)
OUT_NAME
POS
R_FID
ABUND_IN_MEMORY (optional)Set this keyword to generate an abundance image and save it in memory only. If you do not set ABUND_IN_MEMORY and you specify a filename for ABUND_NAME, the abundance image is generated and stored on disk.
ABUND_NAME (optional)
ENVI_SMACC_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 379
Use this keyword to specify a filename for the abundance image output. If you specify a filename for this keyword, an abundance image is generated and saved to a file with the filename. If you do not use ABUND_NAME and you set ABUND_IN_MEMORY, an abundance image is generated and stored in memory.
ABUND_R_FID (optional)Set this keyword to a named variable that contains the file ID of the output abundance image. This image is only generated if you specify either the ABUND_IN_MEMORY or ABUND_NAME keywords. If you specify neither keyword, an abundance image is not generated, and a value of –1 is returned for ABUND_R_FID.
COALESCE
Use this keyword to specify the maximum Spectral Angle Mapper (SAM) threshold value above which endmember spectra are considered unique. The default value is 0.0.
METHOD (optional)Use this keyword to specify an integer value that indicates the unmixing constraint for the SMACC method. The following list shows the integer values that represent each possible constraint and their related conditions.
• 0: Positivity only (default). Inputs should be calibrated to reflectance.
• 1: Sum to unity or less. Inputs should be calibrated to reflectance.
• 2: Sum to unity. Inputs should be calibrated to radiance or thermal IR emissivity.
All of these options also impose a positivity constraint. In the unmixing model, negative fractional abundances are not allowed and are set to 0.
If you specify METHOD=0 or 1, the SMACC method begins with an endmember value of 1.0 (total reflectance). If you specify METHOD=2, the SMACC method begins with an endmember value of 0.0 (zero radiance). Regardless, both of these endmembers are presumed to lie at an extreme point (or even outside) of a plausible convex hull. This point becomes a reasonable baseline for the SMACC method.
N_ENDMEMBERS
Use this keyword to specify the maximum number of desired endmembers.
PLOT_FLAG (optional)Use this keyword to specify an integer value that determines which resulting plot window is provided.
• 0: The endmember and residual error plots are not displayed (default).
• 1: The endmember plot is displayed.
• 2: The residual error plot is displayed.
• 3: Both plot windows are displayed.
ROI_NAME (optional)
ENVI Reference Guide ENVI_SMACC_DOIT
380 Chapter 2: ENVI Routines
Use this keyword to generate ROIs and to specify the name of the file that contains these ROIs. The generated ROIs contain the endmember pixels. If you do not set this keyword, the ROIs are not generated.
THRESH (optional)Use this keyword to specify the residual RMS error threshold at which the SMACC process is terminated.
NoteData units should be considered when choosing the tolerance. For example, RMS errors for reflectance units should be lower than for radiance units.
Examples
The following example uses the cup95eff.int file in the data directory. The SMACC process is used to create a spectral library of 10 endmembers from the data in this file.
PRO SMACCExample; This example procedure uses the ENVI_SMACC_DOIT procedure; (the Sequential Maximum Angle Convex Cone algorithm) to derive; a spectral library of endmembers for the data in the; "cup95eff.int" image file.
; Find the input image file and determine its file ID.cupriteFile = ENVI_PICKFILE(FILTER = '*.int', $
TITLE = 'Find the "cup95eff.int" File')IF (cupriteFile EQ '') THEN RETURNENVI_OPEN_FILE, cupriteFile, R_FID = cupriteFIDENVI_FILE_QUERY, cupriteFID, NB = cupriteNB, NS = cupriteNS, $
NL = cupriteNL, WL = cupriteWLscupriteDims = [-1, 0, cupriteNS - 1, 0, cupriteNL - 1]cupriteBandPos = LINDGEN(cupriteNB)
; Specify the number of resulting endmembers.numEndmembers = 10
; Apply the SMACC process to the input data.ENVI_DOIT, 'ENVI_SMACC_DOIT', FID = cupriteFID, $
DIMS = cupriteDims, $POS = cupriteBandPos, OUT_NAME = 'smaccExample.sli', $N_ENDMEMBERS = numEndmembers, R_FID = libFID
; Access and plot the resulting spectral library.ENVI_FILE_QUERY, libFID, NS = libNS, NL = libNL, WL = libWLslibDims = [-1, 0, libNS - 1, 0, libNL - 1]libData = ENVI_GET_DATA(FID = libFID, DIMS = libDims, POS = 0)ENVI_PLOT_DATA, libWLs, libData, XTITLE = 'Wavelength', $
YTITLE = 'Value'
END
This example procedure produces a plot of the 10 endmember spectra and a file (smaccExample.sli) containing the resulting spectral library.
ENVI_SMACC_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 381
ENVI_SPECTRAL_RESAMPLING_DOIT
This procedure spectrally resamples image or spectral library files. Resampled spectral libraries are added to the Available Bands List.
Syntax
ENVI_DOIT, 'ENVI_SPECTRAL_RESAMPLING_DOIT' [, BAD_VALUE=value] [, /COMPRESSION], DIMS, FID=file ID, /IN_MEMORY [, OUT_BNAME=string array] [, OUT_DT=integer] [, OUT_FWHM=array], OUT_NAME=string, OUT_WAVELENGTH_UNITS=integer, OUT_WL=array, POS=array [, R_FID=file ID]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
BAD_VALUE (optional)Use this keyword to specify a value to use for spectra that fall outside the input wavelength range. In this case, no extrapolation will be performed. All spectra values equal to BAD_VALUE are considered bad values. BAD_VALUE is a single number.
COMPRESSION (optional)Set this keyword to write the file using the standard GZIP format. IDL’s GZIP support is based on the freely available ZLIB library by Mark Adler and Jean-loup Gailly (see www.zlib.org for details). This means that IDL’s compressed files are 100% compatible with the widely available gzip and gunzip programs.
OUT_DT (optional)This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values.
NoteFor spectral libraries, the output data type is always floating-point.
• 1: Byte (8 bits)
ENVI Reference Guide ENVI_SPECTRAL_RESAMPLING_DOIT
382 Chapter 2: ENVI Routines
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
The default output type is the data type of the input file.
OUT_FWHM (optional)Use this keyword to specify a floating-point array of full-width-half-maximum responses for each output band. The number of elements in this array is equal to the number of output bands.
OUT_WAVELENGTH_UNITS
Use this keyword to specify an integer value representing the units used for the values of the OUT_WL array.
• 0: Micrometers
• 1: Nanometers
• 2: Wavenumber
• 3: GHz
• 4: MHz
• 5: Index
• 6: Unknown
OUT_WL
Use this keyword to specify an array of wavelengths to resample to.
ENVI_SPECTRAL_RESAMPLING_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 383
ENVI_STATS_DOIT
Use ENVI_STATS_DOIT to calculate statistics of a data file and optionally display the results or write the results to a file. The calculated statistics include covariance, data maximum, data minimum, eigenvalues, eigenvectors, histograms, mean, and standard deviation.
Syntax
ENVI_DOIT, 'ENVI_STATS_DOIT', CANCEL=variable, COMP_FLAG={0 | 1 | 2} [, COV=variable], DIMS=array [, DMAX=variable] [, DMIN=variable] [, EVAL=variable] [, EVEC=variable], FID=file ID [, HIST=variable] [, /INTERRUPT], M_FID=file ID, M_POS=long integer [, MEAN=variable] [, /OUTPUT_IMAGE], POS=array [, PREC=array] [, R_FID=variable] [, REP_NAME=string] [, REPORT_FLAG={0 | 1 | 2}] [, STA_NAME=string] [, STDV=variable] [, /TO_SCREEN] [, XFAC=floating point] [, YFAC=floating point]
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
FID
M_FID
M_POS
POS
CANCEL
Use this keyword to specify a named variable that returns the status of the Cancel button. A returned value of 1 indicates the Cancel button was pressed. A value of 0 is returned otherwise.
COMP_FLAG
Set this keyword equal to a bit value indicating the computations to perform. The bit values are combined with an OR logical operator to perform the requested calculations. The first bit is ignored. You must set additional bits to calculate histograms and to calculate convariance, eigenvalues, and eigenvectors. The definition of the bits used in COMP_FLAG are as follows:
• Bit 0 (COMP_FLAG=1): Enables the calculation of maximum, minimum, mean, and standard deviation
• Bit 1 (COMP_FLAG=2): Enables the calculation of histograms
• Bit 2 (COMP_FLAG=4): Enables the calculation of covariance, eigenvalues, and eigenvectors
ENVI Reference Guide ENVI_STATS_DOIT
384 Chapter 2: ENVI Routines
• Bit 3 to 15: Not used
If you only want maximum, minimum, mean, and standard deviation, then you should set COMP_FLAG to 1. Otherwise, set COMP_FLAG based on your preference to compute histograms (bit 1) or covariance, eigenvalues, and eigenvectors (bit 2). For example, to calculate all the available statistics (maximum, minimum, mean, standard deviation, histograms, covariance, eigenvalues, and eigenvectors), set COMP_FLAG=7.
COV (optional)Use this keyword to specify a named variable that contains the returned covariance matrix. You must set bit 2 in COMP_FLAG (i.e., COMP_FLAG=4) to generate the covariance matrix.
DMAX (optional)Use this keyword to specify a named variable that contains the array of data maximums, one for each band position.
DMIN (optional)Use this keyword to specify a named variable that contains the array of data minimums, one for each band position.
EVAL (optional)Use this keyword to specify a named variable that contains the eigenvalues. You must set bit 2 in COMP_FLAG (i.e., COMP_FLAG=4) to generate the eigenvalues.
EVEC (optional)Use this keyword to specify a named variable that contains the eigenvector. You must set bit 2 in COMP_FLAG (i.e., COMP_FLAG=4) to generate the eigenvectors.
HIST (optional)Use this keyword to specify a named variable that contains the histogram array. You must set bit 1 in COMP_FLAG (i.e., COMP_FLAG=2) to generate the histogram output.
INTERRUPT (optional)Set this keyword to allow processing interrupts using the Cancel button.
MEAN (optional)Use this keyword to specify a named variable that contains the array of data means, one for each band position.
OUTPUT_IMAGE (optional)Set this keyword to save the covariance matrix, correlation matrix, and eigenvectors to an image. The R_FID keyword can be used to access the file ID of the resulting image.
NoteYou must calculate covariance (COMP_FLAG=4 or greater) to generate this output image. If you do not set COMP_FLAG keyword to 4 or greater, the OUTPUT_IMAGE keyword is ignored.
ENVI_STATS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 385
PREC (optional)Use this keyword to specify the format for numbers printed in statistics reports. PREC is a two-element array of long integers with the following definitions:
• PREC[0]: Set to the desired number of digits to be printed after the decimal point.
• PREC[1]: Set to 0 to specify fixed-point notation or 1 to specify scientific (exponential) notation.
R_FID (optional)Use this keyword to specify a named variable that holds the file ID for the output image containing the covariance matrix, correlation matrix, and eigenvectors. The proper bit must be set in COMP_FLAG in order to save this image.
REP_NAME (optional)Use this keyword to specify the output report filename.
REPORT_FLAG (optional)Set this keyword to a bit value indicating the type of output reports desired. Combine the bit values with an AND logical operator to get the desired reports.
• Bit 0 (REPORT_FLAG=1): Basic statistics
• Bit 1 (REPORT_FLAG=2): Generate histogram report (default)
• Bit 2 (REPORT_FLAG=4): Generate covariance report
• Bits 3 to 15: Not used
If REPORT_FLAG=0, no output report is generated.
STA_NAME (optional)Use this keyword to specify the filename for the output statistics. You can view these files using the View Statistics File utility (see “Statistics” in the ENVI User’s Guide).
STDV (optional)Use this keyword to specify a named variable that contains the array of data standard deviations, one for each band position.
TO_SCREEN (optional)Set this keyword to print the report to the screen. This report presents all of the plot and text information in a single dialog on the screen.
XFAC (optional)Use this keyword to specify a x skip factor for computing statistics. XFAC is a floating-point value greater than or equal to 1.0 (default). For example, to compute statistics using every 10th pixel, set XFAC=10.0.
YFAC (optional)
ENVI Reference Guide ENVI_STATS_DOIT
386 Chapter 2: ENVI Routines
Use this keyword to specify a y skip factor for computing statistics. YFAC is a floating-point value greater than or equal to 1.0 (default). For example, to compute statistics using every 10th pixel, set YFAC=10.0.
Example
pro example_envi_stats_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Get the dimensions and # bands ; for the input file. ; envi_file_query, fid, dims=dims, nb=nb ; ; Set the POS keyword to calculate ; statistics for all data (spectrally) in the file. ; pos = lindgen(nb) ; ; Calculate the basic statistics and the ; histogram for the input data file. Print ; out the calculated information. ; envi_doit, 'envi_stats_doit', fid=fid, pos=pos, $ dims=dims, comp_flag=3, dmin=dmin, dmax=dmax, $ mean=mean, stdv=stdv, hist=hist ; print, 'Minimum ', dmin print, 'Maximum ', dmax print, 'Mean ', mean print, 'Standard Deviation ', stdv ; for i=0,nb-1 do begin print, 'Histogram Band ', i+1 print, hist[*,i] endfor ; ; Exit ENVI ; envi_batch_exitend
ENVI_STATS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 387
See Also
CLASS_STATS_DOITENVI_GET_STATISTICSENVI_WRITE_STATISTICS
ENVI Reference Guide ENVI_STATS_DOIT
388 Chapter 2: ENVI Routines
ENVI_SUBSPACE_BACKGROUND_STATS_DOIT
Syntax | Keywords | Example | See Also
Use this procedure to remove anomalous pixels prior to calculating background statistics with ENVI_ACE_DOIT, ENVI_CEM_DOIT, ENVI_TCIMF_DOIT, ENVI_TCIMF_MF_DOIT, MATCH_FILTER_DOIT, or MATCH_FILTER_MT_DOIT. When the true background is better characterized with subspace background, these spectral detection methods achieve greater target-to-background separation. ENVI_SUBSPACE_BACKGROUND_STATS_DOIT can potentially improve detection results, particularly in scenes that contain a lot of clutter or man-made objects.
Syntax
ENVI_DOIT, 'ENVI_SUUBSPACE_BACKGROUND_STATS_DOIT', FID=file ID, POS=array, DIMS=array [,M_FID=file ID] [,M_POS=value] [, BACKGROUND_THRESH=value] [, MEAN=variable] [, COV=variable] [, EVAL=variable] [, XFAC=value] [, YFAC=value] [, STA_NAME=string], STATUS=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
BACKGROUND_THRESH (optional)Use this keyword to specify the fraction of the background in the anomaly image to use for calculating the subspace background statistics. The data type is floating-point. The allowable range is 0.500 to 1.000 (the entire image). The default is 0.900.
MEAN (optional)Use this keyword to specify a named variable that contains the array of data means of subspace background, one for each band position.
COV (optional)Use this keyword to specify a named variable that contains the returned covariance matrix of subspace background.
EVAL (optional)Use this keyword to specify a named variable that contains the eigenvalues of the subspace background.
ENVI_SUBSPACE_BACKGROUND_STATS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 389
XFAC (optional)Use this keyword to specify an x skip factor for computing statistics. XFAC is a floating-point value greater than or equal to 1.0 (the default). For example, to compute statistics using every 10th pixel, set XFAC=10.
YFAC (optional)Use this keyword to specify a y skip factor for computing statistics. YFAC is a floating-point value greater than or equal to 1.0 (the default). For example, to compute statistics using every 10th pixel, set YFAC=10.
STA_NAME (optional)Use this keyword to specify the filename for the output subspace background statistics.
STATUS
Use this keyword to return the status of the computation. ENVI returns 0 upon success and -1 upon failure.
Example
pro example_envi_subspace_background_stats_doit
; First restore all the base save files. envi, /restore_base_save_files
; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt. envi_batch_init, log_file=’batch.txt’
; Open the input file. envi_open_file, ’mof94av.bil’, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Set the POS keyword ; to process all spectral data. ; Output the result to disk. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’mof94av_ss_mf’
; Compute subspace background statistics envi_doit, $ ’envi_subspace_background_stats_doit’, $ fid=fid, pos=pos, dims=dims, $ background_thresh=0.9, $ cov=cov, mean=mean, $ status=status if (status ne 0) then begin envi_batch_exit return endif
ENVI Reference Guide ENVI_SUBSPACE_BACKGROUND_STATS_DOIT
390 Chapter 2: ENVI Routines
; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for MF. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. envi_read_cols, ’m94_em.asc’, $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = em_names[2:*]
; Call the match filter processing ; routine. envi_doit,’match_filter_doit’, $ fid=fid, pos=pos, dims=dims, $ mean=mean, cov=cov, endmem=endmem, $ out_dt=4, out_name=out_name, $ out_bname=out_bname, r_fid=r_fid
; Exit ENVI envi_batch_exit
end
See Also
ENVI_ACE_DOITENVI_CEM_DOITENVI_TCIMF_DOITENVI_TCIMF_MF_DOITMATCH_FILTER_DOITMATCH_FILTER_MT_DOIT
ENVI_SUBSPACE_BACKGROUND_STATS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 391
ENVI_SUM_DATA_DOIT
Use this procedure to calculate statistical parameters on a set of bands. You can use this procedure to sum all the bands into an new output band and/or calculate other statistics as specified by COMPUTE_FLAG. All operations are performed pixel-by-pixel over the selected number of bands.
Syntax
ENVI_DOIT, 'ENVI_SUM_DATA_DOIT', COMPUTE_FLAG=array, DIMS=array, FID=file ID [, /IN_MEMORY], OUT_BNAME=string array, OUT_NAME=string, OUT_DT=value, POS=array [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME
OUT_NAME
POS
R_FID (optional)
COMPUTE_FLAG
Use this keyword to specify which output bands to calculate. COMPUTE_FLAG is a seven-element array of ones and zeros, where a value of 1 indicates the that the corresponding output band should be calculated. COMPUTE_FLAG has the following definitions:
• COMPUTE_FLAG[0]: Compute the sum of the bands defined by POS
• COMPUTE_FLAG[1]: Compute the sum squared of the bands defined by POS
• COMPUTE_FLAG[2]: Compute the mean of the bands defined by POS
• COMPUTE_FLAG[3]: Compute the standard deviation of the bands defined by POS
• COMPUTE_FLAG[4]: Compute the variance of the bands defined by POS
• COMPUTE_FLAG[5]: Compute the skewness of the bands defined by POS
• COMPUTE_FLAG[6]: Compute the kurtosis of the bands defined by POS
• COMPUTE_FLAG[7]: Compute the mean absolute deviation of the bands defined by POS
ENVI Reference Guide ENVI_SUM_DATA_DOIT
392 Chapter 2: ENVI Routines
OUT_DT
This keyword indicates the IDL data type of the output data.
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
Example
pro example_envi_sum_data_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords to process all the ; spectral data. ; Set the keyword COMPUTE_FLAG to ; compute the sum of the bands, the ; sum squared of the bands, the mean ; of the bands, and the standard ; deviation of the bands. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' compute_flag = [1,1,1,1,0,0,0,0] out_dt = 4 ; ; Call the processing routine to ; sum the data together. ; envi_doit, 'envi_sum_data_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, out_dt=out_dt, $ compute_flag=compute_flag ; ; Exit ENVI ; envi_batch_exitend
ENVI_SUM_DATA_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 393
See Also
ENVI_STATS_DOIT
ENVI Reference Guide ENVI_SUM_DATA_DOIT
394 Chapter 2: ENVI Routines
ENVI_SVM_DOIT
Use this procedure to perform supervised image classification using a support vector machine (SVM). The SVM is trained on a set of input ROIs for the image. Output class names, colors, and rule image band names are inherited from the input ROIs. You can use the optional keywords KERNEL_TYPE, KERNEL_DEGREE, KERNEL_GAMMA, KERNEL_BIAS, PENALTY, THRESH, PYRAMID_LEVELS, and PYRAMID_RECLASS_THRESH to control options specific to the SVM classifier. These options include kernel type and definition, penalty parameter, and can also be used to enable the use of hierarchical processing, which provides coarser overall results with reduced processing time. If not specified, the SVM classifier uses ENVI’s default SVM options.
Syntax
ENVI_DOIT, 'ENVI_SVM_DOIT', DIMS=array, FID=file ID [, /IN_MEMORY] [, OUT_BNAME=string array], OUT_NAME=string, POS=array [, R_FID=variable], ROI_IDS=array [, RULE_FID=variable] [, /RULE_IN_MEMORY] [, RULE_OUT_NAME=string] [, KERNEL_TYPE=value] [, KERNEL_DEGREE=value] [, KERNEL_BIAS=value] [, KERNEL_GAMMA=value] [, PENALTY=value] [, PYRAMID_LEVELS=value] [, PYRAMID_RECLASS_THRESH=value] [, THRESH=value]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
ROI_IDS
Use this keyword to specify an array of ROI IDs returned from a call to ENVI_GET_ROI_IDS. Each ID in the array will use the corresponding ROI to train the support vector machine.
RULE_FID (optional)
Use this keyword to specify a named variable that will contain the file ID for the processed rule image. This file ID can be used to access the processed data. If neither the
ENVI_SVM_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 395
RULE_OUT_NAME nor RULE_IN_MEMORY keywords are used, the return value of this keyword is undefined.
RULE_OUT_NAME (optional)
Use this keyword to specify an output filename for the rule image. If this keyword contains a valid filename, the rule image is saved.
RULE_IN_MEMORY (optional)
Set this keyword to store output rule images in memory. If this option is set, the rule image is saved.
KERNEL_TYPE (optional)
Use this keyword to specify the type of kernel to use for the SVM classification. Allowable values are:
• 0: Linear
• 1: Polynomial
• 2: Radial Basis Function (RBF) (default)
• 3: Sigmoid
KERNEL_DEGREE (optional)
Use this keyword to specify the degree of kernel to use for the SVM classification. This keyword only applies if a polynomial kernel is selected. The default is 2.
KERNEL_BIAS (optional)
Use this keyword to specify the kernel bias value to use for the SVM classification. This keyword only applies if a sigmoid or polynomial kernel is selected. The default is 1.
KERNEL_GAMMA (optional)
Use this keyword to specify the kernel gamma value to use for the SVM classification. This keyword is ignored if the kernel type is set to linear. The default is the inverse of the number of bands in the input image.
PENALTY (optional)
Use this keyword to specify the penalty parameter to use for the SVM classification. The default is 100. It is a floating point value greater than zero.
PYRAMID_LEVELS (optional)
Use this keyword to specify the number of hierarchical resolution levels to process. This value is an integer value from 0 (no special processing), which implies the input image will only be processed at full resolution. If set to an integer larger than 0, this value will specify the number of pyramid levels that will be processed. The maximum value varies depending on the image size the user selects. It is determined by the criteria that the highest pyramid-level image is larger than 64x64. For example, for an image size of 24000 x 24000, the maximum level available would be 8. The default is 0.
ENVI Reference Guide ENVI_SVM_DOIT
396 Chapter 2: ENVI Routines
PYRAMID_RECLASS_THRESH (optional)
Use this keyword to specify the probability threshold which a pixel must meet to avoid being reclassified at a finer resolution. This keyword is ignored if PYRAMID_LEVELS is not set to a value greater than 0. This is a floating point value ranging between 0.0 and 1.0 (all pixels classified). The default value is 0.9.
THRESH (optional)
Use this keyword to specify the minimum probability a pixel must have in order to be classified. Pixels with all class probabilities less than this threshold will not be classified. This value is a floating point value ranging between 0.0 (all pixels classified) and 1.0 (no pixels classified). The default is 0.0.
Example
pro example_envi_svm_doit
compile_opt strictarr
; First restore all the base save files. envi, /restore_base_save_files
; Initialize ENVI and send all errors ; and warnings to the file batch.txt envi_batch_init, log_file='batch.txt' ; Open the input file envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; Classify all data in the file. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'classresult' ; Restore the ROI file used as the training pixels. envi_restore_rois, 'bhtmref.roi' roi_ids = envi_get_roi_ids(fid=fid) ; Specify the SVM training and classification criteria thresh=0.5 penalty=75 kernel_type=1 kernel_degree=3 kernel_bias = 2.
; Call the svm classification doit routine envi_doit, 'envi_svm_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, $ roi_ids=roi_ids, thresh=thresh, $ penalty=penalty, kernel_type= kernel_type, $ kernel_degree=kernel_degree, kernel_bias=kernel_bias
ENVI_SVM_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 397
; Exit ENVI envi_batch_exit end
See Also
CLASS_DOITENVI_NEURAL_NET_DOITENVI_GET_ROI_IDS
ENVI Reference Guide ENVI_SVM_DOIT
398 Chapter 2: ENVI Routines
ENVI_SYNTHETIC_COLOR_DOIT
Use this procedure to calculate a synthetic color image from a single gray scale band. This program uses a low-pass filter, high-pass filter, and a saturation value as inputs into a hue saturation value (HSV) transform to create a synthetic color image.
Syntax
ENVI_DOIT, 'ENVI_SYNTHETIC_COLOR_DOIT', DIMS=array, FID=file ID, H_KSIZE=long integer, /IN_MEMORY, L_KSIZE=long integer, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, SAT_VALUE=floating point
Keywords
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
H_KSIZE
Use this keyword to specify the high-pass kernel size for the filter. The high pass filter is the value for the HSV transform. H_KSIZE is a long integer greater than 1.
L_KSIZE
Use this keyword to specify the low-pass kernel size for the filter. The low pass filter is the hue for the HSV transform. L_KSIZE is a long integer greater than 1.
SAT_VALUE
Use this keyword to specify a saturation value for the HSV transform. SAT_VALUE is a floating-point number from 0.0 to 1.0.
Example
pro example_envi_synthetic_color_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors
ENVI_SYNTHETIC_COLOR_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 399
; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keyword POS to calculate the ; synthetic color for the first ; band. Set the output band ; names to RGB. ; envi_file_query, fid, dims=dims pos = [0] out_bname = ['R','G','B'] out_name = 'testimg' ; ; Call the synthetic color processing ; routine. Set the low and high pass ; kernels to 10 pixels and use a ; saturation value of .5 for the HSV ; transform. ; envi_doit, 'envi_synthetic_color_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, out_bname=out_bname, $ h_ksize=10, l_ksize=10, sat_value=.5, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
MUNSELL_DOITMUNSELL_INV_DOITRGB_ITRANS_DOITRGB_TRANS_DOIT
ENVI Reference Guide ENVI_SYNTHETIC_COLOR_DOIT
400 Chapter 2: ENVI Routines
ENVI_TCIMF_DOIT
Syntax | Keywords | Example | See Also
Use this procedure to run the Target-Constrained Interference-Minimized Filter (TCIMF) target analysis. TCIMF detects the desired targets, eliminates non-targets, and minimizes interfering effects in one operation. TCIMF is constrained to eliminate the response of non-targets rather than minimizing their energy, just like other interferences in CEM. Previous studies show that if the spectral angle between the target and the non-target is significant, TCIMF can potentially reduce the number of false positives as compared to CEM results.
To remove anomalous pixels before modeling the scene background, run ENVI_SUBSPACE_BACKGROUND_STATS_DOIT prior to ENVI_TCIMF_DOIT. Removing anomalous pixels prior to modeling the scene background can potentially improve the results, particularly in a scene that has a lot of clutter or man-made objects.
Syntax
ENVI_DOIT, 'ENVI_TCIMF_DOIT', FID=file ID, POS=array, DIMS=array [,M_FID=file ID] [,M_POS=value], TARGET=array [, NON_TARGET=variable] [, COV=array] [, USE_COV=variable] [, /IN_MEMORY], OUT_NAME=string [, OUT_BNAME=string array] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of these keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
IN_MEMORY (optional)
OUT_NAME
OUT_BNAME (optional)
R_FID (optional)
TARGET
Use this keyword to specify the target spectra. It is a floating-point array. The array size is [number of input bands, number of target spectra].
NON_TARGET (optional)
ENVI_TCIMF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 401
Use this keyword to specify the non-target spectra. It is a floating-point array. The array size is [number of input bands, number of target spectra]. TCIMF is constrained to eliminate the response of non-targets, and has the potential to reduce the false positives over CEM. If this keyword is not defined, you need to define at least two target spectra so that each target can use the other as non-target information.
COV (optional)Use this keyword to specify the covariance matrix input bands. If the keyword is not defined, ENVI computes it internally.
USE_COV (optional)Use this keyword to specify using the covariance matrix as background statistics instead of the input bands correlation matrix. By default, ENVI uses the input bands correlation matrix as background statistics, which is derived from the covariance matrix internally. If this keyword is defines, it must be with a nonzero value.
Example
pro example_envi_tcimf_doit
; First restore all the base save files. envi, /restore_base_save_files ; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt. envi_batch_init, log_file=’batch.txt’
; Open the input file envi_open_file, ’mof94av.bil’, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Set the POS keyword ; to process all spectral data. ; Output the result to disk. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’mof94av_tcimf’ ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for TCIMF. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. envi_read_cols, ’m94_em.asc’, $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = ’TCIMF Score (’ + $ em_names[2:*] + ’)’
ENVI Reference Guide ENVI_TCIMF_DOIT
402 Chapter 2: ENVI Routines
; Calculate the covariance of the ; input data file. envi_doit, ’envi_stats_doit’, $ fid=fid, pos=pos, dims=dims, $ cov=cov, comp_flag=5
; Call the Target-Constrained ; Interference-Minimized Filter ; processing routine. envi_doit,’envi_tcimf_doit’, $ fid=fid, pos=pos, dims=dims, $ target=endmem, cov=cov, $ /use_cov, out_name=out_name, $ out_bname=out_bname, r_fid=r_fid
; Exit ENVI envi_batch_exit end
See Also
ENVI_ACE_DOITENVI_CEM_DOITENVI_OSP_DOITENVI_SUBSPACE_BACKGROUND_STATS_DOITENVI_TCIMF_MF_DOIT
ENVI_TCIMF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 403
ENVI_TCIMF_MF_DOIT
Syntax | Keywords | Example | See Also
Use this procedure to perform the Mixture Tuned Target-Constrained Interference-Minimized Filter (MTTCIMF) target detection analysis. It combines the Mixture Tuned technique and TCIMF target detector. This method uses a Minimum Noise Fraction (MNF) transform input file to perform TCIMF, and adds an infeasibility image to the results. The infeasibility image is used to reduce the number of false positives that are sometimes found when using TCIMF alone. The output of MTTCIMF is a set of rule images corresponding to TCIMF scores and a set of images corresponding to infeasibility values. The infeasibility results are in noise sigma units and indicate the feasibility of the TCIMF result. Correctly mapped pixels have a high TCIMF score and a low infeasibility value. If non-target spectra are specified, MTTCIMF can potentially reduce the number of false positives as compared to MTMF results.
To remove anomalous pixels before modeling the scene background, run ENVI_SUBSPACE_BACKGROUND_STATS_DOIT prior to ENVI_TCIMF_MF_DOIT. Removing anomalous pixels prior to modeling the scene background can potentially improve the results, particularly in a scene that has a lot of clutter or man-made objects.
Syntax
ENVI_DOIT, 'ENVI_TCIMF_DOIT', FID=file ID, POS=array, DIMS=array [,M_FID=file ID] [,M_POS=value], TARGET=array [, NON_TARGET=variable] [, COV=array] [, EVAL=array] [, /IN_MEMORY], OUT_NAME=string [, OUT_BNAME=string array] [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of these keywords.
FID
POS
DIMS
M_FID (optional)
M_POS (optional)
ENVI Reference Guide ENVI_TCIMF_MF_DOIT
404 Chapter 2: ENVI Routines
IN_MEMORY (optional)
OUT_NAME
OUT_BNAME (optional)
R_FID (optional)
TARGET
Use this keyword to specify the target spectra. It is a floating-point array. The array size is [number of input bands, number of target spectra].
NON_TARGET (optional)Use this keyword to specify the non-target spectra. It is a floating-point array. The array size is [number of input bands, number of target spectra]. If this keyword is not defined, you need to define at least two target spectra so that each target can use the other as non-target information.
COV (optional)Use this keyword to specify the input bands covariance matrix. If the keyword is not defined, ENVI computes it internally.
EVAL (optional)Use this keyword to specify the input bands eigenvalues. If the keyword is not defined, it will be computed internally.
Example
pro example_envi_tcimf_mt_doit
; First restore all the base save files. envi, /restore_base_save_files ; Initialize ENVI in the batch mode ; and send all errors and warnings ; to the file batch.txt. envi_batch_init, log_file=’batch.txt’
; Open the input file envi_open_file, ’mof94av.bil’, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Set the POS keyword ; to process all spectral data. ; Output the result to disk. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = ’mof94av_mttcimf’ ; Read in the endmember text file.
ENVI_TCIMF_MF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 405
; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for MTTCIMF. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. envi_read_cols, ’m94_em.asc’, $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = [ $ ’TCIMF Score (’ + em_names[2:*] + ’)’, $ ’Infeasibility (’ + em_names[2:*] + ’)’] ; Calculate the statistics of the ; input data file. envi_doit, ’envi_stats_doit’, $ fid=fid, pos=pos, dims=dims, $ cov=cov, eval=eval, comp_flag=5
; Call the Mixture Tuned TCIMF ; processing routine. envi_doit,’envi_tcimf_mt_doit’, $ fid=fid, pos=pos, dims=dims, $ target=endmem, cov=cov, eval=eval, $ out_name=out_name, $ out_bname=out_bname, r_fid=r_fid
; Exit ENVI envi_batch_exit end
See Also
ENVI_ACE_DOITENVI_CEM_DOITENVI_OSP_DOITENVI_SUBSPACE_BACKGROUND_STATS_DOITENVI_TCIMF_DOITMATCH_FILTER_MT_DOITMNF_DOIT
ENVI Reference Guide ENVI_TCIMF_MF_DOIT
406 Chapter 2: ENVI Routines
ENVI_THERMAL_CORRECT_DOIT
Use this procedure to calculate the thermal infrared atmospheric correction. The input into this procedure must be a thermal multi-band image with associated wavelength values. If you do not specify wavelength units in the file header, you must supply them with the optional keyword WL_UNITS. The image should be in units of (W/m2/m/sr). The optional keyword DATA_SCALE is used to convert the image to these units. The keywords METHOD_LF and METHOD_PS allow you to control the data gain and offset calculations. Additional keywords allow you to output a gain and offset file and plot the transmission/upwelling.
Syntax
ENVI_DOIT, 'ENVI_THERMAL_CORRECT_DOIT' [, /DATA_SCALE], DIMS=array, FID=file ID, /IN_MEMORY [, /MAKEPLOTS], METHOD_LF={0 | 1}, METHOD_PS={0 | 1} [, NESR=value] [, OUT_BNAME=string array] [, OUT_CFF=string], OUT_NAME=string, POS=array [, R_FID=file ID] [, WL_UNITS=integer]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
DATA_SCALE (optional)Use this keyword to specify the data scaling factor to convert the image to W/m2/m/sr, prior to calculating the thermal atmospheric correction. The default is to perform no data scaling.
MAKEPLOTS (optional)Set this keyword to plot the transmission/upwelling of the data. The default is to not plot the data.
METHOD_LF
Use this keyword to specify the method for fitting the line in the data gain and offset calculation. METHOD_LF is one of the following integer values.
• 0: Top of bin
ENVI_THERMAL_CORRECT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 407
• 1: Normalized regression (requires the keyword NESR)
METHOD_PS
Use this keyword to specify the regression method in the data gain and offset calculation. METHOD_PS is one of the following integer values.
• 0: All pixels
• 1: Max hit
NESR (optional)Use this keyword to specify the noise equivalent spectral radiance (NESR) value. You must specify this value if METHOD_LF=1.
OUT_CFF (optional)Use this keyword to specify an output filename for the gain and offset values used to atmospherically correct each band. The file contains a gain and offset value for each band specified by the POS array. The default is to not save the gain and offset value to a file.
WL_UNITS (optional)Use this keyword to specify the wavelength units for the file specified by FID. WL_UNITS is required when the file header does not contain any wavelength units.
See Also
EMITTANCE_CALC_DOIT
ENVI Reference Guide ENVI_THERMAL_CORRECT_DOIT
408 Chapter 2: ENVI Routines
ENVI_TILE_DONE
This procedure frees the tile request once tile processing is complete. This procedure must be called once the processing routine has completed the tiling process.
Syntax
ENVI_TILE_DONE, Tile_id
Arguments
Tile_id
The tile ID is returned from ENVI_INIT_TILE.
See also
ENVI_INIT_TILEENVI_GET_TILE
ENVI_TILE_DONE ENVI Reference Guide
Chapter 2: ENVI Routines 409
ENVI_TOGGLE_CATCH
Use this routine to toggle the ENVI error catching handling mechanism on and off. When toggled off the catch mechanism will not redirect IDL programming or execution errors. Instead, errors will be handled according to IDL. This routine is useful when debugging user-developed ENVI routines.
Syntax
ENVI_TOGGLE_CATCH
ENVI Reference Guide ENVI_TOGGLE_CATCH
410 Chapter 2: ENVI Routines
ENVI_TRANSLATE_PROJECTION_NAME
ENVI supports a number of different projection types. This function translates between the projection name string and the projection type integer value.
Syntax
Result = ENVI_TRANSLATE_PROJECTION_NAME(Val)
Arguments
Val
Val can be either an integer or a string. If Val is an integer, the function returns the string-format description of the projection name. If Val is a string, the function returns the integer code describing the projection type.
Example
type = envi_translate_projection_name('State Plane')
or
proj_name = envi_translate_projection_name(3)
See Also
ENVI_MAP_INFO_CREATE
ENVI_TRANSLATE_PROJECTION_NAME ENVI Reference Guide
Chapter 2: ENVI Routines 411
ENVI_TRANSLATE_PROJECTION_UNITS
ENVI supports a number of different projection units. This function translates between the projection units string and the projection units integer value.
Syntax
Result = ENVI_TRANSLATE_PROJECTION_UNITS(Val)
Arguments
Val
Val can be either an integer or a string. If Val is an integer, the function returns the string-format description of the projection units. If Val is a string, the function returns the integer code describing the projection units.
NoteBecause additional unit types may be added in future releases of ENVI, we strongly recommend that you use string descriptors rather than integer descriptors when referring to projection units. See the example below.
Example
units = envi_translate_projection_units('Meters')
See Also
ENVI_MAP_INFO_CREATE
ENVI Reference Guide ENVI_TRANSLATE_PROJECTION_UNITS
412 Chapter 2: ENVI Routines
ENVI_USER_DEFINED_ANNOTATION
Use this procedure to create an ENVI annotation file or append items to an existing annotation file. If the annotation file does not exist, ENVI creates a new annotation file and adds the specified item. If the annotation file exists, each subsequent call to ENVI_USER_DEFINED_ANNOTATION adds another annotation item to the file. The desired item is specified by the appropriate keywords and associated parameters.
Syntax
ENVI_USER_DEFINED_ANNOTATION, Name, X, Y [, ALIGN={0 | 0.5 | 1}] [, /ARROW] [, BGCOLOR=integer] [, CHARSIZE=floating point] [, COLOR=integer] [, /COL_RAMP] [, FILL_MODE={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7}] [, FILL_ORIEN=integer] [, FILL_SPACING=floating point] [, FONT=string] [, IMAGE=array] [, LSTYLE=integer] [, /MAP_KEY] [, ORIEN=integer], [, /POLYGON] [, /POLYLINE] [, /SCALE_BARS] [, STR_TEXT=string] [, /TEXT] [, THICK=integer] [, USE_MAP_COORDS=file ID]
Optional keywords for ARROW:
[, HEAD_ANGLE=floating point] [, HEAD_PCT=floating point]
Optional keywords for COL_RAMP:
[, RAMP_INC=integer] [, RAMP_LENGTH=integer] [, RAMP_MAX_VAL=floating point] [, RAMP_MIN_VAL=floating point] [, RAMP_ORIEN={0 | 1 | 2 | 3}] [, RAMP_PRECISION=integer] [, RAMP_WIDTH=integer]
Optional keywords for MAP_KEY:
[, KEY_FILL_MODE=integer] [, KEY_FILL_ORIEN=integer] [, KEY_FILL_SPACING=floating point]
Keywords for SCALE_BARS (all are optional except PIXEL_SIZE):
PIXEL_SIZE=floating point [, SCALE_FLAG=array] [, SCALE_HEIGHT=integer] [, SCALE_INC=array] [, SCALE_LENGTH=array] [, SCALE_SUB_INC=array] [, SCALE_TITLES=string array]
Arguments
Name
This is a string variable specifying the annotation filename. If Name does not exist, ENVI creates a new annotation file. If Name exists, ENVI appends the desired item to the annotation file.
X
This is the x pixel location for the annotation item.
Y
This is the y pixel location for the annotation item.
ENVI_USER_DEFINED_ANNOTATION ENVI Reference Guide
Chapter 2: ENVI Routines 413
Keywords
ALIGN (optional)Use this keyword to specify the text alignment for annotation objects supporting this keyword. ALIGN is one of the following floating-point values:
• 0.0: Left justified
• 0.5: Centered
• 1.0: Right justified
ARROW (optional)Set this keyword to specify that the annotation item is an arrow. If you set ARROW, the x and y location parameters are not used, but you must specify the keywords XPTS and YPTS to define the two end points of the arrow (in image coordinates). Optional keywords that you can use with ARROW include COLOR, FILL_MODE, FILL_ORIEN, FILL_SPACING, HEAD_ANGLE, HEAD_PCT, LSTYLE, and THICK.
BGCOLOR (optional)Use this keyword to specify the background color index for annotation objects supporting this keyword. BGCOLOR is an integer color index where 0 is black, 1 is white, 2 is red, etc. Set BGCOLOR equal to -1 for no background.
CHARSIZE (optional)Use this keyword to specify the character size for annotation objects supporting this keyword. CHARSIZE is a floating-point value specifying the character size.
COLOR (optional)Use this keyword to specify the color index for annotation objects supporting this keyword. COLOR is an integer color index into the graphic colors where the default colors are 0 (black), 1 (white), 2 (red), etc.
COL_RAMP (optional)Set this keyword to specify that the annotation item is a color ramp. If you set COL_RAMP, you must set the x and y location parameters (in image coordinates). Optional keywords that you can use with COL_RAMP include BGCOLOR, COLOR, CHARSIZE, FONT, RAMP_LENGTH, RAMP_INC, RAMP_MAX_VAL, RAMP_MIN_VAL, RAMP_ORIEN, RAMP_PRECISION, RAMP_WIDTH, and THICK.
FILL_MODE (optional)Use this keyword to specify the IDL fill style for annotation objects supporting this keyword. FILL_MODE is one of the following integer values.
• 0: No fill
• 1: Solid fill
• 2: Solid line fill
• 3: Dotted line fill
ENVI Reference Guide ENVI_USER_DEFINED_ANNOTATION
414 Chapter 2: ENVI Routines
• 4: Dashed line fill
• 5: Dash dot line fill
• 6: Dash dot dot line fill
• 7: Long dash line fill
FILL_ORIEN (optional)Use this keyword to specify the rotation of fill for annotation objects supporting this keyword. FILL_ORIEN is an integer value greater than 1.
FILL_SPACING (optional)Use this keyword to specify the spacing of fill for annotation objects supporting this keyword. FILL_SPACING is floating-point number. This keyword is only used for FILL_MODE values greater than 1.
FONT (optional)Use this keyword to specify the font for annotation objects supporting this keyword. FONT is a string value specifying either a hershey font (“!3” to “!20”) or a valid name for a true-type font (“Courier”).
IMAGE (optional)Use this keyword to specify an annotation image. IMAGE is a byte array with dimensions [num_samples, num_lines] for gray scale or [num_samples, num_lines, 3] for RGB images. If you set IMAGE, you must set the x and y location parameters (in image coordinates), which reference the lower-left corner of IMAGE.
LSTYLE (optional)Use this keyword to specify the IDL line style for annotation objects supporting this keyword. LSTYLE is an integer value.
MAP_KEY (optional)Set this keyword to specify that the annotation item is a map key. If you set MAP_KEY, you must set the x and y location parameters (in image coordinates) and specify the keywords KEY_COLORS and KEY_NAMES. Optional keywords for MAP_KEY include BGCOLOR, CHARSIZE, COLOR, FONT, KEY_FILL_MODE, KEY_FILL_ORIEN, KEY_FILL_SPACING, and THICK.
ORIEN (optional)Use this keyword to specify the orientation for annotation objects supporting this keyword. ORIEN is an integer value specifying the clockwise rotation angle.
POLYGON (optional)Set this keyword to specify that the annotation item is a polygon. If you set POLYGON, the x and y location parameters are not used, but you must use the keywords XPTS and YPTS to define the vertices of the polygon (in image coordinates). Optional keywords that you can use with POLYGON include COLOR, FILL_MODE, FILL_ORIEN, FILL_SPACING, LSTYLE, and THICK.
ENVI_USER_DEFINED_ANNOTATION ENVI Reference Guide
Chapter 2: ENVI Routines 415
POLYLINE (optional)Set this keyword to specify that the annotation item is a polyline. If you set POLYLINE, the x and y location parameters are not used, but you must use the keywords XPTS and YPTS to define the polyline vertices (in image coordinates). Optional keywords that you can use with POLYLINE include COLOR, LSTYLE, and THICK.
SCALE_BARS (optional)Set this keyword to specify that the annotation item is a scale bar. If you set SCALE_BARS, you must specify the x and y location parameters (in image coordinates) and the keyword PIXEL_SIZE. Optional keywords that you can use with SCALE_BARS include BGCOLOR, COLOR, FONT, SCALE_FLAG, SCALE_HEIGHT, SCALE_INC, SCALE_LENGTH, SCALE_SUB_INC, SCALE_TITLES, and THICK.
STR_TEXT (optional)Use this keyword to specify the text string for the annotation item TEXT. You must delineate multiple lines of text with !C!C. For example, ‘Hello!C!CWorld’ prints Hello and World on separate lines.
TEXT (optional)Set this keyword to specify that the annotation item is a text string. If you set TEXT, you must specify the x and y location parameters and the STR_TEXT keyword. Optional keywords that you can use with TEXT include ALIGN, BGCOLOR, CHARSIZE, COLOR, FONT, ORIEN, and THICK.
THICK (optional)Use this optional integer keyword to specify the line thickness of hershey-font characters for annotation objects supporting this keyword.
USE_MAP_COORDS (optional)Set this keyword to the FID of a georeferenced image to put the (x,y) and (xpts,ypts) coordinates sent to this procedure in map coordinates instead of file coordinates.
Keywords for ARROW
HEAD_ANGLE (optional)Use this keyword to specify the head angle of an ARROW annotation object. HEAD_ANGLE is a floating-point value greater than 0, specifying the angle in degrees of the arrow head. The default value is 35.0.
HEAD_PCT (optional)Use this keyword to specify the size of the head for an ARROW annotation object. HEAD_PCT is a floating-point value between 0.0 and 1.0, specifying the percentage of the head size versus the overall length. The default value is 0.15.
Keywords for COL_RAMP
RAMP_INC (optional)
ENVI Reference Guide ENVI_USER_DEFINED_ANNOTATION
416 Chapter 2: ENVI Routines
Use this keyword to specify the number of color ramp increments. RAMP_INC is an integer value specifying number of increments. The default value is 3.
RAMP_LENGTH (optional)Use this keyword to specify the color ramp length in pixels. RAMP_LENGTH is an integer value specifying the color ramp length in pixels. The default value is 200.
RAMP_MAX_VAL (optional)Use this keyword to specify the value associated with the high end of the color ramp. RAMP_MAX_VAL is a floating-point value.
RAMP_MIN_VAL (optional)Use this keyword to specify the value associated with the low end of the color ramp. RAMP_MIN_VAL is a floating-point value.
RAMP_ORIEN (optional)Use this keyword to specify the color ramp orientation. RAMP_ORIEN is one of the following integer values:
• 0: Horizontal (low to high)
• 1: Vertical (high to low)
• 2: Horizontal (high to low)
• 3: Vertical (low to high)
RAMP_PRECISION (optional)Use this keyword to specify the number of precision digits for color ramp values. RAMP_PRECISION is an integer. The default value is 1.
RAMP_WIDTH (optional)Use this keyword to specify the color ramp width in pixels. RAMP_WIDTH is an integer. The default value is 25.
Keywords for MAP_KEY
KEY_FILL_MODE (optional)Use this keyword to specify the IDL fill mode for map key polygons. KEY_FILL_MODE is an integer value indicating the IDL fill mode. The default value is 0 (no fill).
KEY_FILL_ORIEN (optional)Use this keyword to specify the orientation for fill. KEY_FILL_ORIEN is an integer value greater than l. The default value is 0 (no rotation).
KEY_FILL_SPACING (optional)Use this keyword to specify the spacing for fill. KEY_FILL_SPACING is floating-point value indicating the fill spacing. KEY_FILL_SPACING is only valid when KEY_FILL_MODE is greater than 1. The default value is 0.1.
ENVI_USER_DEFINED_ANNOTATION ENVI Reference Guide
Chapter 2: ENVI Routines 417
Keywords for SCALE_BARS
PIXEL_SIZE
Use this keyword to specify a floating-point number that represents both the x and y pixel size in meters. If the pixel size is not in meters, you need to convert it to meters. If the x and y pixel sizes are different, use the x pixel size (since scale bars are always horizontal).
SCALE_FLAG (optional)Use this keyword to specify which units are active for a scale bar. SCALE_FLAG is a four-element byte array of zeros and ones, where a value of 1 makes the corresponding units active. The elements of SCALE_FLAG correspond to the units [km, miles, meters, feet]. The default is [1, 0, 0, 0], displaying only kilometer units.
SCALE_HEIGHT (optional)Use this keyword to specify the height in pixels for the scale bars. SCALE_HEIGHT is an integer value specifying the scale bar height in pixels. The default value is 25.
SCALE_INC (optional)Use this keyword to specify the number of increments for each type of scale bar. SCALE_INC is a four-element array of integers specifying the number of increments for each of the units [km, miles, meters, feet]. The default is [1, 1, 1, 1].
SCALE_LENGTH (optional)Use this keyword to specify the length in map scale for each type of scale bar. SCALE_LENGTH is a four-element array of floating-point values specifying the length in map scale for each of the units [km, miles, meters, feet].
SCALE_SUB_INC (optional)Use this keyword to specify the number of sub-increments for the first unit of a given scale bar. SCALE_SUB_INC is a four-element array of integers specifying the number of increments for each of the units [km, miles, meters, feet]. The default is [4, 4, 4, 4].
SCALE_TITLES (optional)Use this keyword to specify the titles for each scale bar. SCALE_TITLE is a four-element string array specifying the titles for each of the units [km, miles, meters, feet]. Use a null string ('') for units that you do not use. The default is ['Kilometers', 'Miles', 'Meters', 'Feet'].
Example
pro annotation_demo
compile_opt strictarr
; For this example, just pick bhtmref.img that comes with ENVIin_file = DIALOG_PICKFILE()
; Now we’re opening the fileENVI_OPEN_FILE, in_file, R_FID = in_fid
ENVI Reference Guide ENVI_USER_DEFINED_ANNOTATION
418 Chapter 2: ENVI Routines
; This next command will add a text object to the annotation file; example_annotation_file.ann; The lower left corner of the text object will be at the ; ENVI image coordinates of 50,50. The text object has 2 lines,; which both say, "Text Test Object", and will be in red; lettering.ENVI_USER_DEFINED_ANNOTATION, 'example_annotation_file.ann', $
125, 50, STR_TEXT = 'Text!C!CTest Object', COLOR = 2, /TEXT,$ALIGN = 0.5
; Now we’ll add a small image, just a test picture.; The lower left corner of the test picture will be at ENVI $; image coordinate 50,140 which will place it just below our text.image = BYTSCL(DIST(40))ENVI_USER_DEFINED_ANNOTATION, 'example_annotation_file.ann', $
50, 140, image=image
; If you restore the annotation file on the image in ENVI you; should see the objects placed as described above.
end
ENVI_USER_DEFINED_ANNOTATION ENVI Reference Guide
Chapter 2: ENVI Routines 419
ENVI_VEG_INDEX_AVAILABLE_INDICES
This function returns the number of vegetation indices that can be calculated on an input data file. It can optionally return the names of these indices, a classification describing the purpose of the index, or, if no indices are available, a descriptive error specifying the reason why.
Syntax
Result = ENVI_VEG_INDEX_AVAILABLE_INDICES (FID [, ERROR_STRING=string] [, VI_LIST=array] [, VI_NAMES=string] [, VI_TYPE=array])
Arguments
FID
Use this keyword to specify the file ID for the input file.
Keywords
ERROR_STRING (optional)Set this keyword to a named variable in which to return a descriptive error string describing the reason that no vegetation indices are available, if the return value of the function is 0. Otherwise, this keyword is undefined.
VI_LIST (optional)Set this keyword to a named variable in which to return an array of long integers containing the numeric indices associated with each vegetation index available for calculation, if any. These indices can be used to specify the desired subset of indices for the ENVI_VEG_INDEX_DOIT procedure to calculate. If the ENVI_VEG_INDEX_AVAILABLE_INDICES return value is 0, this keyword is undefined.
VI_NAMES (optional)Set this keyword to a named variable in which to return a string array containing the names of all vegetation indices available for calculation, if any. See “Vegetation Indices” in ENVI Help for a complete list of vegetation index names. If the ENVI_VEG_INDEX_AVAILABLE_INDICES return value is 0, this keyword is undefined.
VI_TYPE (optional)Set this keyword to a named variable in which to return a string containing the names of the categories for all vegetation indices available for calculation. See “Vegetation Indices” in ENVI Help for a complete list of VI categories. If the ENVI_VEG_INDEX_AVAILABLE_INDICES return value is 0, this keyword is undefined.
Example
The following example code shows how to calculate a subset of VIs.
pro example_veg_index_2compile_opt strictarr
ENVI Reference Guide ENVI_VEG_INDEX_AVAILABLE_INDICES
420 Chapter 2: ENVI Routines
; This example calculates a subset of the available vegetation ; indices determined using both ; the ENVI_VEG_INDEX_AVAILABLE_INDICES procedure ; and the ENVI_VEG_INDEX_DOIT procedure ; First, restore all the base save files. envi, /restore_base_save_files
; Initialize ENVI and send all errors ; and warnings to the file batch.txt. envi_batch_init, log_file='batch.txt'
; Open the input file envi_open_file, envi_pickfile(), r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Find the list of available vegetation indices for this file. if (~ENVI_VEG_INDEX_AVAILABLE_INDICES(fid, vi_list=vi_list, $ vi_names=vi_names, vi_type=vi_type, $ error_string=error_string)) then begin print, error_string envi_batch_exit return endif
; Find the subset of indices for greenness to calculate. vi_subset = where(vi_type eq 'Broadband Greenness', count) if (count eq 0) then begin print, 'Error: No broadband greenness indices are available.' envi_batch_exit return endif
; Calculate the greenness indices. envi_doit, 'envi_veg_index_doit', fid=fid, in_memory=0, $ out_name='veg_indices.dat', vi_list=vi_list[vi_subset] envi_batch_exitend
See Also
ENVI_VEG_INDEX_DOIT
ENVI_VEG_INDEX_AVAILABLE_INDICES ENVI Reference Guide
Chapter 2: ENVI Routines 421
ENVI_VEG_INDEX_DOIT
Use this procedure to calculate vegetation indices from a spectral input image. The input spectral data must be atmospherically corrected and calibrated to reflectance.
Syntax
ENVI_DOIT, 'ENVI_VEG_INDEX_DOIT' [, /CROSS_CHECK] [, DIMS=array], FID=file ID [, /IN_MEMORY] [, M_FID=file ID] [, M_POS=value]
[, OUT_NAME=string] [, R_FID=file ID] [, VI_LIST=string]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS (optional)
FID
IN_MEMORY (optional)
M_FID (optional)
M_POS (optional)
OUT_NAME (optional)
R_FID (optional)
CROSS_CHECK (optional)Set this keyword to perform biophysical cross-checking on the output. Biophysical cross-checking performs pixel-by-pixel comparisons between the vegetation indices to determine areas where one index value indicates that another index value has a low probability of validity. The values for any pixel with a low probability of validity are set to the data ignore value. The default is to not perform biophysical cross-checking.
VI_LIST (optional)Use this keyword to indicate which vegetation indices to calculate. Each vegetation index is specified as a numeric index into the array of all available vegetation indices. This list is derived from the VI_LIST values returned from the ENVI_VEG_INDEX_AVAILABLE_INDICES function. The default is to calculate all available vegetation indices. If any indices are requested that cannot be calculated on the input dataset, only the available requested indices will be calculated, unless you are in an interactive ENVI session, in which case you are prompted if the valid selected indices should be calculated.
Example
The following is example code to calculate all available VIs.
pro example_veg_index_1
ENVI Reference Guide ENVI_VEG_INDEX_DOIT
422 Chapter 2: ENVI Routines
compile_opt strictarr ; This example calculates all available vegetation indices on an ; input file. ; First, restore all the base save files. envi, /restore_base_save_files
; Initialize ENVI and send all errors ; and warnings to the file batch.txt. envi_batch_init, log_file='batch.txt'
; Open the input file. envi_open_file, envi_pickfile(), r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
; Calculate the vegetation indices with ; biophysical cross checking enabled to help validate the results envi_doit, 'envi_veg_index_doit', fid=fid, in_memory=0, $ out_name='veg_indices.dat', /cross_check envi_batch_exitend
See Also
ENVI_VEG_INDEX_AVAILABLE_INDICES
ENVI_VEG_INDEX_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 423
ENVI_VEG_SUPPRESS_DOIT
Use this procedure to remove the vegetation spectral signature from multispectral and hyperspectral imagery, using information from red and near-infrared (NIR) bands. The algorithm models the amount of vegetation per pixel using a vegetation transform. The model calculates the relationship of each input band with vegetation, then it decorrelates the vegetative component of the total signal on a pixel-by-pixel basis for each band. You can use the results of vegetation suppression for qualitative analysis, but not for subsequent spectral analysis.
Syntax
ENVI_DOIT, 'ENVI_VEG_SUPPRESS_DOIT' [, DIMS=array], FID=file ID [, /IN_MEMORY] [, NIR_POS=integer] [, OUT_NAME=string], POS=array [, R_FID=file ID] [, RED_POS=integer]
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS (optional)
FID
IN_MEMORY (optional)
OUT_NAME (optional)
POS
R_FID (optional)
NIR_POS (optional)Set this keyword to an integer value representing the band index to use for the NIR band when the image does not contain wavelength information. If the image contains wavelength information, ENVI returns the NIR band chosen for processing. If you supply this keyword, you must also supply RED_POS. Specify bands starting with zero (Band 1=0, Band 2=1, etc.)
RED_POS (optional)Set this keyword to an integer value representing the band index to use for the red band when the image does not contain wavelength information. If the image contains wavelength information, ENVI returns the red band chosen for processing. If you supply this keyword, you must also supply NIR_POS. Specify bands starting with zero (Band 1=0, Band 2=1, etc.)
Example
The following example code performs vegetation suppression on a multispectral file that contains wavelength information.
pro example_veg_suppresscompile_opt strictarr
ENVI Reference Guide ENVI_VEG_SUPPRESS_DOIT
424 Chapter 2: ENVI Routines
; This example suppresses the spectral signature of vegetation in a ; multispectral file that does not contain wavelength information. ; First, restore all the base save files. envi, /restore_base_save_files
; Initialize ENVI and send all errors ; and warnings to the file batch.txt. envi_batch_init, log_file='batch.txt'
; Open the input file. envi_open_file, envi_pickfile(), r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
envi_file_query, fid, nb=nbpos=lindgen(nb)
; Perform vegetation suppression envi_doit, 'envi_veg_suppress_doit', fid=fid, pos=pos, $ out_name='veg_suppress.dat' envi_batch_exitend
ENVI_VEG_SUPPRESS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 425
ENVI_WRITE_COSMOSKYMED_METADATA
Use this procedure to write the metadata from a COSMO-SkyMed data file to XML format.
Syntax
ENVI_WRITE_COSMOSKYMED_METADATA, FID, Filename
Arguments
FID
Specify the file ID of the COSMO-SkyMed data file that has been previously opened. ENVI supports the following COSMO-SkyMed products; all are in HDF5 format:
• Level-1A Single look, complex, slant range (SCS)
• Level-1B Detected Ground Multilook (DGM)
• Level-1C Geocoded Ellipsoid Corrected (GEC)
Filename
Specify the name of the output XML file.
ENVI Reference Guide ENVI_WRITE_COSMOSKYMED_METADATA
426 Chapter 2: ENVI Routines
ENVI_WRITE_DBF_FILE
Use this procedure to write a DBF attribute file for an EVF. Attributes are used to describe each record in an EVF. There must be a one-to-one correspondence between the number of EVF records (points, polylines, and polygons) and the number of DBF records. The fields in an attribute record are a mix of numbers (byte, integer, long, and floating point) and strings. All attribute records in a single DBF file must have the same field structure (an array of identical structures).
Syntax
ENVI_WRITE_DBF_FILE, Filename, Attributes
Arguments
Filename
This is a string value that specifies the output DBF filename. For ENVI to recognize the attribute table when reading the EVF file, the filename should consist of the EVF root name with a “.DBF” extension.
Attributes
The attributes are defined using an IDL anonymous structure variable. Each attribute is a field within the structure. The structure tag names are used as the attribute field names (the maximum field name length is 11 characters). There can be any number of attribute fields comprised of numbers (byte, integer, long, and floating point) and strings. Replicate the structure into an array with the same number of elements as there are records in the corresponding EVF file.
Example
See the Example section under ENVI_EVF_DEFINE_ADD_RECORD.
See Also
ENVI_EVF_CLOSEENVI_EVF_DEFINE_ADD_RECORDENVI_EVF_DEFINE_CLOSEENVI_EVF_DEFINE_INIT
ENVI_WRITE_DBF_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 427
ENVI_WRITE_ENVI_FILE
Use this procedure to convert an IDL image array in memory to an ENVI image. The input data are dimensioned as either BSQ [samples, lines, bands], BIL [samples, bands, lines] or BIP [bands, samples, lines]. The resulting ENVI image can either be stored as a disk file with an associated header file or stored in memory.
Syntax
ENVI_WRITE_ENVI_FILE, Data [, BBL=array] [, BNAMES=string array] [, BYTE_ORDER=variable] [, CLASS_NAMES=string array] [, /COMPRESSION], DATA_TYPE={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15} [, DEF_BANDS=array] [, DEF_STRETCH=value] [, DESCRIP=string] [, FILE_TYPE=variable] [, FUNC_COMPLEX={0 | 1 | 2 | 3 | 4}] [, FWHM=array] [, GEO_POINTS=array] [, /IN_MEMORY] [, INFO=value] [, INHERIT=value] [, INTERLEAVE={0 | 1 | 2}] [, LOOKUP=array] [, MAP_INFO=structure], NB=integer, NL=integer, NS=integer [, NUM_CLASSES=integer] [, /NO_COPY] [, /NO_OPEN] [, /NO_WRITE], OFFSET=value [, OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}], OUT_NAME=variable [, PIXEL_SIZE=array] [, R_FID=variable] [, READ_PROCEDURE=variable] [, SENSOR_TYPE=integer] [, SPEC_NAMES=variable] [, UNITS=integer] [, WAVELENGTH_UNITS={0L | 1L}] [, WL=array] [, XSTART=integer] [, YSTART=integer] [, ZPLOT_AVERAGE=array] [, ZPLOT_TITLES=string array] [, ZRANGE=array]
Arguments
Data
This is a 2D or 3D data array of type byte, integer, unsigned integer, long integer, unsigned long integer, long 64-bit integer, unsigned long 64-bit integer, floating-point, double-precision, complex, or double-precision complex. The data may be in BSQ, BIL, or BIP storage order. The DATA array will be converted to an ENVI image file.
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
IN_MEMORY (optional)
OUT_NAME
R_FID (optional)
BBL (optional)
Use this keyword to specify an array of ones and zeros representing the good and bad bands, respectively. The number of elements in BBL must be equal to the number of bands in the image.
BNAMES (optional)
ENVI Reference Guide ENVI_WRITE_ENVI_FILE
428 Chapter 2: ENVI Routines
Use this keyword to specify the band names assigned to the data. BNAMES is a string array of size num_bands with band names. The default band names are [band 1, band 2, etc.]
BYTE_ORDER (optional)Use this keyword to specify a variable that contains a flag indicating the byte order of the data. Set BYTE_ORDER to a value of 1 for big-endian data (generated on SUN, SGI, and PowerMac platforms) or to a value of 0 for little-endian data (generated on PC x86). The default value is the byte order of your platform.
CLASS_NAMES (optional)Use this keyword to specify a string array of class names for classification images. The first element (Class 0) is “Unclassified.” Only use CLASS_NAMES if the result is a classification image, in which case this keyword is required. If the result is not a classification image, this keyword is optional.
COMPRESSION (optional)Set this keyword to write the file using the standard GZIP format. IDL’s GZIP support is based on the freely available ZLIB library by Mark Adler and Jean-loup Gailly (see www.zlib.org for details). This means that IDL’s compressed files are 100% compatible with the widely available gzip and gunzip programs.
DATA_TYPE
Use this keyword to specify the IDL data type of the file, using the following IDL convention:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
DEF_BANDS (optional)Set this keyword to a one- or three-element array specifying which bands to display upon opening the file in ENVI. If you set DEF_BANDS to a one-element array, ENVI loads a grayscale image in the display group. If you set DEF_BANDS to a three-element array, ENVI loads an RGB image in the display group. The values are zero-based. To load bands 4, 3, and 2 of a 7-band image, set DEF_BANDS to [3, 2, 1].
DEF_STRETCH (optional)
ENVI_WRITE_ENVI_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 429
Use this keyword to specify the default contrast stretch to use whenever the image is displayed. Set DEF_STRETCH equal to the value returned from ENVI_DEFAULT_STRETCH_CREATE.
DESCRIP (optional)Use this keyword to specify a text description of the data or of the type of processing performed.
FILE_TYPE (optional)Use this keyword to specify a named variable that contains the integer file type value. See ENVI_FILE_TYPE for details on how to determine this value.
FUNC_COMPLEX (optional)Set this keyword to one of the following values to specify the complex lookup function that determines how to display complex data.
• 0: Power (default): The natural log of the magnitude
• 1: Magnitude:
• 2: Real: The real portion of the complex number
• 3: Imaginary: The imaginary part of the complex number
• 4: Phase:
NoteOnly set this keyword if the IDL data type of the image is complex or double-precision complex.
FWHM (optional) Use this keyword to specify an array of full-width-half-maximum responses for each band. The number of elements in this array is equal to the number of bands in the image.
GEO_POINTS (optional)Use this keyword to specify a 16-element array of double-precision, floating-point values representing geographic coordinates for the upper-left, upper-right, lower-left, and lower-right corners of the image. The array consists of four groups of x and y pixel locations and their corresponding latitude and longitude values with the form [x, y, lat, lon]. South latitudes and west longitudes have negative values. The array is defined as follows:
• GEO_POINTS[0:3]: Upper left
• GEO_POINTS[4:7]: Upper right
• GEO_POINTS[8:11]: Lower left
• GEO_POINTS[12:15]: Lower right
INFO (optional)Use this keyword to store information to pass to your spatial and spectral readers. INFO is retrieved from ENVI_FILE_QUERY using the keyword H_INFO, which is a handle to the data. Use HANDLE_VALUE and the handle H_INFO to retrieve the data for INFO.
real 2 inaryimag 2+
arc inaryimagreal
--------------------------tan
ENVI Reference Guide ENVI_WRITE_ENVI_FILE
430 Chapter 2: ENVI Routines
INHERIT (optional)Use this keyword to specify the file inheritance. Set INHERIT equal to the value returned from ENVI_SET_INHERITANCE.
INTERLEAVE (optional)Set this keyword to one of the following integer values to specify the interleave output:
• 0: BSQ
• 1: BIL
• 2: BIP
LOOKUP (optional)Use this keyword to specify an array of long integers representing class RGB values. The LOOKUP array contains an RGB triplet for each class specified by the keyword NUM_CLASSES. The dimensions of the array are [3, num_classes+1], and the RGB triplet is ordered [r, g , b]. You must set LOOKUP when entering a classification image.
MAP_INFO (optional)Use this keyword to specify map information. Set MAP_INFO equal to the structure returned from ENVI_MAP_INFO_CREATE.
NB
Use this keyword to specify the number of bands in the file.
NL
Use this keyword to specify a the number of lines in the file.
NS
Use this keyword to specify the number of samples in the file.
NUM_CLASSES (optional)Use this keyword to specify the number of classes for classification files. Remember to include Class 0 (“Unclassified”) in the number of classes. You should only use this keyword for classification files.
NO_COPY (optional)Set this keyword to prohibit duplicating the Data array on output. If you set this keyword, the Data argument array is incorporated into the ENVI session directly, rendering the variable Data undefined after the call to ENVI_WRITE_ENVI_FILE. The default is to make a copy of the data.
NO_OPEN (optional)Set this keyword to prohibit adding the output file to the Available Bands List. The default is to add the output file to this list.
NO_WRITE (optional)
ENVI_WRITE_ENVI_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 431
Set this keyword to prohibit writing an output header file to disk. The default is to write an output header. It is valid to add a file to the Available Bands List and not write the header file to disk. If you set the NO_WRITE keyword, you have to manually specify the file parameters when you open the file in a later ENVI session. The keyword has no effect when you set the keyword IN_MEMORY.
OFFSET
Use this keyword to specify the offset (in bytes) to the start of the data in the file.
OUT_DT (optional)This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values. The default output data type is the same as the input data type.
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
PIXEL_SIZE (optional)Use this keyword to specify the pixel size of images that are not georeferenced. PIXEL_SIZE is a two-element array of floating-point values specifying the x and y pixel sizes, respectively.
READ_PROCEDURE (optional)Use this keyword to specify a named variable that contains a string array of the procedure names for the spatial and spectral readers, respectively.
SENSOR_TYPE (optional)Use this keyword to specify an integer value related to the sensor type. See ENVI_SENSOR_TYPE for details on how to determine the integer sensor type value.
SPEC_NAMES (optional)Use this keyword to specify a named variable that contains a string array of spectral library names. Only set this keyword for a spectral library file.
UNITS (optional)Use this keyword to specify the PIXEL_SIZE units for images that are not georeferenced. UNITS is an integer value returned from ENVI_TRANSLATE_PROJECTION_UNITS.
ENVI Reference Guide ENVI_WRITE_ENVI_FILE
432 Chapter 2: ENVI Routines
Georeferenced images do not use this value. Instead, they use the pixel size and units contained in the map information structure.
WAVELENGTH_UNITS (optional)Use this keyword to specify the wavelength units. Set to 0L for micrometers, or set to 1L for nanometers.
WL (optional)Use this keyword to specify an array of wavelength values. The number of elements in this array is equal to the number of bands.
XSTART (optional)Use this keyword to specify the x starting sample for the first pixel in the file. The default value is 0. Use XSTART in conjunction with YSTART to preserve the location within the original file for subsetted files. When processing a file, you typically set the XSTART of the output file to the XSTART of the input file, plus the value of DIMS[1] (the starting sample).
YSTART (optional)Use this keyword to specify the y starting line for the first pixel in the file. The default value is 0. Use YSTART in conjunction with XSTART to preserve the spatial reference for subsetted files. When processing a file, you typically set the YSTART of the output file to the YSTART of the input file, plus the value of DIMS[3] (the starting line).
ZPLOT_AVERAGE (optional)Use this keyword to specify a two-element array of long integers for the x and y window size (in pixels) for the Z Profile. The window size must be 1 or greater. The Z Profile is formed from the average of the profiles within the specified window. The default window size is [1, 1].
ZPLOT_TITLES (optional)Use this keyword to specify a two-element string array for x- and y-axis titles for any spectral plots derived from the image. The default x-axis title is “Band Number” for images with no wavelength information and “Wavelength” for images with wavelength information. The default y-axis title is “Value.”
ZRANGE (optional)Use this keyword to specify a 2D array for the lower and upper spectral plot range.
Examples
The following example generates a 256 x 256, three-band, BSQ, byte ramp image using the function BINDGEN. You will save this image to disk using the filename test.img, and the image will be automatically added to the Available Bands List.
; Create the image array;data = BINDGEN(256,256,3);; Open the output file and write; the image to disk
ENVI_WRITE_ENVI_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 433
;ENVI_WRITE_ENVI_FILE, data, out_name=’test.img’
The following example creates two classes (plus the “Unclassified” class) from the ramp image and enters the resulting classification image into ENVI. The “Unclassified” class is black [0, 0, 0], the first class is red [255, 0, 0], and the second class is yellow [255, 255, 0]. The classification image has the description “Example Classification Image” and the band name “Ramp Classification.”
; Create a 2D ramp and then classify all values ; from 20 to 100 in the first class (classification ; data value equal to one) and classify all values ; from 101 to 220 into the second class ; (classification data value equal to two);data = BINDGEN(256,256)class = BYTE((data ge 20 and data le 100) + $ 2B * (data ge 101 and data le 220));; Create the classification information;class_names = ['Unclassified','Red','Yellow']lookup = [[0,0,0],[255,0,0],[255,255,0]]bnames = ['Ramp Classification']descrip = 'Example Classification Image'file_type = ENVI_FILE_TYPE('ENVI Classification');; Save the classification image to disk;ENVI_WRITE_ENVI_FILE, class, out_name=’test.img’, num_classes=3, class_names=class_names, $ lookup=lookup, file_type=file_type, $ bnames=bnames, descrip=descrip
The following example assigns a geographic projection to the ramp image with the upper-left corner at 15 degrees south, 48 degrees west, with an x and y pixel size of one arc second. The map projection is created using ENVI_MAP_INFO_CREATE, and the resulting structure uses the MAP_INFO keyword when the data are entered into ENVI.
;; First create the ramp image. The ramp image ; would actually be replaced by a real ; georeferenced image.;data = BINDGEN(256,256);; Create the items used for the projection;mc = [.5D,.5, -48,-15]ps = [1D/3600, 1D/3600]units = ENVI_TRANSLATE_PROJECTION_UNITS('Degrees')map_info = ENVI_MAP_INFO_CREATE(/geographic, $ mc=mc, ps=ps, units=units);; Enter the data into ENVI ;;ENVI_WRITE_ENVI_FILE, data, out_name=’test.img’, $ map_info=map_info
ENVI Reference Guide ENVI_WRITE_ENVI_FILE
434 Chapter 2: ENVI Routines
See Also
ENVI_ENTER_DATAENVI_SETUP_HEAD
ENVI_WRITE_ENVI_FILE ENVI Reference Guide
Chapter 2: ENVI Routines 435
ENVI_WRITE_FILE_HEADER
Use this procedure to write or re-write an ENVI header file to preserve changes to user-defined header values. Once you open an ENVI file, you can programmatically change your header values using ENVI_ASSIGN_HEADER_VALUE. To preserve these changes to files that reside on disk, you must also write the updated ENVI header using ENVI_WRITE_FILE_HEADER.
Syntax
ENVI_WRITE_FILE_HEADER, FID
Arguments
FID
This is the file ID for the open file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
Example
The following example opens the image file can_tmr.img using the ENVI_OPEN_FILE procedure. Once you open the file and a valid file ID is returned, store a user-defined header value for “My Scale Factors” to the header using ENVI_ASSIGN_HEADER_VALUE. Query the change using ENVI_GET_HEADER_VALUE and print the result to the ENVI log window. At this point, the header change exists only in the current ENVI session. In order to preserve this change to the disk file, call the procedure ENVI_WRITE_FILE_HEADER to write an updated header to disk.
envi_open_file, 'can_tmr.img', r_fid=fid
if (fid eq -1) then return
scale_factors = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
envi_assign_header_value, fid=fid, keyword='My Scale Factors', $ value=scale_factors, precision=3
values = envi_get_header_value(fid, 'My Scale Factors')
print, 'My Scale Factors', values
envi_write_file_header, fid
See Also
ENVI_ASSIGN_HEADER_VALUEENVI_GET_HEADER_VALUE
ENVI Reference Guide ENVI_WRITE_FILE_HEADER
436 Chapter 2: ENVI Routines
ENVI_WRITE_STATISTICS
Use this procedure to write statistics data to an ENVI statistics file (.sta).
Syntax
ENVI_WRITE_STATISTICS, Filename [, COV=array] [, CPOS=array] [, DATA_TYPE=value] [, DMAX=array] [, DMIN=array] [, EVAL=array] [, EVEC=array], FID=file ID [, MEAN=array] [, STDV=array]
Arguments
Filename
This is the filename of the ENVI statistics file (.sta) to be written.
Keywords
COV (optional)Set this keyword to specify the covariance for the image. COV is an [nb, nb] array, where nb is defined by CPOS. If you set COV, then you must also set EVAL and EVAC.
CPOS (optional)Use this keyword to specify the array of band indices used to calculate COV, EVAL, and EVEC. The number of elements of CPOS define the nb for COV, EVAL, and EVEC and may be different than the number of bands defined by FID. The default is that COV, EVAL, and EVEC are calculated for all bands in the file defined by FID.
DATA_TYPE (optional)Use this keyword to specify the image data type. This may be different that the data type in the file defined by FID. DATA_TYPE is used during any subsequent display of statistics by ENVI.
DMAX (optional)Use this keyword to specify an array that contains the image maximums. DMAX is an [nb] array, where nb is equal to the number of bands in the file defined by FID.
DMIN (optional)Use this keyword to specify an array that contains the image minimums. DMIN is an [nb] array, where nb is equal to the number of bands in the file defined by FID.
EVAL (optional)Use this keyword to specify the eigenvalues for the image. EVAL is an [nb, nb] array, where nb is defined by CPOS. If you set EVAL, then you must also set COV and EVEC.
EVEC (optional)
ENVI_WRITE_STATISTICS ENVI Reference Guide
Chapter 2: ENVI Routines 437
Use this keyword to specify the eigenvectors for the image. EVEC is a [nb] array, where nb is defined by CPOS. If you set EVEC, then you must also set COV and EVAL.
FID
Use this keyword to specify a file ID for defining the overall number of bands in the statistics calculations. COV, EVAL, and EVEC use CPOS to save statistics for fewer than the total number of bands.
MEAN (optional)Use this keyword to specify an array that contains the image mean. MEAN is a an [nb] array, where nb is equal to the number of bands in the file defined by FID.
STDV (optional)Use this keyword to specify an array that contains the image standard deviation. STDV is an [nb] array, where nb is equal to the number of bands in the file defined by FID.
Example
This example computes the statistics for a file using ENVI_STATS_DOIT and outputs the result to an ENVI statistics file (.sta).
pos = lindgen(nb); Call the doitenvi_stats_doit, fid=fid, pos=pos, dims=dims, $
dmin=dmin, dmax=dmax, mean=mean, stdv=stdv, $comp_flag=0, report_flag=1
; Save the results
envi_write_statistics, 'test.sta', fid=fid, dmin=dmin, dmax=dmax, $mean=mean, stdv=stdv
See Also
ENVI_GET_STATISTICSENVI_STATS_DOIT
ENVI Reference Guide ENVI_WRITE_STATISTICS
438 Chapter 2: ENVI Routines
FFT_DOIT
Use this procedure to perform forward FFT of images.
Syntax
ENVI_DOIT, 'FFT_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
Example
pro example_fft_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; FFT on all samples and bands in ; the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb)
FFT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 439
out_name = 'testfft' ; ; Perform the FFT ; envi_doit, 'fft_doit', $ fid=fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide FFT_DOIT
440 Chapter 2: ENVI Routines
FFT_INV_DOIT
Use this procedure to apply an FFT filter image and perform the inverse FFT.
NoteIf you select a user-defined filter, then it must exist as an ENVI annotation file prior to starting this function.
Syntax
ENVI_DOIT, 'FFT_INV_DOIT', DIMS=array, FID=file ID, FILTER_FID=file ID, FILTER_POS=integer, /IN_MEMORY, OUT_BNAME=string array, OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
FILTER_FID
Use this keyword to specify the file ID of a filter image generated by ENVI_FILTER_DOIT.
FILTER_POS
Use this keyword to specify the band number for the filter image.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
FFT_INV_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 441
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
Example
pro example_fft_inv_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'testfft.img', r_fid=fid envi_open_file, 'testfft.img', r_fid=f_fid if (fid eq -1 or f_fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; inverse FFT on all samples and all ; bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' f_pos = [0] ; ; Perform the FFT ; envi_doit, 'fft_inv_doit', $ fid=fid, pos=pos, dims=dims, $ filter_fid=f_fid, filter_pos=f_pos, $ out_dt=4, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide FFT_INV_DOIT
442 Chapter 2: ENVI Routines
FFT_INV_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 443
GAINOFF_DOIT
Use this procedure to apply a gain and offset to each input band.
Syntax
ENVI_DOIT, 'GAINOFF_DOIT', DIMS=array, FID=file ID, GAIN=array, /IN_MEMORY, OFFSET=array, OUT_DT=integer, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
POS
R_FID
GAIN
Set this keyword to an array of gain values, one for each element in POS.
OFFSET
Set this keyword to an array of offset values, one for each element in POS.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
ENVI Reference Guide GAINOFF_DOIT
444 Chapter 2: ENVI Routines
• 15: Unsigned long 64-bit integer
Example
pro example_gainoff_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; gain and offset correction on all ; samples and all bands in the file. ; envi_file_query, fid, nb=nb pos = lindgen(nb) out_name = 'testimg' gain = [2.00, 1.33, 1.20, $ 1.11, 2.60, 3.12] offset = [12.33, 1.10, 6.00, $ 1.55, 5.32, 4.05] ; ; Call gainoff_doit ; envi_doit, 'gainoff_doit', $ fid=fid, pos=pos, dims=dims, $ gain=gain, offset=offset, $ out_dt=4, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
GAINOFF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 445
GEN_IMAGE_DOIT
Use this procedure to generate test images.
Syntax
ENVI_DOIT, 'GEN_IMAGE_DOIT', DATA_TYPE=value, /IN_MEMORY, MAX_VAL=value, MEAN=value, METHOD={0 | 1 | 2 | 3 | 4 | 5}, MIN_VAL=value, NB=integer, NL=integer, NS=integer, OUT_NAME=string, R_FID=variable [, SEED=value], SIGMA=value, VAL=value
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
IN_MEMORY
OUT_NAME
R_FID
DATA_TYPE
Use this keyword to specify the IDL data type of the file, using the following IDL convention.
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
MAX_VAL
Use this keyword to specify the maximum value when METHOD=1, 2, 3 or 5.
MEAN
Use this keyword to specify the mean value when METHOD=4.
ENVI Reference Guide GEN_IMAGE_DOIT
446 Chapter 2: ENVI Routines
METHOD
Set this keyword to one of the following values to specify which type of test image to generate.
• 0: Constant
• 1: Horizontal ramp
• 2: Vertical ramp
• 3: Random noise (uniform)
• 4: Random noise (normal)
• 5: Gaussian point spread function
MIN_VAL
Use this keyword to specify the minimum value when METHOD=1, 2, 3 or 5.
NB
Use this keyword to specify the number of bands in the output image.
NL
Use this keyword to specify the number of lines in the output image.
NS
Use this keyword to specify the number of samples in the output image.
SEED (optional)Use this keyword to specify a random number seed when METHOD=3 or 4.
SIGMA
Use this keyword to specify the Gaussian sigma value when METHOD=4 or 5. For METHOD=5, +/- one sigma is equal to the number of samples.
VAL
Use this keyword to specify the constant value for constant images.
Example
pro example_gen_image_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ;
GEN_IMAGE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 447
; Set the keywords. ; ns = 512L nl = 512L nb = 1 method = 3 min_val = 0 max_val = 1024 data_type = 2 out_name = 'testimg' ; ; Generate the test image ; envi_doit, 'gen_image_doit', $ ns=ns, nl=nl, nb=nb, method=method, $ min_val=min_val, max_val=max_val, $ data_type=data_type, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide GEN_IMAGE_DOIT
448 Chapter 2: ENVI Routines
HANDLE_VALUE
This procedure returns or sets the value of an existing handle.
Syntax
HANDLE_VALUE, ID, Value, /NO_COPY, /SET
Arguments
ID
Specify a valid handle ID.
Value
When using HANDLE_VALUE to return an existing handle value (the default), Value is a named variable in which the value is returned.
When using HANDLE_VALUE to set a handle value, Value is the new value. Note that handle values can have any IDL data type and organization.
Keywords
NO_COPY
By default, HANDLE_VALUE works by making a second copy of the source data. Although this technique is fine for small data, it can have a significant memory cost when the data being copied are large.
If you set this keyword, HANDLE_VALUE works differently. Rather than copy the source data, it takes the data away from the source and attaches them directly to the destination. This feature can be used to move data very efficiently. However, it can cause the source variable to become undefined. On a retrieve operation, the handle value becomes undefined. On a set operation, the variable passed as Value becomes undefined.
SET
Set this keyword to assign Value as the new handle value. The default is to retrieve the current handle value.
Example
The following commands demonstrate the two different uses of HANDLE_VALUE:
; Retrieve the value of handle1 into the variable current.HANDLE_VALUE, handle1, current; Set the value of handle1 to a 2-element integer vector.HANDLE_VALUE,handle1,[2,3],/SET
HANDLE_VALUE ENVI Reference Guide
Chapter 2: ENVI Routines 449
HIST_EXPORT_DOIT
Use this procedure to output an image using a supplied LUT. An LUT is a method of changing an input image DN to new output DN. Each input pixel is used to calculate the index into the LUT, and the corresponding value in the LUT becomes the new output value. The index into the LUT is calculated from the input data value, the input data minimum (I_MIN), and the input binsize (I_BINSIZE) by the following formula:
Output value = LUT[(input value - I_MIN) / I_BINSIZE]
Additionally, you can adjust the output DNs by the desired output minimum and maximum, using the keywords O_MIN and O_MAX, respectively.
Syntax
ENVI_DOIT, 'HIST_EXPORT_DOIT', DIMS=array, FID=file ID, I_BINSIZE=value, I_MIN=value [, /IN_MEMORY], LUT=array, O_MAX=value, O_MIN=value [, OUT_BNAME=string array], OUT_DT={0 | 1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}, OUT_NAME=string, POS=array [, R_FID=variable]
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
POS
R_FID (optional)
I_BINSIZE
Use this keyword to specify the input bin size, which is the width in DN that a group of input pixels will map to a single output pixel. For integer data, I_BINSIZE must be an integer greater than or equal to 1; for floating point data, I_BINSIZE must be greater than 0.
I_MIN
Use this keyword to specify the input data minimum.
ENVI Reference Guide HIST_EXPORT_DOIT
450 Chapter 2: ENVI Routines
LUT
Use this keyword to specify the lookup table array. The number of elements of LUT is determined by the input data range and the input bin size (I_BINSIZE) using the following formula:
# elements lut = (input data maximum - input data minimum) / I_BINSIZE + 1
O_MAX
Use this keyword to specify the desired output data maximum. O_MAX is a single value with the same data type as OUT_DT.
O_MIN
Use this keyword to specify the desired output data minimum. O_MIN is a single value with the same data type as OUT_DT.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
Example
This example calculates a new byte image using a square-root LUT. This example uses the following files found in the IDLxx\products\envixx\data directory of the ENVI installation (where xx is the software version number):
• bhtmref.img
• bhtmref.hdr
Since these are byte data and you do not want to change the dynamic range of the input data, set the data minimum to 0 and the data maximum to 255. Use a binsize of 1, allowing each input pixel to map to its square-root value. The LUT must have 256 entries, and the value of each entry is the square root of the index.
HIST_EXPORT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 451
pro example_hist_export_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Setup the keywords to the ; processing routine ; envi_file_query, fid, dims=dims, $ data_type=out_dt out_name = 'testimg' pos = [0] ; ; Since we are converting byte data ; and do not wish to change the range ; of the input data we will set the ; data mins to 0 and the max to 255. ; An input binsize of one is used ; to map each input pixel to a ; output value. ; o_min = 0 o_max = 255 i_min = 0 i_binsize = 1 lut = sqrt(lindgen(256)) ; ; Call the doit ; envi_doit,'hist_export_doit', fid=fid, $ pos=pos, dims=dims, out_name=out_name, $ out_dt=out_dt, i_min=i_min, o_min=o_min, $ o_max=o_max, lut=lut, i_binsize=i_binsize, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide HIST_EXPORT_DOIT
452 Chapter 2: ENVI Routines
MAGIC_MEM_CHECK
MAGIC_MEM_CHECK is a memory management function. It should always be called before the processing function. It returns a structure containing the tags IN_MEMORY and OUT_NAME, which are then passed to the processing function (_DOIT).
Syntax
Result = MAGIC_MEM_CHECK(DIMS=array, FID=file ID, /IN_MEMORY, OUT_NAME=value, OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}, NB=integer)
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
NB
Use this keyword to specify the number of bands in the output image.
MAGIC_MEM_CHECK ENVI Reference Guide
Chapter 2: ENVI Routines 453
Example
After obtaining the processing parameters, call MAGIC_MEM_CHECK to ensure that in-memory items do not exceed the total cache size. After calling MAGIC_MEM_CHECK, use the values stored in M_RES.IN_MEMORY and M_RES.OUT_NAME for the in-memory processing flag or the output filename. if M_RES.CANCEL is set, then you have canceled the operation.
m_res=magic_mem_check(fid=fid,dims=dims, out_dt=1,$nb=n_elements(pos), out_name=result.outf.name,$in_memory=result.outf.in_memory)
if (m_res.cancel) then returnin_memory = m_res.in_memoryout_name = m_res.out_name
ENVI Reference Guide MAGIC_MEM_CHECK
454 Chapter 2: ENVI Routines
MATCH_FILTER_DOIT
Use this procedure to perform Matched Filtering (MF).
To model the scene background, run ENVI_SUBSPACE_BACKGROUND_STATS_DOIT prior to MATCH_FILTER_DOIT. Modeling the scene background can potentially improve the results, particularly in a scene that has a lot of clutter or man-made objects.
Syntax
ENVI_DOIT, 'MATCH_FILTER_DOIT', COV=value, DIMS=array, ENDMEM=array, FID=file ID, /IN_MEMORY, M_FID=file ID, M_POS=long integer, MEAN=value, O_MAX=value, O_MIN=value, OUT_BNAME=string array, OUT_DT={1 | 4}, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY
M_FID
M_POS
OUT_BNAME
OUT_NAME
POS
R_FID
COV
Use this keyword to specify the input data covariance matrix. Typically this is the covariance of the data with the optional mask applied.
ENDMEM
Use this keyword to specify the endmembers array. ENDMEM is a floating-point array of size [nb, # endmembers].
MEAN
Use this keyword to specify the input data mean. Typically, this is the mean of the data with the optional mask applied.
MATCH_FILTER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 455
O_MAX
Use this keyword to specify the output data maximum to use for conversion to byte. Only use O_MAX when OUT_DT=1 (byte).
O_MIN
Use this keyword to specify the output data minimum to use for conversion to byte. Only use O_MIN when OUT_DT=1 (byte).
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 4: Floating-point (32 bits)
Example
pro example_match_filter_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'mof94av.bil', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword ; to process all spectral data. ; Output the result to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for MF. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. ; envi_read_cols, 'm94_em.asc', $
ENVI Reference Guide MATCH_FILTER_DOIT
456 Chapter 2: ENVI Routines
endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = em_names[2:*] ; ; Calculate the covariance of the ; input data file. ; envi_doit, 'envi_stats_doit', $ fid=fid, pos=pos, dims=dims, $ mean=mean, cov=cov, comp_flag=5 ; ; Call the match filter processing ; routine. ; envi_doit,'match_filter_doit', $ fid=fid, pos=pos, dims=dims, $ mean=mean, cov=cov, endmem=endmem, $ out_dt=4, out_name=out_name, $ out_bname=out_bname, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_SUBSPACE_BACKGROUND_STATS_DOIT
MATCH_FILTER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 457
MATCH_FILTER_MT_DOIT
Use this procedure to perform Mixture Tuned Matched Filtering (MTMF). Compute both the normal Matched Filter (MF) as well as the MTMF infeasibility answer for each endmember.
To model the scene background, run ENVI_SUBSPACE_BACKGROUND_STATS_DOIT prior to MATCH_FILTER_DOIT. Modeling the scene background can potentially improve the results, particularly in a scene that has a lot of clutter or man-made objects.
Syntax
ENVI_DOIT, 'MATCH_FILTER_MT_DOIT', COV=value, DIMS=array, ENDMEM=array, EVAL=value, FID=file ID, /IN_MEMORY, M_FID=file ID, M_POS=long integer, MEAN=value, O_MAX=value, O_MIN=value, OUT_BNAME=string array, OUT_DT={1 | 4}, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY
M_FID
M_POS
OUT_BNAME
OUT_NAME
POS
R_FID
COV
Use this keyword to specify the input data covariance matrix. Typically this is the covariance of the data with the optional mask applied.
ENDMEM
Use this keyword to specify the endmembers array. ENDMEM is a floating-point array of size [nb, # endmembers].
EVAL
Use this keyword to specify the input data eigenvalues. Typically, you apply an optional mask.
ENVI Reference Guide MATCH_FILTER_MT_DOIT
458 Chapter 2: ENVI Routines
MEAN
Use this keyword to specify the input data mean. Typically, you apply an optional mask.
O_MAX
Use this keyword to specify the output data maximum to use for conversion to byte. Only use O_MAX when OUT_DT=1 (byte).
O_MIN
Use this keyword to specify the output data minimum to use for conversion to byte. Only use O_MIN when OUT_DT=1 (byte).
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 4: Floating-point (32 bits)
Example
pro example_match_filter_mt_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'mof94av.bil', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for MTFM.
MATCH_FILTER_MT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 459
; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. ; envi_read_cols, 'm94_em.asc', $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = [$ 'MF Score (' + em_names[2:*] + ')', $ 'Infeasibility (' + em_names[2:*] + ')'] ; ; Calculate the statistics for the ; input data file. ; envi_doit, 'envi_stats_doit', $ fid=fid, pos=pos, dims=dims, $ mean=mean, cov=cov, eval=eval, $ evec=evec, comp_flag=5 ; ; Call the match filter processing ; routine. ; envi_doit,'match_filter_mt_doit', $ fid=fid, pos=pos, dims=dims, $ mean=mean, cov=cov, eval=eval, $ evec=evec, endmem=endmem, $ out_dt=4, out_name=out_name, $ out_bname=out_bname, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_SUBSPACE_BACKGROUND_STATS_DOIT
ENVI Reference Guide MATCH_FILTER_MT_DOIT
460 Chapter 2: ENVI Routines
MATH_DOIT
Use this procedure to perform Band Math on image data.
Syntax
ENVI_DOIT, 'MATH_DOIT', DIMS=array, EXP=string, FID=array, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
EXP
Use this keyword to specify the mathematical expression to perform. EXP is a string variable. Some valid ENVI math expressions are:
EXP = 'b1+b1'EXP = 'byte ((float(b1)+float(b2))<255)'EXP = 'byte(((float(b1)+float(b2)+float(b3))/3.0)'EXP = '(sin(b1)^2+cos(b2))*tan(b3)'EXP = 'b1 and b2'EXP = 'b1 xor b2'
FID
Use this keyword to specify an array of long integers representing file IDs, one for each of the bands in EXP.
Example
pro example_math_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt'
MATH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 461
; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; band math on all samples in the file. ; envi_file_query, fid, dims=dims t_fid = [fid,fid] pos = [0,1] exp = 'b1 + b2' out_name = 'testimg' ; ; Perform the band math processing ; envi_doit, 'math_doit', $ fid=t_fid, pos=pos, dims=dims, $ exp=exp, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide MATH_DOIT
462 Chapter 2: ENVI Routines
MNF_DOIT
Use this procedure to perform a Minimum Noise Fraction (MNF) transform.
Syntax
ENVI_DOIT, 'MNF_DOIT', DIMS=array, FID=file ID, /IN_MEMORY [, /NO_PLOT], NOISE_EVAL=value, NOISE_EVEC=value, NOISE_STA_NAME=string, OUT_BNAME=string array, OUT_NAME=string [, OUT_NB=long integer], POS=array [, /QUERY], R_FID=variable, SD_DIMS=array, /SHIFT_DIFF, STA_NAME=string
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
NO_PLOT (optional)Set this keyword to disable the resulting principal components eigenvalue plot.
NOISE_EVEC
Use this keyword to specify the noise eigenvectors. You do not need NOISE_EVEC if you set the keyword SHIFT_DIFF.
NOISE_EVAL
Use this keyword to specify the noise eigenvalues. You do not need NOISE_EVAL if you set the keyword SHIFT_DIFF.
NOISE_STA_NAME
Use this keyword to specify the noise statistics file.
OUT_NB (optional)Use this keyword to specify the number of output bands in the MNF image. OUT_NB is a long integer ranging from 1 to the number of elements of POS. The default is to use the number of bands specified by POS.
MNF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 463
QUERY (optional)Set this keyword to interactively select the number of output bands from the eigenvalues.
SD_DIMS
Use this keyword to specify the spatial dimensions for the shift differencing operation. You only need to set SD_DIMS if you set SHIFT_DIFF. SD_DIMS is a five-element array of long integers with the following definitions:
• SD_DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• SD_DIMS[1]: The starting sample number. The first x pixel is 0.
• SD_DIMS[2]: The ending sample number
• SD_DIMS[3]: The starting line number. The first y pixel is 0.
• SD_DIMS[4]: The ending line number
SHIFT_DIFF
Set this keyword to compute noise statistics by shift differencing.
STA_NAME
Use this keyword to specify the statistics filename.
Example
pro example_mnf_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords DIMS and POS to ; process all spatial and all spectral ; data. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Call the MNF processing routine
ENVI Reference Guide MNF_DOIT
464 Chapter 2: ENVI Routines
; use the shift difference method ; to calculate the noise statistics. ; Output the result to a disk file, ; set the statistics file to a null ; file and do not plot the eigenvalues. ; envi_doit, 'mnf_doit', $ fid=fid, pos=pos, dims=dims, $ sd_dims=dims, out_name=out_name, $ in_memory=0, sta_name='', /no_plot, $ shift_diff=1, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
MNF_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 465
MNF_INV_DOIT
Use this procedure to perform an inverse Minimum Noise Fraction (MNF) transform. To use the MNF as a filter, first perform a forward MNF without reducing the output number of bands. Next, perform the inverse MNF and specify only the number of bands to include in the inverse using the POS keyword.
Syntax
ENVI_DOIT, 'MNF_INV_DOIT’, DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_DT=value, OUT_NAME=string, POS=array, R_FID=variable, STA_NAME=string
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 4: Floating-point (32 bits)
STA_NAME
Use this keyword to specify the forward MNF statistics filename. The number of bands output from the inverse MNF is based on the number of bands in the STA_NAME statistics file.
See Also
MNF_DOIT
ENVI Reference Guide MNF_INV_DOIT
466 Chapter 2: ENVI Routines
MORPH_DOIT
Use this procedure to perform morphological filtering including dilate, erode, open, and close.
Syntax
ENVI_DOIT, 'MORPH_DOIT', CYCLES=integer, DIMS=array, FID=file ID, /GRAY, /IN_MEMORY, KERNEL=value, METHOD={0 | 1 | 2 | 3}, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, VALUE=array
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
CYCLES
Use this integer keyword to specify the number of cycles to perform the morphological operation.
GRAY
Set this keyword to perform gray scale, rather than binary, operations. Non-zero elements of the kernel parameter determine the shape of the structuring element (neighborhood). If VALUES is not present, all elements of the structuring element are 0, yielding the neighborhood minimum operator for the erode method and the maximum operator for dilate method.
KERNEL
Use this keyword to specify a structuring element for the morphological process. The elements are interpreted as binary values, either 0 or 1.
METHOD
Set this keyword to one of the following values to indicate the type of filter to apply:
• 0: Erode
MORPH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 467
• 1: Dilate
• 2: Open
• 3: Close
VALUE
Use this keyword to specify an array of the same dimensions as the kernel providing the values of the structuring element. The presence of this keyword implies gray scale erosion. Each element in the structuring element is either subtracted (eroded) or added (dilated) to the associated pixels. The minimum (erode) or maximum (dilate) is performed.
Example
pro example_morph_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; morphological filtering on all ; samples and all bands in the file. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) kernel = fltarr(5,5) + 1. value = kernel out_name = 'testimg' ; ; Perform the morphological ; opening filter operation ; on the image. ; envi_doit, 'morph_doit', $ fid=fid, pos=pos, dims=dims, $ method=2, gray=1, kernel=kernel, $ value=value, cycles=3, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide MORPH_DOIT
468 Chapter 2: ENVI Routines
MOSAIC_DOIT
Use this procedure to overlay two or more images with overlapping areas (typically georeferenced) or to overlay non-overlapping images (typically pixel-based). You can mosaic individual bands, entire files, and multi-resolution georeferenced images.
Syntax
ENVI_DOIT, 'MOSAIC_DOIT' [, BACKGROUND=integer], DIMS=array, FID=file ID[, /GEOREF] [, /IN_MEMORY] [, MAP_INFO=structure] [, OUT_BNAME=string array], OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}, OUT_NAME=string, PIXEL_SIZE=array, POS=array [, R_FID=variable] [, /SEE_THROUGH_VAL], USE_SEE_THROUGH=array, XSIZE=integer, X0=array, YSIZE=integer, Y0=array
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
IN_MEMORY (optional)
OUT_BNAME (optional)
OUT_NAME
R_FID (optional)
BACKGROUND (optional)Use this keyword to specify the value for all background pixels. The default is 0.
FID
Use this keyword to specify a long-integer array of file IDs, one for each file to mosaic. The file ID is the value returned by the R_FID keyword to the ENVI_OPEN_FILE procedure or the FID keyword to ENVI_SELECT.
GEOREF (optional)Set this keyword to indicate that the data are georeferenced, in which case you must define the keyword MAP_INFO.
MAP_INFO (optional)Use this keyword to specify map information. Set MAP_INFO equal to the structure returned from ENVI_GET_MAP_INFO or ENVI_MAP_INFO_CREATE.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
MOSAIC_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 469
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
PIXEL_SIZE
Use this keyword to specify a two-element array of floating-point or double-precision values containing the x and y pixel sizes, respectively. For pixel-based mosaics, set the x and y pixel sizes to 1.0, for example, PIXEL_SIZE=[1.0, 1.0].
POS
Use this keyword to specify an array of long integers representing band positions to include in the mosaic. The dimensions of the array must be [#output bands, #files]. A value of -1 indicates that no input band for the associated file is included in the corresponding mosaicked output band. The valid values for POS are 0 to num_bands (for the corresponding file), or -1.
SEE_THROUGH_VAL (optional)Use this keyword to set the see-through value for each input file. SEE_THROUGH_VAL is an array of values with the same data type as OUT_DT with [#files] elements. If a pixel in the input file is equal to its corresponding value of SEE_THROUGH_VAL, then that pixel is not transferred to the output mosaic, which allows data stacked underneath to remain visible. If any elements of the array USE_SEE_THROUGH have a value of 1, then you must specify the SEE_THROUGH_VAL array.
USE_SEE_THROUGH
Use this keyword to specify an integer array of zeros and ones indicating whether the bands from the current file will use the corresponding SEE_THROUGH_VAL value. A value of 1 indicates that the input file will use SEE_THROUGH_VAL, and a value of 0 indicates that SEE_THROUGH_VAL will not be used. The number of elements in the USE_SEE_THROUGH array is equal to the number of input files specified by FID.
XSIZE
Use this keyword to set the x size of the output image (sample direction). For pixel-based mosaics, the XSIZE is in pixels and the corresponding pixels size is [1, 1]. For georeferenced images, XSIZE has the same units as PIXEL_SIZE. For example, a 1 km image in the sample direction uses a PIXEL_SIZE of 1 m and an XSIZE of 1,000 m.
ENVI Reference Guide MOSAIC_DOIT
470 Chapter 2: ENVI Routines
X0
Use this keyword to specify an array of long integers representing the x starting pixels, one for each file. X0 is in pixel coordinates and may require you to convert map locations to output pixel locations in georeferenced images.
YSIZE
Use this keyword to set the y size of the output image (line direction). For pixel-based mosaics, the YSIZE is in pixels and the corresponding pixels size is [1, 1]. For georeferenced images, YSIZE has the same units as PIXEL_SIZE. For example, a 1 km image in the line direction uses a PIXEL_SIZE of 1 m and an YSIZE of 1,000 m.
Y0
Use this keyword to specify an array of long integers representing the y starting lines, one for each file. Y0 is in pixel coordinates and may require you to convert map locations to output line locations in georeferenced images.
Example
This example mosaics the first three bands from bhtmref.img and the single band bhdemsub.img side-by-side into the same output image (pixel-based). This example uses the following files found in the DATA directory of the ENVI installation:
• bhtmref.img
• bhtmref.hdr
• bhtdemsub.img
• bhtdemsub.hdr
The single band DEM is only placed into the first output band, while the TM data are placed into all three output bands. The data are positioned with a 20-pixel border around the outside and between each of the images. The actual border area varies because the images are not the same size, and the DEM image is only in the first output band. Use a background value of 255 for the border area. Set the output data type to integer since that is the greater of the two data types. The images are mosaicked side-by-side so no see-through is needed, but for illustration purposes, set see-through to 0 for each of the input files.
pro example_mosaic_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input files ; envi_open_file, 'bhtmref.img', r_fid=tm_fid if (tm_fid eq -1) then begin
MOSAIC_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 471
envi_batch_exit return endif envi_open_file, 'bhdemsub.img', r_fid=dem_fid if (dem_fid eq -1) then begin envi_batch_exit return endif ; ; Build the necessary keywords. We will ; create a new 3 band output image from ; a pixel mosaic of the first three band ; of the TM data and the single band DEM. ; envi_file_query, tm_fid, ns=tm_ns, nl=tm_nl envi_file_query, dem_fid, ns=dem_ns, nl=dem_nl fid = [tm_fid, dem_fid] pos = [[0,1,2],[0,-1,-1]] dims = [[-1,0, tm_ns-1,0, tm_nl-1], $ [-1,0,dem_ns-1,0,dem_nl-1]] out_name = 'testimg' ; ; Determine the placement of the output ; bands. The upper left corner of the ; TM data is at [20,20] and the upper ; lefter corner of the DEM data is [40+tm_ns, 20] ; x0 = [20,40+tm_ns] y0 = [20,20] xsize = tm_ns + dem_ns + 60 ysize = (tm_nl > dem_nl) + 40 pixel_size = [1.,1.] ; ; Although it does not matter (since ; we are placing the files next to each ; other) we will use a see through ; value of zero for each file. ; use_see_through = [1L,1] see_through_val = [0L,0] ; ; Call the doit. Use a background value of ; 255 and set the output data type to ; integer. ; envi_doit, 'mosaic_doit', fid=fid, pos=pos, $ dims=dims, out_name=out_name, xsize=xsize, $ ysize=ysize, x0=x0, y0=y0, georef=0, $ out_dt=2, pixel_size=pixel_size, $ background=255, see_through_val=see_through_val, $ use_see_through=use_see_through ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide MOSAIC_DOIT
472 Chapter 2: ENVI Routines
MUNSELL_DOIT
Use this procedure to calculate USGS Munsell coordinates (HSV) from an RGB image.
Syntax
ENVI_DOIT, 'MUNSELL_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
POS
R_FID
Example
pro example_munsell_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; munsell transform on all samples ; and first three bands in the file. ; envi_file_query, fid, dims=dims t_fid=[fid,fid,fid] pos = [0,1,2] out_name = 'testmunsell.img'
MUNSELL_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 473
; ; Perform the Munsell transform ; envi_doit, 'munsell_doit', $ fid=t_fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide MUNSELL_DOIT
474 Chapter 2: ENVI Routines
MUNSELL_INV_DOIT
Use this procedure to calculate an RGB image from USGS Munsell coordinates (HSV).
Syntax
ENVI_DOIT, 'MUNSELL_INV_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
POS
R_FID
Example
pro example_munsell_inv_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'testmunsell.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; munsel transform on all samples ; and the first three bands in the file. ; envi_file_query, fid, dims=dims t_fid=[fid,fid,fid] pos = [0,1,2] out_name = 'testimg'
MUNSELL_INV_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 475
; ; Perform the Munsell transform ; envi_doit, 'munsell_inv_doit', $ fid=t_fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide MUNSELL_INV_DOIT
476 Chapter 2: ENVI Routines
MUNSELL_INV_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 477
NDVI_DOIT
Use this procedure to create a normalized difference vegetation index (NDVI).
Syntax
ENVI_DOIT, 'NDVI_DOIT', /CHECK, DIMS=array, FID=file ID, /IN_MEMORY, O_MAX=value, O_MIN=value, OUT_BNAME=string array, OUT_DT={1 | 4}, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
CHECK
Set this keyword to check for divide-by-zero errors. These errors are set to 0.
O_MAX
Use this keyword to specify the output data maximum. Only use this keyword when OUT_DT=1 (byte).
O_MIN
Use this keyword to specify the output data minimum. Only use this keyword when OUT_DT=1 (byte).
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to 1 for byte data and 4 for floating-point data.
POS
ENVI Reference Guide NDVI_DOIT
478 Chapter 2: ENVI Routines
Use this keyword to specify an array of zero-based, two-band positions. NDVI is designed to work with TM, MSS, AVHRR, SPOT, and AVIRIS DATA. The following band pairs are used for each of the different data types. Be sure to subtract 1 from each of the band combinations.
Example
pro example_ndvi_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; NDVI on all samples and all bands ; in the file. ; envi_file_query, fid, dims=dims pos = [4,3] - 1 out_name = 'testimg' ; ; Perform the NDVI transform ; envi_doit, 'ndvi_doit', $ fid=fid, pos=pos, dims=dims, $ /check, o_min=0, o_max=255, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
Data Type Band Numbers (one-based, [IR, Red])
TM Bands= [4, 3]
MSS Bands = [7, 5]
AVHRR Bands = [2, 1]
SPOT XS Bands = [3, 2]
AVIRIS Bands = [51, 29]
NDVI_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 479
ENVI Reference Guide NDVI_DOIT
480 Chapter 2: ENVI Routines
RADAR_INC_ANGLE_DOIT
Use this procedure to calculate an incidence angle for a radar image. No DEM data are used to calculate the incidence angle.
Syntax
ENVI_DOIT, 'RADAR_INC_ANGLE_DOIT' [, /DEGREES], DIMS=array, FR_ANGLE=value, /IN_MEMORY, /LEFT_LOOK, NR_ANGLE=value, OUT_BNAME=string array, OUT_NAME=string, RANGE_DIR={0 | 1}
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
DEGREES (optional)Set this keyword to specify that the input and output angles are in degrees. Otherwise, the angles are in radians.
FR_ANGLE
Use this keyword to specify the far-range angle for the locations specified by the DIMS array.
NR_ANGLE
Use this keyword to specify the near-range angle for the locations specified by the DIMS array.
LEFT_LOOK
Set this keyword to use a left-looking instrument to calculate the incidence angle image.
RANGE_DIR
Use this keyword to specify the range direction. RANGE_DIR is an integer value with the following definitions:
• 0: Range by samples
• 1: Range by lines
Example
pro example_radar_inc_angle_doit ;
RADAR_INC_ANGLE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 481
; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords. ; ns = 512L nl = 512L dims = [-1, 0, ns-1, 0, nl-1] nr_angle = 20.5 fr_angle = 28.0 range_dir = 0 out_name = 'testimg' ; ; Generate the radar incidence angle ; image. ; envi_doit, 'radar_inc_angle_doit', $ dims=dims, nr_angle=nr_angle, $ fr_angle=fr_angle, range_dir=range_dir, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide RADAR_INC_ANGLE_DOIT
482 Chapter 2: ENVI Routines
RATIO_DOIT
Use this procedure to calculate ratios of selected image bands.
Syntax
ENVI_DOIT, 'RATIO_DOIT', /CHECK, DIMS=array, FID=array of file IDs, /IN_MEMORY, O_MAX=value, O_MIN=value, OUT_BNAME=string array, OUT_DT={1 | 4}, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
CHECK
Set this keyword to check for divide-by-zero errors. Any such errors are set to 0.
FID
Use this keyword to specify a long-integer vector representing file IDs for the ratio pairs. Each pair is sequential in the list, i.e., (0,1) (2,3) (4,5) etc.
O_MAX
Use this keyword to specify the output data maximum. This keyword is only used when OUT_DT is set to byte.
O_MIN
Use this keyword to specify the output data minimum. This keyword is only used when OUT_DT is set to byte.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 4: Floating-point (32 bits)
RATIO_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 483
Example
pro example_ratio_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Use the POS keyword to ratio bands 1 and 4. ; Output the result to disk. ; envi_file_query, fid, dims=dims t_fid=[fid,fid] pos = [1,4] out_name = 'testimg' ; ; Perform the ratio calculation ; envi_doit, 'ratio_doit', $ fid=t_fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide RATIO_DOIT
484 Chapter 2: ENVI Routines
RESIZE_DOIT
Use this procedure to spatially resize image data.
Syntax
ENVI_DOIT, 'RESIZE_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, INTERP={0 | 1 | 2 | 3}, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, RFACT=array
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
INTERP
Use this keyword to specify an integer value corresponding to the interpolation type. Choose one of the following.
• 0: Nearest neighbor
• 1: Bilinear
• 2: Cubic convolution
• 3: Pixel aggregate
NoteBilinear and cubic convolution interpolation methods do not apply when downsampling data. You should use either nearest-neighbor or pixel-aggregate interpolation when downsampling data. If you specify bilinear interpolation (INTERP=1) or cubic-convolution interpolation (INTERP=2) while downsampling, RESIZE_DOIT will default to the nearest-neighbor method.
RFACT
Use this keyword to specify a two-element array holding the rebin factors for x and y. The values of RFACT reflect the IDL convention for resizing data. A value of 1 does not change
RESIZE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 485
the size of the data. Values less than 1 cause the size to increase; values greater than 1 cause the size to decrease.
Example
pro example_resize_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Perform the resize calculation. ; Make the output image twice as ; large in both X and Y. Use ; bilinear interpolation. ; envi_doit, 'resize_doit', $ fid=fid, pos=pos, dims=dims, $ interp=1, rfact=[.5,.5], $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide RESIZE_DOIT
486 Chapter 2: ENVI Routines
RGB_GET_BANDS
This procedure displays an ENVI Band Selection dialog that allows you to select three bands from the Available Bands List.
NoteAn interactive ENVI session is required to run this procedure.
Syntax
RGB_GET_BANDS, DIMS=array, FID=file ID [, /NO_DIMS], POS=array [, STR=string array], TITLE=string
Keywords
DIMS
See “Common Keywords” on page 34 for a definition of this keyword.
FID
Use this keyword to specify a named variable that contains the file IDs of the selected files. FID is a three-element array of long integers.
NO_DIMS (optional)Set this keyword to disable spatial subsetting on the selected RGB bands.
POS
Use this keyword to specify a named variable that contains a three-element array of the selected band positions.
STR (optional)Use this keyword to specify a string array containing the labels for the text boxes used to enter the three band names. The default value for the array is ['R','G','B'].
TITLE
Use this keyword to specify the string used in the title bar of the Band Selection dialog window. Enter the title enclosed in single quotes.
Example
This examples uses an RGB selection widget titled “USGS Munsell RGB to HSI Input File” to select three bands. The resulting selection is returned in FID, POS, and DIMS.
tstr = 'USGS Musell RGB to HSI Input File'rgb_get_bands, title=tstr, fid=fid, pos=pos, dims=dimsif (fid[0] eq -1) then return
RGB_GET_BANDS ENVI Reference Guide
Chapter 2: ENVI Routines 487
Notes
If FID(0) = -1, the Cancel button was selected and you should take the appropriate action. There is no requirement that the three bands come from the same file, so you should be sure to properly handle the three FIDs and band positions.
See Also
ENVI_SELECT
ENVI Reference Guide RGB_GET_BANDS
488 Chapter 2: ENVI Routines
RGB_ITRANS_DOIT
Use this procedure to perform HSV-to-RGB and HLS-to-RGB color transforms using IDL functions.
Syntax
ENVI_DOIT, 'RGB_ITRANS_DOIT', DIMS=array, FID=file ID, HSV={0 | 1}, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
FID
Use this keyword to specify a three-element array of long integers representing file IDs for the selected bands. The three elements represent the red, green, and blue bands, respectively.
HSV
Set this keyword to 0 to transform from HSV to RGB, or to 1 to transform from HLS to RGB.
Example
pro example_rgb_itrans_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'testhsv.img', r_fid=fid if (fid eq -1) then begin
RGB_ITRANS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 489
envi_batch_exit return endif ; ; Set the keywords. We will perform the ; inverse HSV transform on all samples ; and first three bands in the file. ; envi_file_query, fid, dims=dims t_fid=[fid,fid,fid] pos = [0,1,2] out_name = 'testimg' ; ; Perform the inverse HSV transform ; envi_doit, 'rgb_itrans_doit', $ fid=t_fid, pos=pos, dims=dims, $ hsv=1, out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide RGB_ITRANS_DOIT
490 Chapter 2: ENVI Routines
RGB_TRANS_DOIT
Use this procedure to perform RGB-to-HSV and RGB-to-HLS color transforms using IDL functions.
Syntax
ENVI_DOIT, 'RGB_TRANS_DOIT', DIMS=array, FID=file ID, HSV={0 | 1}, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
FID
Use this keyword to specify a three-element array of long integers representing file IDs for the selected bands. The three elements represent the red, green, and blue bands, respectively.
HSV
Set this keyword to 0 to transform from RGB to HSV, or to 1 to transform from RGB to HLS. The default value is 0.
Example
pro example_rgb_trans_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid
RGB_TRANS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 491
if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; RGB HSV transform on all samples ; and first three bands in the file. ; envi_file_query, fid, dims=dims t_fid=[fid,fid,fid] pos = [0,1,2] out_name = 'testhsv.img' ; ; Perform the HSV transform ; envi_doit, 'rgb_trans_doit', $ fid=t_fid, pos=pos, dims=dims, $ hsv=1, out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide RGB_TRANS_DOIT
492 Chapter 2: ENVI Routines
ROC_CURVE_DOIT
Use this procedure to compute ROC curves, which compare a series of rule-image classification results for different threshold values with ground truth information. A probability of detection (Pd) versus probability of false alarm (Pfa) curve and a Pd versus threshold curve are reported for each selected class (rule band). ENVI can calculate a ROC curve using either a ground truth image or using ground truth ROIs.
Syntax
ENVI_DOIT, 'ROC_CURVE_DOIT', /PLOT_THRESH, CDIMS=array, CFID=file ID, CPOS=array [, GDIMS=array] [, GFID=file ID] [, GPOS=array] [, GT_PTR=array], MAX_THRESH=value, METHOD={0 | 1}, MIN_THRESH=value, PPC=long integer, PPW=long integer [, RESULT=variable] [, ROI_IDS=value]
Keywords
PLOT_THRESH
Set this keyword to enable plotting the probability of detection (PD) versus threshold plot. The default is to only plot the ROC curves.
CDIMS
Use this keyword to specify the spatial dimensions on which to perform the operation. CDIMS, CFID, and CPOS define the classification rule image used to compute the ROC curves. CDIMS is a five-element array of long integers with the following definitions:
• CDIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• CDIMS[1]: The starting sample number. The first x pixel is 0.
• CDIMS[2]: The ending sample number
• CDIMS[3]: The starting line number. The first y pixel is 0.
• CDIMS[4]: The ending line number
CFID
Use this keyword to specify the file ID for the open classification rule image file. CDIMS, CFID, and CPOS define the classification rule image used to compute the ROC curves. CFID is the value returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. CFID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
CPOS
Use this keyword to specify an array of band positions, indicating the band numbers on which to perform the operation. CDIMS, CFID, and CPOS define the classification rule image used to compute the ROC curves. CPOS is an array of long integers, ranging from 0 to the number of bands minus 1.
ROC_CURVE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 493
GDIMS (optional)Use this keyword to specify the spatial dimensions on which to perform the operation. GDIMS, GFID, and GPOS define the ground truth classification image used to compute the ROC curves. GDIMS is a five-element array of long integers with the following definitions:
• GDIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• GDIMS[1]: The starting sample number. The first x pixel is 0.
• GDIMS[2]: The ending sample number
• GDIMS[3]: The starting line number. The first y pixel is 0.
• GDIMS[4]: The ending line number
If you do not set the keyword ROI_IDS, then you must set GDIMS, GFID, GPOS, and GT_PRT.
GFID (optional)Use this keyword to specify the file ID for the open ground truth classification image file. GDIMS, GFID, and GPOS define the ground truth classification image used to compute the ROC curves. GFID is the value returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. GFID is a long integer with a value greater than 0. An invalid file ID has a value of -1. If you do not set the keyword ROI_IDS, then you must set GDIMS, GFID, GPOS, and GT_PTR.
GPOS (optional)Use this keyword to specify an array of band positions, indicating the band numbers on which to perform the operation. GDIMS, GFID, and GPOS define the ground truth classification image used to compute the ROC curves. GPOS is an array of long integers, ranging from 0 to the number of bands minus 1. If you do not set the keyword ROI_IDS, then you must set GDIMS, GFID, GPOS, and GT_PTR.
GT_PTR (optional)Use this keyword to specify a link between the ground truth class and the corresponding rule image classes. For example, the ground truth class value (the actual pixel value of the ground truth classification image) GT_PTR[k] corresponds to the class created from the rule image band CPOS[k]. GT_PTR is an array of long integers with the same number of elements as CPOS. If you do not set the keyword ROI_IDS, then you must set GDIMS, GFID, GPOS, and GT_PTR.
MAX_THRESH
Use this keyword to specify the threshold maximum for classifying the rule images. The points per curve, as specified by PPC, are evenly distributed between MIN_THRESH and MAX_THRESH.
METHOD
Set this keyword equal to one of the following values to specify the method for classifying the rule images.
ENVI Reference Guide ROC_CURVE_DOIT
494 Chapter 2: ENVI Routines
• 0: Minimum
• 1: Maximum
MIN_THRESH
Use this keyword to specify the threshold minimum for classifying the rule images. The points per curve, as specified by PPC, are evenly distributed between MIN_THRESH and MAX_THRESH.
PPC
Use this keyword to specify the number of points per ROC curve. The points are evenly distributed between MIN_THRESH and MAX_THRESH. PPC is a long-integer value greater than or equal to 2.
PPW
Use this keyword to specify the maximum number of plots per plot window. PPW is a long-integer value greater than 0.
RESULT (optional)Use this keyword to specify a named variable that contains the x,y data from the ROC curves. RESULT is a double-precision array of size [num_points, 2, num_classes]. The x and y values are calculated for each class as follows:
x = reform(result[*,0,i]); probability of false alarmy = reform(result[*,1,i]); probability of detection
ROI_IDS (optional)Use this keyword to specify the ground truth ROIs. ROI_IDS are the selected IDs of the ground truth ROIs returned from the function ENVI_GET_ROI_IDS. If you do not set ROI_IDS, then you must set GDIMS, GFID, and GPOS.
See Also
CLASS_CONFUSION_DOITCLASS_DOITCLASS_RULE_DOIT
ROC_CURVE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 495
ROI_THRESH_DOIT
Use this procedure to create an ROI that contains all pixels with values above, below, or between threshold pixel values.
Syntax
ENVI_DOIT, 'ROI_THRESH_DOIT', DIMS=array, FID=file ID, MAX_THRESH=value, MIN_THRESH=value, /NO_QUERY, POS=array, ROI_ID=variable, ROI_NAME=string, ROI_COLOR=long integer
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
DIMS
FID
POS
MAX_THRESH
Use this keyword to specify the maximum threshold. Values below MAX_THRESH are included in the ROI.
MIN_THRESH
Use this keyword to specify the minimum threshold. Values above MIN_THRESH are included in the ROI.
NO_QUERY
Set this keyword to suppress informational or interactive dialogs during the threshold process.
ROI_ID
Set this keyword to a named variable containing the ID of the resulting ROI.
ROI_NAME
Use this keyword to specify an output name for the ROI.
ROI_COLOR
Use this keyword to specify the output ROI color. ROI_COLOR is a long-integer variable representing the index into the ENVI graphic colors. By default, ENVI has 17 graphic colors, whose index values range from 0 to 16.
Example
pro example_roi_thresh_doit ;
ENVI Reference Guide ROI_THRESH_DOIT
496 Chapter 2: ENVI Routines
; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Use the POS keyword to select the first band ; to use for the ROI. ; envi_file_query, fid, dims=dims pos = [0] roi_name = 'test ROI' out_name = 'test.roi' ; ; Perform the ROI threshold ; envi_doit, 'roi_thresh_doit', $ fid=fid, pos=pos, dims=dims, $ max_thresh=255, min_thresh=30, $ /no_query, roi_color=5, $ roi_name=roi_name, roi_id=roi_id ; ; Save the ROI to a file ; envi_save_rois, out_name, roi_id ; ; Exit ENVI ; envi_batch_exitend
ROI_THRESH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 497
ROTATE_DOIT
Use this procedure to rotate images using standard IDL rotations and transpositions.
Syntax
ENVI_DOIT, 'ROTATE_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, ROT_TYPE={0 | 1 | 2 | 3}, /TRANSPOSE
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
ROT_TYPE
Use this integer keyword to specify the rotation type:
• 0: 0 degrees
• 1: 90 degrees
• 2: 180 degrees
• 3: 270 degrees
TRANSPOSE
Set this keyword to transpose the image.
Notes
Rotations and transpositions are performed according to IDL conventions.
Example
pro example_rotate_doit ; ; First restore all the base save files. ;
ENVI Reference Guide ROTATE_DOIT
498 Chapter 2: ENVI Routines
envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Rotate the image by 90 degrees. ; envi_doit, 'rotate_doit', $ fid=fid, pos=pos, dims=dims, $ rot_type=1, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ROTATE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 499
RTV_DOIT
Use this procedure to perform a raster-to-vector conversion for a classification image or for a contour level on a gray scale image.
Syntax
ENVI_DOIT, 'RTV_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, L_NAME=string array, OUT_NAME=string, POS=array, VALUES=array
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
DIMS
FID
POS
IN_MEMORY
Set this keyword to an array of ones and zeros indicating the storage location for each of the output vectors. IN_MEMORY is a long-integer array of ones and zeros with the same number of elements as VALUES and OUT_NAME.
L_NAME
Use this keyword to specify a string array of vector level names. L_NAME has the same number of elements as the keyword VALUES.
OUT_NAME
Use this keyword to specify a string array of output vector filenames. The OUT_NAME array must have a valid output filename for each of the zero values in the array IN_MEMORY. OUT_NAME has the same number of elements as the keywords VALUES and IN_MEMORY.
VALUES
Use this keyword to specify an array of classification class values to contour or gray scale contour levels. A vector file will be generated for each element in the VALUES array.
Example
pro example_rtv_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt
ENVI Reference Guide RTV_DOIT
500 Chapter 2: ENVI Routines
; envi_batch_init, log_file='batch.txt' ; ; Open the data and class files ; envi_open_file, 'bhtm_sam.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keyword to convert ; all spatial data for ; the first three class (the ; Unclassified class is the ; zero class) to vectors. Each of ; the classes will be output to a ; separate vector file. ; envi_file_query, fid, dims=dims, $ class_names=class_names pos = [0] values = [1, 2, 3] l_name = class_names[values] out_names = 'testimg_' + $ strcompress(string(values),/remove_all) + '.evf' in_memory = lonarr(n_elements(values)) ; ; Call the raster to vector ; processing routine. ;envi_toggle_catch envi_doit, 'rtv_doit', $ fid=fid, pos=pos, dims=dims, $ values=values, l_name=l_name, $ in_memory=in_memory, $ out_names=out_names ; ; Exit ENVI ; envi_batch_exitend
RTV_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 501
SAT_STRETCH_DOIT
Use this procedure to perform a saturation stretch on the data.
Syntax
ENVI_DOIT, 'SAT_STRETCH_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
Example
pro example_sat_stretch_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the keywords. We will perform the ; saturation stretch on the first ; three bands in the file and all ; spatial pixels. ; envi_file_query, fid, dims=dims
ENVI Reference Guide SAT_STRETCH_DOIT
502 Chapter 2: ENVI Routines
t_fid = [fid,fid,fid] pos = [0,1,2] out_name = 'testimg' ; ; Perform the decorrelation stretch ; envi_doit, 'sat_stretch_doit', $ fid=t_fid, pos=pos, dims=dims, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
SAT_STRETCH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 503
SHARPEN_DOIT
Use this procedure to perform HSV and color-normalized sharpening on an image.
Syntax
ENVI_DOIT, 'SHARPEN_DOIT', F_DIMS=array, F_FID=file ID, F_POS=long integer, FID=file ID, /IN_MEMORY, INTERP={0 | 1 | 2}, METHOD={0 | 1}, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
F_DIMS
Use this keyword to specify the spatial dimensions of the high resolution image. F_DIMS is a five-element array of long integers with the following definitions:
• F_DIMS[0]: A pointer to an open ROI; use only in cases where ROIs define the spatial subset. Otherwise, set to -1L.
• F_DIMS[1]: The starting sample number. The first x pixel is 0.
• F_DIMS[2]: The ending sample number
• F_DIMS[3]: The starting line number. The first y pixel is 0.
• F_DIMS[4]: The ending line number
F_FID
Use this keyword to specify the high resolution data file ID for the open file. This value is returned from the keyword R_FID in the ENVI_OPEN_FILE procedure. FID is a long integer with a value greater than 0. An invalid file ID has a value of -1.
F_POS
Use this keyword to specify the band position of the high resolution sharpening band. F_POS is a single long-integer value greater than or equal to 0.
ENVI Reference Guide SHARPEN_DOIT
504 Chapter 2: ENVI Routines
INTERP
Use this keyword to specify an integer value corresponding to the interpolation type. Choose one of the following.
• 0: Nearest neighbor
• 1: Bilinear
• 2: Cubic convolution
METHOD
Use this keyword to specify the sharpening method. METHOD is one of the following long-integer values.
• 0: HSV sharpening
• 1: Color-normalized sharpening
Example
pro example_sharpen_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input high resolution file ; envi_open_file, 'bldr_sp.img', r_fid=f_fid if (f_fid eq -1) then begin envi_batch_exit return endif ; ; Set the keyword F_DIMS and F_POS to ; process all spatial and all spectral ; data. ; envi_file_query, f_fid, ns=f_ns, nl=f_nl ; Set the keywords f_dims = [-1l, 0, f_ns-1, 0, f_nl-1] f_pos = [0] ; ; Open the file for the RGB bands ; envi_open_file, 'bldrtm_m.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; pos = [2,1,0]
SHARPEN_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 505
rgb_fid = [fid,fid,fid] out_name = 'testimg' out_bname = ['Red','Green','Blue'] ; ; Call the sharpening processing ; routine. ; envi_doit, 'sharpen_doit', $ fid=rgb_fid, pos=pos, f_fid=f_fid, $ f_dims=f_dims, f_pos=f_pos, $ out_name=out_name, method=1, $ interp=0, out_bname=out_bname ; ; Exit ENVI ; envi_batch_exitend
See Also
ENVI_PC_SHARPEN_DOITENVI_GS_SHARPEN_DOIT
ENVI Reference Guide SHARPEN_DOIT
506 Chapter 2: ENVI Routines
SIRC_HEADER_DOIT
Use this procedure to read the SIR-C header information used by other SIR-C routines.
Syntax
SIRC_HEADER_DOIT [, AZ_KM=variable] [, BAND=variable] [, CANCEL=variable], FILENAME=string [, NL=variable] [, NS=variable] [, OFFSET=variable] [, RANGE_KM=variable] [, SLH=variable] [, TYPE=variable]
Keywords
AZ_KM (optional)
Use this keyword to specify a named variable that contains the azimuth or y image size in kilometers.
BAND (optional)
Use this keyword to specify a named variable that contains the band number for the file specified by FNAME. Set BAND to 0 for C-Band data and to 1 for L-Band data.
CANCEL (optional)
Use this keyword to specify a named variable that will be set to 0 if you cancel the read request.
FILENAME
Use this keyword to specify the filename of the SIR-C file.
NL (optional)
Use this keyword to specify a named variable that contains the number of lines in the SIR-C image.
NS (optional)
Use this keyword to specify a named variable that contains the number of samples per line in SIR-C image.
OFFSET (optional)
Use this keyword to specify a named variable that contains the offset for the file specified by FNAME.
RANGE_KM (optional)
Use this keyword to specify a named variable that contains the range or x image size in kilometers.
SLH (optional)
SIRC_HEADER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 507
Use this keyword to specify a named variable that contains a flag indicating whether the file needs to skip the line header. A value of 1 indicates that the line header must be skipped when processing.
TYPE (optional)
Use this keyword to specify an named variable that contains the SIR-C data product type for the file specified by FILENAME.
• 0: Microwave Limb Sounder (MLS) quad-polarized
• 1: MLC dual-polarized HH VV
• 2: MLC dual-polarized HH HV
• 3: MLC dual-polarized VH VV
• 4: Single Look Complex (SLC) quad-polarized
• 5: SLC dual-polarized HH VV
• 6: SLC dual-polarized HH HV
• 7: SLC dual-polarized VH VV
• 8: SLC single-polarized HH
• 9: SLC single-polarized HH
Example
pro example_sirc_header_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; filename = 'ndv_l.cdp' ; ; Call the procedure ; sirc_header_doit, $ filename=filename, ns=ns, nl=nl, $ type=type, cancel=cancel, $ offset=offset, band=band, az_km=az_km, $ range_km=range_km, slh=slh ; ; Print the result ; print, 'ns = ', ns print, 'nl = ', nl print, 'offset = ', offset print, 'type = ', type
ENVI Reference Guide SIRC_HEADER_DOIT
508 Chapter 2: ENVI Routines
print, 'slh = ', slh print, 'band = ', band print, 'az_km = ', az_km print, 'range_km = ', range_km ; ; Exit ENVI ; envi_batch_exitend
SIRC_HEADER_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 509
SIRC_MULTILOOK_DOIT
Use this procedure to multilook SIR-C compressed data products.
Syntax
ENVI_DOIT, 'SIRC_MULTILOOK_DOIT', AZ_M=value, DIMS=array, F_NS=integer, F_NL=integer, FNAME=string array, LOOK=array, OUT_NAME=string, OFFSETarray, R_FID=variable, RANGE_M=value, SLH=array, TYPE={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}, XSTART=value, YSTART=value
Keywords
See “Common Keywords” on page 34 for definitions of the following three keywords.
DIMS
OUT_NAME
R_FID
AZ_M
Use this keyword to specify the azimuth or y image size in meters.
FNAME
Use this keyword to specify a string array of compressed data products filenames for C and/or L bands, respectively. If you do not use a file, then set the array element to ''.
F_NS
Use this keyword to specify the number of samples per line in the SIR-C image.
F_NL
Use this keyword to specify the number of lines in the SIR-C image.
LOOK
Use this keyword to specify a two-element array of floating-point values representing the look factors to apply to the x and y directions for range and azimuth, respectively.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
RANGE_M
Use this keyword to specify the range or x image size in meters.
ENVI Reference Guide SIRC_MULTILOOK_DOIT
510 Chapter 2: ENVI Routines
SLH
Use this keyword to specify an array of long integers indicating which files need to strip the line header. A value of 0 indicates that line header is not present, and a value of 1 indicates that the 12-byte SIR-C line header must be stripped. SLH must have the same number of elements as FNAME.
TYPE
Use this keyword to specify an array of SIR-C data product types for each of the files specified by FNAME.
• 0: MLS quad-polarized
• 1: MLC dual-polarized HH VV
• 2: MLC dual-polarized HH HV
• 3: MLC dual-polarized VH VV
• 4: SLC quad-polarized
• 5: SLC dual-polarized HH VV
• 6: SLC dual-polarized HH HV
• 7: SLC dual-polarized VH VV
• 8: SLC single-polarized HH
• 9: SLC single-polarized HH
XSTART
Use this keyword to specify the x offset of the input file.
YSTART
Use this keyword to specify the y offset of the input file.
Example
pro example_sirc_multilook_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = 'ndv_l.cdp' ; ; First get necessary information ; about the SIR data file.
SIRC_MULTILOOK_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 511
; sirc_header_doit, $ filename=fname, ns=ns, nl=nl, $ type=type, cancel=cancel, $ offset=offset, band=band, az_km=az_km, $ range_km=range_km, slh=slh ; ; ; Set the necessary keywords. Use a ; multilook of 10 in both the samples ; and lines. This will make the output ; image 10 times smaller in both ;directions. ; dims = [-1, 0, ns-1, 0, nl-1] az_m = (az_km * 1000.) / 10. range_m = (range_km * 1000.) / 10. look = [10,10] out_name = 'testimg' ; ; Perform the multilook processing ; envi_doit, 'sirc_multilook_doit', $ fname=fname, f_ns=ns, f_nl=nl, $ dims=dims, az_m=az_m, range_m=range_m, $ offset=offset, look=look, $ slh=slh, type=type, xstart=0, $ ystart=0, out_name=out_name ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide SIRC_MULTILOOK_DOIT
512 Chapter 2: ENVI Routines
SIRC_PED_HEIGHT_DOIT
Use this procedure to calculate pedestal height images from a SIR-C compressed data products file.
Syntax
ENVI_DOIT, 'SIRC_PED_HEIGHT_DOIT', DIMS=array, FNAME=string array, FNS=integer, FNL=integer, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, OFFSET=array, R_FID=variable, SLH=array, TYPE={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
FNAME
Use this keyword to specify a string array of compressed data products filenames for C and/or L bands, respectively. If you do not use a file, then set the array element to ''.
FNS
Use this keyword to specify the number of samples per line in the SIR-C image.
FNL
Use this keyword to specify the number of lines in the SIR-C image.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
SLH
Use this keyword to specify an array of long integers indicating which files need to strip the line header. A value of 0 indicates that the line header is not present, and a value of 1 indicates that the 12-byte SIR-C line header must be stripped. SLH must have the same number of elements as FNAME.
SIRC_PED_HEIGHT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 513
TYPE
Use this keyword to specify an array of SIR-C data product types for each of the files specified by FNAME.
• 0: MLS quad-polarized
• 1: MLC dual-polarized HH VV
• 2: MLC dual-polarized HH HV
• 3: MLC dual-polarized VH VV
• 4: SLC quad-polarized
• 5: SLC dual-polarized HH VV
• 6: SLC dual-polarized HH HV
• 7: SLC dual-polarized VH VV
• 8: SLC single-polarized HH
• 9: SLC single-polarized HH
Example
pro example_sirc_ped_height_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = 'ndv_l.cdp' ; ; First get necessary information ; about the SIR data file. ; sirc_header_doit, $ filename=fname, ns=ns, nl=nl, $ type=type, cancel=cancel, $ offset=offset, band=band, az_km=az_km, $ range_km=range_km, slh=slh ; ; ; Set the DIMS keyword to calculate the ; pedestal height image for all spatial ; pixels. ; dims = [-1, 0, ns-1, 0, nl-1] out_name = 'testimg' ; ; Perform the processing
ENVI Reference Guide SIRC_PED_HEIGHT_DOIT
514 Chapter 2: ENVI Routines
; envi_doit, 'sirc_ped_height_doit', $ fname=fname, fns=ns, fnl=nl, $ dims=dims, offset=offset, slh=slh, $ type=type, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
SIRC_PED_HEIGHT_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 515
SIRC_PHASE_IMAGE_DOIT
Use this procedure to calculate phase images from a SIR-C compressed data products file.
Syntax
ENVI_DOIT, 'SIRC_PHASE_IMAGE_DOIT' [, /DEGREE], DIMS=array, FNAME=string array, FNS=integer, FNL=integer, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, OFFSET=array, R_FID=variable, SLH=array, TYPE={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}
Keywords
See “Common Keywords” on page 34 for definitions of the following five keywords.
DIMS
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
DEGREE (optional)
Set this keyword to output the phase images in degrees. The default is radians.
FNAME
Use this keyword to specify a string array of compressed data products filenames for C and/or L bands, respectively. A phase image will be calculated for each file in FNAME.
FNS
Use this keyword to specify the number of samples per line in the SIR-C image.
FNL
Use this keyword to specify the number of lines in the SIR-C image.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
SLH
Use this keyword to specify an array of long integers indicating which files need to strip the line header. A value of 0 indicates that the line header is not present, and a value of 1 indicates that the 12-byte SIR-C line header must be stripped. SLH must have the same number of elements as FNAME.
ENVI Reference Guide SIRC_PHASE_IMAGE_DOIT
516 Chapter 2: ENVI Routines
TYPE
Use this keyword to specify an array of SIR-C data product types for each of the files specified by FNAME.
• 0: MLS quad-polarized
• 1: MLC dual-polarized HH VV
• 2: MLC dual-polarized HH HV
• 3: MLC dual-polarized VH VV
• 4: SLC quad-polarized
• 5: SLC dual-polarized HH VV
• 6: SLC dual-polarized HH HV
• 7: SLC dual-polarized VH VV
• 8: SLC single-polarized HH
• 9: SLC single-polarized HH
Example
pro example_sirc_phase_image_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = 'ndv_l.cdp' ; ; First get necessary information ; about the SIR data file. ; sirc_header_doit, $ filename=fname, ns=ns, nl=nl, $ type=type, cancel=cancel, $ offset=offset, band=band, az_km=az_km, $ range_km=range_km, slh=slh ; ; ; Set the DIMS keyword to calculate the ; phase image for all spatial pixels. ; dims = [-1, 0, ns-1, 0, nl-1] out_name = 'testimg' ; ; Perform the processing ;
SIRC_PHASE_IMAGE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 517
envi_doit, 'sirc_phase_image_doit', $ fname=fname, fns=ns, fnl=nl, $ dims=dims, offset=offset, slh=slh, $ type=type, out_name=out_name, $ /degree, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide SIRC_PHASE_IMAGE_DOIT
518 Chapter 2: ENVI Routines
SIRC_POLSIG_DOIT
Use this procedure to calculate polarization signatures from a SIR-C compressed data products file.
Syntax
ENVI_DOIT, 'SIRC_POLSIG_DOIT', BANDS=array, BFNAME=array, FNAME=string array, FNS=integer, FNL=integer, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, OFFSET=array, R_FID=variable, ROI_ID=array, SLH=array, TYPE={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
IN_MEMORY
OUT_BNAME
OUT_NAME
R_FID
BANDS
Use this keyword to specify an array of ones and zeros indicating whether the C and L bands were used. A value of 1 indicates the band was used. BANDS must be two elements long, regardless of the size of FNAME.
BFNAME
Use this keyword to specify a string array where each element specifies C and L annotations for the header description. BFNAME must be two elements long, regardless of the size of FNAME.
FNAME
Use this keyword to specify a string array of compressed data products filenames for C and/or L bands, respectively. A phase image will be calculated for each file in FNAME.
FNS
Use this keyword to specify the number of samples per line in the SIR-C image.
FNL
Use this keyword to specify the number of lines in the SIR-C image.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
SIRC_POLSIG_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 519
ROI_ID
Use this keyword to specify an array of ROI IDs returned from a call to ENVI_GET_ROI_IDS. Each ID in the array will use the corresponding ROI to calculate both a co-polarization and cross-polarization image.
SLH
Use this keyword to specify an array of long integers indicating which files need to strip the line header. A value of 0 indicates that the line header is not present, and a value of 1 indicates that the 12-byte SIR-C line header must be stripped. SLH must have the same number of elements as FNAME.
TYPE
Use this keyword to specify an array of SIR-C data product types for each of the files specified by FNAME.
• 0: MLS quad-polarized
• 1: MLC dual-polarized HH VV
• 2: MLC dual-polarized HH HV
• 3: MLC dual-polarized VH VV
• 4: SLC quad-polarized
• 5: SLC dual-polarized HH VV
• 6: SLC dual-polarized HH HV
• 7: SLC dual-polarized VH VV
• 8: SLC single-polarized HH
• 9: SLC single-polarized HH
Example
forward_function envi_get_roi_ids
pro example_sirc_polsig_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = 'ndv_l.cdp' ; ; First get necessary information ; about the SIR data file.
ENVI Reference Guide SIRC_POLSIG_DOIT
520 Chapter 2: ENVI Routines
; sirc_header_doit, $ filename=fname, ns=ns, nl=nl, $ type=type, cancel=cancel, $ offset=offset, band=band, az_km=az_km, $ range_km=range_km, slh=slh ; ; Restore the polarization signature ; ROI and get the ROI ids. ; envi_restore_rois, 'pol_sig.roi' roi_ids = envi_get_roi_ids(ns=ns, nl=nl) ; ; Set the DIMS keyword to calculate the ; phase image for all spatial pixels. ; dims = [-1, 0, ns-1, 0, nl-1] bands = [0,1,0] out_name = 'testimg' bfname = ['',fname,''] ; ; Perform the processing ; envi_doit, 'sirc_polsig_doit', $ fname=fname, fns=ns, fnl=nl, $ offset=offset, slh=slh, type=type, $ roi_ids=roi_ids, bfname=bfname, $ bands=bands, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
SIRC_POLSIG_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 521
SIRC_SYNTH_DOIT
Use this procedure to synthesize images from SIR-C compressed data product files.
Syntax
ENVI_DOIT, 'SIRC_SYNTH_DOIT', COMBO=array, DIMS=array, FNAME=string array, FNL=integer, FNS=integer, /IN_MEMORY [, MAX_VAL=value] [, MIN_VAL=value], OUT_DT={1 | 4}, OUT_NAME=string, OFFSET=array, R_FID=variable, /STDMULT, /SIGMA_ZERO, SLH=array, TOTAL_POWER=array, TYPE={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}, XFAC=value, YFAC=value
Keywords
See “Common Keywords” on page 34 for definitions of the following four keywords.
DIMS
IN_MEMORY
OUT_NAME
R_FID
COMBO
Use this keyword to specify a 5 x n array of ellipticity and orientation angles for each image synthesized. The format for the array is:
• [0, i] - Transmit ellipticity for ith image
• [1, i] - Transmit orientation for ith image
• [2, i] - Receive ellipticity for ith image
• [3, i] - Receive orientation for ith image
• [4, i] - Stokes band number (0=C, 1=L)
FNAME
Use this keyword to specify a string array of compressed data products filenames for C and/or L bands, respectively. A phase image will be calculated for each file in FNAME.
FNS
Use this keyword to specify the number of samples per line in the SIR-C image.
FNL
Use this keyword to specify the number of lines in the SIR-C image.
MAX_VAL (optional)
Use this keyword to set a maximum value for output data.
ENVI Reference Guide SIRC_SYNTH_DOIT
522 Chapter 2: ENVI Routines
MIN_VAL (optional)
Use this keyword to set a minimum value for output data.
OFFSET
Use this keyword to specify an array of long integers representing header offsets for each of the files specified by FNAME.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 4: Floating-point (32 bits)
SIGMA_ZERO
Set this keyword to convert the output values to sigma zero, 10*log10(data).
SLH
Use this keyword to specify an array of long integers indicating which files need to strip the line header. A value of 0 indicates that the line header is not present, and a value of 1 indicates that the 12-byte SIR-C line header must be stripped. SLH must have the same number of elements as FNAME.
STDMULT
Set this keyword to specify the standard deviation multiplier for byte output data types. Plus and minus the STDMULT determines the output minimum and maximum.
TOTAL_POWER
Use this keyword to specify a three-element array of ones and zeros indicating whether the total power should be computed for the C and/or L bands, respectively. A value of 1 causes the synthesis of the total power image.
TYPE
Use this keyword to specify an array of SIR-C data product types for each of the files specified by FNAME.
• 0: MLS quad-polarized
• 1: MLC dual-polarized HH VV
• 2: MLC dual-polarized HH HV
• 3: MLC dual-polarized VH VV
• 4: SLC quad-polarized
• 5: SLC dual-polarized HH VV
• 6: SLC dual-polarized HH HV
SIRC_SYNTH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 523
• 7: SLC dual-polarized VH VV
• 8: SLC single-polarized HH
• 9: SLC single-polarized HH
XFAC
Use this keyword to specify an x subsampling factor used to compute image data statistics prior to the conversion to byte. Only use this keyword when the output data type is byte.
YFAC
Use this keyword to specify a y subsampling factor used to compute image data statistics prior to the conversion to byte. Only use this keyword when the output data type is byte.
Example
pro example_sirc_synth_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the keywords ; fname = 'ndv_l.cdp' ; ; First get necessary information ; about the SIR data file. ; sirc_header_doit, $ filename=fname, ns=ns, nl=nl, $ type=type, cancel=cancel, $ offset=offset, band=band, az_km=az_km, $ range_km=range_km, slh=slh ; ; ; Set the DIMS keyword to synthesize all ; spatial pixels. Since we are only using ; the L band we need to set null values ; for the other wavelengths. ; dims = [-1, 0, ns-1, 0, nl-1] combo = [[0.,0.,0.,0.,1]] total_power = [0,1,0] slh = [0, slh] offset = [0, offset] fname = ['', fname] out_name = 'testimg' ; ; Perform the processing ;
ENVI Reference Guide SIRC_SYNTH_DOIT
524 Chapter 2: ENVI Routines
envi_doit, 'sirc_synth_doit', $ fname=fname, fns=ns, fnl=nl, $ dims=dims, offset=offset, slh=slh, $ type=type, combo=combo, out_dt=4, $ total_power=total_power, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
SIRC_SYNTH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 525
SLICE_DOIT
Use this procedure to extract a spectral slice and store the result as an image.
Syntax
ENVI_DOIT, 'SLICE_DOIT', DIMS=array, FID=file ID, /HORIZONTAL, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, /VERTICAL
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
DIMS
Use this keyword to specify the spatial dimensions on which to perform the operation. DIMS is a five-element array of long integers with the following definitions:
• DIMS[0]: Unused for this function, set to -1.
• DIMS[1]: This element specifies the sample for the vertical spectral slice.
• DIMS[2]: The ending X pixel (unused for this function)
• DIMS[3]: This element specifies the line for the horizontal spectral slice.
• DIMS[4]: The ending Y pixel (unused for this function)
HORIZONTAL
Set this keyword to extract a horizontal slice. The extracted line is specified by DIMS[3]. In a horizontal slice image, the number of samples is equal to the number samples in the input image, and the number of lines is equal to the number of elements in the POS array.
VERTICAL
Set this keyword to extract a vertical slice. The extracted column is specified by DIMS[1]. In a vertical slice image, the number of samples is equal to the number of elements in POS, and the number of lines is equal to the number of lines in the input image.
ENVI Reference Guide SLICE_DOIT
526 Chapter 2: ENVI Routines
SLT2GND_DOIT
Use this procedure to convert from slant to ground range.
Syntax
ENVI_DOIT, 'SLT2GND_DOIT', DIMS=array, FID=file ID, HEIGHT=value, /IN_MEMORY, /LEFT_LOOK, NR_RANGE=value, OUT_BNAME=string array, OUT_NAME=string, PS_OUTPUT=value, PS_SLANT_RANGE=value, POS=array, R_FID=variable, RANGE_DIR=value, RESAMPLING={0 | 1 | 2}
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
HEIGHT
Use this keyword to specify the instrument height in meters.
LEFT_LOOK
Set this keyword to specify that the instrument was left-looking in the range direction.
NR_RANGE
Use this keyword to specify the instrument near range in meters.
PS_OUTPUT
Use this keyword to specify the pixel size (in meters) of the ground-range data.
PS_SLANT_RANGE
Use this keyword to specify the pixel size (in meters) in slant range.
RESAMPLING
Use this keyword to specify the pixel resampling method. Set RESAMPLING to one of the following.
SLT2GND_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 527
• 0: Nearest neighbor
• 1: Bilinear
• 2: Cubic convolution
RANGE_DIR
Use this keyword to specify the range direction. If you do not specify this keyword, then the range direction is assumed to be in the samples direction. If you specify this keyword, then the range direction is in the line direction.
Example
pro example_slt2gnd_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bonnrsat.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Perform the slant to ground ; correction. ; envi_doit, 'slt2gnd_doit', $ fid=fid, pos=pos, dims=dims, $ height=27460., nr_dist=28360, $ ps_slant_range=8., ps_output=10.0, $ range_dir=1, resampling=2, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide SLT2GND_DOIT
528 Chapter 2: ENVI Routines
SPECTRAL_FEATURE_DOIT
Use this procedure to perform Spectral Feature Fitting (SFF).
Syntax
ENVI_DOIT, 'SPECTRAL_FEATURE_DOIT', DIMS=array, ENDMEM=array, FID=file ID, /IN_MEMORY, M_FID=file ID, M_POS=long integer, OUT_BNAME=string array, OUT_MODE={0 | 1}, OUT_NAME=string, POS=array, R_FID=variable, /REMOVE_CONT
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY
M_FID
M_POS
OUT_BNAME
OUT_NAME
POS
R_FID
ENDMEM
Use this keyword to specify the endmembers array. ENDMEM is a floating-point array of size [nb, #endmembers].
OUT_MODE
Set this keyword to 0 to output separate files for scale and RMS, or to 1 to output scale and RMS to a single file.
REMOVE_CONT
Set this keyword to specify that Continuum Removal should run prior to Spectral Feature Fitting (SFF).
Example
pro example_spectral_feature_doit ;
SPECTRAL_FEATURE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 529
; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'mof94av.bil', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for spectral ; feature fitting. The endmember data ; must also be transposed in order to ; send in a (nb, # endmember) array. ; envi_read_cols, 'm94_em.asc', $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = 'Fit (' + em_names[2:*] + ')' ; ; Call the spectral feature fitting ; routine. Output the Scale/RMS image ; for each endmember. ; envi_doit,'spectral_feature_doit', $ fid=fid, pos=pos, dims=dims, $ endmem=endmem, /remove_cont, $ out_mode=1, out_bname=out_bname, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide SPECTRAL_FEATURE_DOIT
530 Chapter 2: ENVI Routines
STRETCH_DOIT
Use this procedure to perform contrast stretching of image data.
Syntax
ENVI_DOIT, 'STRETCH_DOIT', DIMS=array, FID=file ID, I_MAX=value, /IN_MEMORY, I_MIN=value, METHOD={1 | 2 | 3 | 4}, OUT_BNAME=string array, OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}, OUT_MAX=value, OUT_MIN=value, OUT_NAME=string, POS=array, R_FID=variable, RANGE_BY={0 | 1}, STDV=value
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
I_MAX
Use this keyword to specify either the maximum percent stretch value or the maximum value, depending on the value of the RANGE_BY keyword.
I_MIN
Use this keyword to specify either the minimum percent stretch value or the minimum value, depending on the value of the RANGE_BY keyword.
METHOD
Set this keyword to one of the following values specifying the type of stretch to perform:
• 1: Linear
• 2: Equalize
• 3: Gaussian
• 4: Square root
STRETCH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 531
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
OUT_MAX
Use this keyword to specify the maximum output value.
OUT_MIN
Use this keyword to specify the minimum output value.
RANGE_BY
Use this keyword to indicate the type of ranging. If you set RANGE_BY to a value of 1, the keywords I_MIN and I_MAX contain absolute minimum and maximum values, respectively. If you set RANGE_BY to a value of 0, I_MIN and I_MAX contain percent stretch values.
STDV
Use this keyword to specify the standard deviation for the Gaussian stretch.
Example
pro example_stretch_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ;
ENVI Reference Guide STRETCH_DOIT
532 Chapter 2: ENVI Routines
envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Call the stretch processing routine. ; We will perform a 2% stretch on the ; data and output a byte image with ; a zero to 255 range. ; envi_doit, 'stretch_doit', $ fid=fid, pos=pos, dims=dims, $ method=1, out_name=out_name, $ i_min=2.0, i_max=98.0, range_by=0, $ out_min=0, out_max=255, out_dt=1, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
STRETCH_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 533
TASCAP_DOIT
Use this procedure to create tasseled cap vegetation and soil indices.
Syntax
ENVI_DOIT, 'TASCAP_DOIT', DIMS=array, FID=file ID, FILE_TYPE={0 | 1 | 2}, /IN_MEMORY, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
POS
R_FID
FILE_TYPE
Set this keyword to one of the following values.
• 0: TM data
• 1: MSS data
• 2: Landsat-7 ETM
Example
pro example_tascap_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif
ENVI Reference Guide TASCAP_DOIT
534 Chapter 2: ENVI Routines
; ; Set the DIMS and POS to keywords ; to processes all spatial and all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb
pos = lindgen(nb) out_name = 'testimg' ; ; Perform the Tasseled Cap vegetation ; and soil indices for the TM data. ; envi_doit, 'tascap_doit', $ fid=fid, pos=pos, dims=dims, $ file_type=0, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
TASCAP_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 535
TEXTURE_COOCCUR_DOIT
Use this procedure to calculate texture co-occurrence measures for an image.
Syntax
ENVI_DOIT, 'TEXTURE_COOCCUR_DOIT', DIMS=array, DIRECTION=array, FID=file ID, /G_LEVELS=integer scalar, /IN_MEMORY, KX=integer, KY=integer, METHOD=array, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_BNAME
POS
R_FID
DIRECTION
Use this keyword to specify the direction and distance between the co-occurrence kernels. DIRECTION is a two-element array of long integers representing the x and y distances and directions. For example, if DIRECTION=[2, -1], then displacement is two pixels to the right and one line up.
G_LEVELS
Use this keyword to set gray scale quantization levels, thereby reducing the number of shades of gray required to represent the image (which also reduces processing time). Set G_LEVELS to an integer scalar less than or equal to 256. This value must be a power of two. If you do not set G_LEVELS, then no gray scale quantization will be performed.
KX
Use this keyword to specify the x kernel size in pixels for calculating the texture measures. Each texture measure is calculated from the localized kernel specified by KX and KY.
KY
Use this keyword to specify the y kernel size in pixels for calculating the texture measures. Each texture measure is calculated from the localized kernel specified by KX and KY.
ENVI Reference Guide TEXTURE_COOCCUR_DOIT
536 Chapter 2: ENVI Routines
METHOD
Use this keyword to specify an eight-element array of integers indicating which texture measure to compute.
• METHOD[0]: Compute the co-occurrence mean
• METHOD[1]: Compute the co-occurrence variance
• METHOD[2]: Compute the co-occurrence homogeneity
• METHOD[3]: Compute the co-occurrence contrast
• METHOD[4]: Compute the co-occurrence dissimilarity
• METHOD[5]: Compute the co-occurrence entropy
• METHOD[6]: Compute the co-occurrence second moment
• METHOD[7]: Compute the co-occurrence correlation
Example
pro example_texture_cooccur_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'can_tmr.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) method = lonarr(8) + 1 direction = [2,2] out_name = 'testimg' ; ; Perform the texture cooccurence ; calculation. ; envi_doit, 'texture_cooccur_doit', $ fid=fid, pos=pos, dims=dims, $ method=method, kx=5, ky=5, $ direction=direction, $ out_name=out_name, r_fid=r_fid
TEXTURE_COOCCUR_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 537
; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide TEXTURE_COOCCUR_DOIT
538 Chapter 2: ENVI Routines
TEXTURE_STATS_DOIT
Use this procedure to calculate texture measures for an image.
Syntax
ENVI_DOIT, 'TEXTURE_STATS_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, KX=integer, KY=integer, METHOD=array, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
KX
Use this keyword to specify the x kernel size in pixels for calculating the texture measures. Each texture measure is calculated from the localized kernel specified by KX and KY.
KY
Use this keyword to specify the y kernel size in pixels for calculating the texture measures. Each texture measure is calculated from the localized kernel specified by KX and KY.
METHOD
Use this keyword to specify a five-element array of integers indicating which texture measure to compute.
• METHOD[0]: Compute the kernel data range
• METHOD[1]: Compute the kernel mean
• METHOD[2]: Compute the kernel variance
• METHOD[3]: Compute the kernel entropy
• METHOD[4]: Compute the kernel skewness
TEXTURE_STATS_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 539
Example
pro example_texture_stats_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhtmref.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Use the POS keyword to calculate ; the texture measures only for ; the first band (band zero). ; Use a 5x5 kernel to calculate ; all texture measures (data range, ; mean, variance, entropy, skewness). ; The results will be save to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = [0] out_name = 'testimg' out_bname = ['Data Range', 'Mean', $ 'Variance', 'Entropy', 'Skewness'] method = [1,1,1,1,1] ; ; Call the texture processing ; routine. ; envi_doit, 'texture_stats_doit', $ fid=fid, pos=pos, dims=dims, $ kx=5, ky=5, method=method, $ out_name=out_name, r_fid=r_fid, $ out_bname=out_bname ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide TEXTURE_STATS_DOIT
540 Chapter 2: ENVI Routines
TIMS_CAL_DOIT
Use this procedure to calibrate TIMS data to radiance. This procedure uses the calibration information at the start of each line to calibrate the data.
Syntax
ENVI_DOIT, 'TIMS_CAL_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, OUT_NAME=string, POS=array [, R_FID=variable], REF_SMOOTH=long integer
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
DIMS
FID
IN_MEMORY
OUT_NAME
POS
R_FID
REF_SMOOTH
Use this keyword to specify the width of the reference data moving average window. REF_SMOOTH lines are averaged together and used for the calibration. REF_SMOOTH is a single long-integer value.
Example
pro example_tims_cal_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'tims_data.raw', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ;
TIMS_CAL_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 541
; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Perform the TIMS Calibration. ; envi_doit, 'tims_cal_doit', $ fid=fid, pos=pos, dims=dims, $ ref_smooth=20, out_name=out_name, $ r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
EMITTANCE_CALC_DOIT
ENVI Reference Guide TIMS_CAL_DOIT
542 Chapter 2: ENVI Routines
TMCAL_DOIT
Use this procedure to calibrate Landsat MSS, TM, and ETM+ data to radiance or reflectance using pre-launch characteristics.
Syntax
ENVI_DOIT, 'TMCAL_DOIT', BANDS_PRESENT=array, BIAS=value, CAL_TYPE={0 | 1}, DATE={0 | 1 | 2}, DIMS=array, FID=file ID, GAIN=value, /IN_MEMORY, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable, SAT={4 | 5 | 7}, SUN_ANGLE=floating point
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
BANDS_PRESENT
Use this keyword to specify an array of band numbers to process from a single Landsat input file. To process multiple bands, set BANDS_PRESENT=[POS]. Use the tables below to determine the appropriate array values.
The following pertains to the MSS sensor on Landsat 4-5. For example, set BANDS_PRESENT=[0] to process Band 1 of a MSS file from Landsat 4 or 5.
The following pertains to the MSS sensor on Landsat 1-3.:
Bands 1 2 3 4
Array value 0 1 2 3
Bands 4 5 6 7
Array value 0 1 2 3
TMCAL_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 543
The following pertains to Landsat TM:
The following pertains to Landsat ETM+:
For example, set BANDS_PRESENT=[5] or BANDS_PRESENT=[6] to process the thermal bands 61 or 62, respectively, of a Landsat ETM+ file. TM_CAL will calibrate the data to temperature in Kelvins.
To process the ETM+ panchromatic band, set BANDS_PRESENT=[8].
BIAS
Use this keyword to specify the calibration bias values for Landsat-7. This keyword is not used for other satellites. BIAS is used with GAIN to convert the data.
CAL_TYPE
Use this keyword to specify the calibration type. Set CAL_TYPE equal to 0 to indicate radiance, or to 1 to indicate reflectance.
DATE
Use this keyword to specify the calibration numbers to use, depending on the date the data were collected. If you want to compute the Earth-Sun distance while calibrating Landsat-7 TM data, set the DATE keyword to an array of [mm, dd, yyyy], specifying the acquisition date.
GAIN
Use this keyword to specify the calibration gain values for Landsat-7. This keyword is not used for other satellites. GAIN is used with BIAS to convert the data.
result=Input * GAIN + BIAS.
SAT
Set this keyword to one of the following values to indicate the satellite and sensor:
• 0: Landsat-7 ETM+
• 1: Landsat-5 TM
• 2: Landsat-4 TM
• 3: Landsat-5 MSS
• 4: Landsat-4 MSS
• 5: Landsat-3 MSS
• 6: Landsat-2 MSS
Bands 1 2 3 4 5 6 7
Array value 0 1 2 3 4 5 6
Bands 1 2 3 4 5 61 62 7 8
Array value 0 1 2 3 4 5 6 7 8
ENVI Reference Guide TMCAL_DOIT
544 Chapter 2: ENVI Routines
• 7: Landsat-1 MSS
SUN_ANGLE
Use this keyword to specify a floating-point value between 0.0 and 180.0, corresponding to the solar elevation angle. This value is used only used for reflectance calibration.
Example
The following example calibrates a single Landsat GeoTIFF file (without metadata) to reflectance.
pro example_tmcal_doit ; ; First restore all the base save files. envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt envi_batch_init, log_file=’batch.txt’ ; ; Create a variable to store the file location. ; File systems may vary locations, this is an example. file_name = ’C:\Program Files\ITT\IDL71\examples\data\boulder.tif’ ; ; Open the input file envi_open_file, file_name, r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ;Output the result to disk. envi_file_query, fid, dims=dims, nb=nb ; ; Set the POS keyword to process all ; spectral data. pos = lindgen(nb) ; ; Set bands_present based on an array position. ; ---------------------------------------------- ; Sensor MSS: ; Bands | 4 | 5 | 6 | 7 | MSS 1-3 ; Bands | 1 | 2 | 3 | 4 | MSS 4-5 ; Array | 0 | 1 | 2 | 3 | ; Sensor TM: ; Bands | 1 | 2 | 3 | 4 | 5 | 6 | 7 | ; Array | 0 | 1 | 2 | 3 | 4 | 5 | 6 | ; Sensor ETM: ; Bands | 1 | 2 | 3 | 4 | 5 | 61 | 62 | 7 | 8 | ; Array | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | ; bands_present = [ARRAY_POSITION] ; ---------------------------------------------- ; ; Single Band example for ; satellite ETM+ band 1 bands_present = [1] ;
TMCAL_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 545
; Assign lmin/lmax values ; if gain/bias is unknown. lmin = -6.2 ; ETM+ High radiance value. lmax = 191.6 ; ETM+ High radiance value. ; ; Calculate the gain and bias from lmin/lmax. gain = (lmax - lmin) / 255 bias = lmin ; ; Assign the acquisition date to the variable data. date = [11,17,2000] out_name = ’testimg’ ; ; ------------------------------------------------------------------ ; Determin Satellite by array position ; Satellite | ETM+7 | TM5 | TM4 | MSS5 | MSS4 | MSS3 | MSS2 | MSS1 | ; Array | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | ; ------------------------------------------------------------------ ; Use Case: sat = 0 ; This will use calibration values of ETM+7 ; ; Perform the TM Calibration ; envi_doit, ’tmcal_doit’, $ fid=fid, pos=pos, dims=dims, $ bands_present=bands_present, $ sat=sat, cal_type=1, date=date, $ sun_angle=29.26, out_name=out_name, $ r_fid=r_fid, gain=gain, bias=bias ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide TMCAL_DOIT
546 Chapter 2: ENVI Routines
TOPO_DOIT
Use this procedure to perform topographic modeling of a DEM image file.
Syntax
ENVI_DOIT, 'TOPO_DOIT', AZIMUTH=value [, BPTR={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}], DIMS=array, ELEVATION=value, FID=file ID, /IN_MEMORY, KERNEL_SIZE=single scalar, OUT_BNAME=string array, OUT_NAME=string, PIXEL_SIZE=array, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
AZIMUTH
Use this keyword to specify the sun azimuth for the purpose of sun shading.
BPTR (optional)Use this keyword to specify an integer array of images to generate. For example, to generate only slope and shaded-relief images, set BPTR = [0,2]. If you do not specify this keyword, then all images will be generated.
• 0: Slope
• 1: Aspect
• 2: Shaded relief
• 3: Profile convexity
• 4: Plan convexity
• 5: Longitudinal convexity
• 6:Cross-sectional convexity
• 7: Minimum curvature
• 8: Maximum curvature
TOPO_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 547
• 9: RMS
ELEVATION
Use this keyword to specify the solar elevation for the purpose of sun shading.
KERNEL_SIZE
Use this keyword to specify a kernel size for the topographic model. KERNEL_SIZE is a single scalar that sets both the x and y kernel size. KERNEL_SIZE determines the local surface-fit size used to calculate topographic modeling parameters.
PIXEL_SIZE
Use this keyword to specify a two-element array containing the x and y pixel sizes, respectively. The pixel size should be in the same units as the DEM.
Example
forward_function envi_get_projectionpro example_topo_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhdemsub.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to use the ; first band from the file. ; We will calculate the slope, ; aspect, and shaded relief images. ; Since the data file is ; georeferenced we can use the ; pixel size from the projection. ; The result will be saved to disk. ; envi_file_query, fid, dims=dims, nl=nl pos = [0] bptr = [0,1,2] out_bname = ['Slope', 'Aspect', $ 'Shaded Relief'] proj = envi_get_projection(fid=fid, $ pixel_size=pixel_size) out_name = 'testimg' ;
ENVI Reference Guide TOPO_DOIT
548 Chapter 2: ENVI Routines
; Call the topographic processing ; routine. Use a sun elevation of ; 67 degrees and an azimuth of 23 ; degrees. ; envi_doit, 'topo_doit', $ fid=fid, pos=pos, dims=dims, $ azimuth=23.0, elevation=67.0, $ bptr=bptr, out_name=out_name, $ out_bname=out_bname, $ pixel_size=pixel_size, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
TOPO_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 549
TOPO_FEATURE_DOIT
Use this procedure to create a topographic feature classification image. Each pixel is classified into one of the following terrain types or morphometric features by setting the keyword CPTR: peak, ridge, pass, plane, channel, or pit.
Syntax
ENVI_DOIT, 'TOPO_FEATURE_DOIT', CLASS_NAMES=array, CONVEX_TOL=value, CPTR={0 | 1 | 2 | 3 | 4 | 5}, DIMS=array, FID=file ID, /IN_MEMORY, KERNEL_SIZE=single scalar, LOOKUP=array, OUT_BNAME=string array, OUT_NAME=string [, PIXEL_SIZE=array], POS=array, R_FID=variable, SLOPE_TOL=value
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
CLASS_NAMES
Use this keyword to specify names for each output class. CLASS_NAMES is an array of strings with [num_classes+1] elements. The first element (Class 0) is “Unclassified.”
CONVEX_TOL
Use this keyword to specify the floating-point or double-precision value for the curvature tolerance. CONVEX_TOL and SLOPE_TOL, in addition to the topographic modeling values, determine how a pixel is classified.
CPTR
Use this keyword to specify an array of long integers representing the type of output class to compute.
• 0: Peak
• 1: Ridge
• 2: Pass
ENVI Reference Guide TOPO_FEATURE_DOIT
550 Chapter 2: ENVI Routines
• 3: Plane
• 4: Channel
• 5: Pit
KERNEL_SIZE
Use this keyword to specify a kernel size for the topographic features. KERNEL_SIZE is a single scalar that sets both the x and y kernel size. KERNEL_SIZE determines the local surface-fit size used to calculate topographic modeling parameters for feature extraction.
LOOKUP
Use this keyword to specify a byte array specifying the color tables for the classification image. The LOOKUP array contains an RGB triplet for each output class. The dimensions of the array are [3, num_classes+1], and the RGB triplet is ordered [r, g , b]. The “Unclassified” class typically uses the RGB triplet [0, 0, 0] for black.
PIXEL_SIZE (optional)Use this keyword to specify the pixel size of the image. PIXEL_SIZE is a two-element array of floating-point or double-precision values specifying the x and y pixel sizes, respectively.
SLOPE_TOL
Use this keyword to specify the floating-point or double-precision value for the slope tolerance. SLOPE_TOL and CONVEX_TOL, in addition to the topographic modeling values, determine how a pixel is classified.
Example
forward_function envi_get_projectionpro example_topo_feature_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'bhdemsub.img', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to use the ; first band from the file. ; Since the data file is ; georeferenced we can use the ; pixel size from the projection.
TOPO_FEATURE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 551
; The result will be saved to disk. ; Use a 7x7 kernel with a slope ; tolerance of 1.0 and a convex ; tolerance of 0.1 ; envi_file_query, fid, dims=dims, sname=sname pos = [0] out_name = 'testimg' proj = envi_get_projection(fid=fid, $ pixel_size=pixel_size) kernel_size = 7L slope_tol = 1.0 convex_tol = .1 ; ; We will classify all feature (peak, ; ridge, pass, plane, channel and pit) ; names - CPTR keyword. Set the output ; band name, class names and class ; colors. ; cptr = bytarr(6) + 1b out_bname = 'Topographic Features (' + $ sname + ')' class_names = ['Unclassified', 'Peak', $ 'Ridge', 'Pass', 'Plane', 'Channel', $ 'Pit'] lookup = bytarr(3,7) for i=0, 6 do begin envi_get_rgb_triplets, i+2, r, g, b lookup[0,i] = [r,g,b] endfor ; ; Call the topographic feature ; classification routine. ; envi_doit,'topo_feature_doit', $ fid=fid, pos=pos, dims=dims, $ kernel_size=kernel_size, $ slope_tol=slope_tol, $ convex_tol=convex_tol, $ pixel_size=pixel_size, $ out_name=out_name, cptr=cptr, $ out_bname=out_bname, $ class_names=class_names, $ lookup=lookup, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
See Also
TOPO_DOIT
ENVI Reference Guide TOPO_FEATURE_DOIT
552 Chapter 2: ENVI Routines
TOPO_FEATURE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 553
PC_ROTATE
Use this procedure to calculate the principal components rotation transform.
Syntax
ENVI_DOIT, 'PC_ROTATE', DIMS=array, EVEC=value, EVAL=value, FID=file ID, /FORWARD, /IN_MEMORY, MEAN=value [, /NO_PLOT], OUT_BNAME=string array, OUT_DT={1 | 4 | 5} [, OUT_NB=integer], OUT_NAME=string, POS=array, R_FID=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following six keywords.
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
DIMS
The “dimensions” keyword is a five-element array of long integers that defines the spatial subset (of a file or array) to use for processing. Nearly every time you specify the keyword FID, you must also specify the spatial subset of the corresponding file (even if the entire file, with no spatial subsetting, is to be processed).
• DIMS[0]: Unused for this routine; set to -1L.
• DIMS[1]: The starting sample number. The first x pixel is 0.
• DIMS[2]: The ending sample number
• DIMS[3]: The starting line number. The first y pixel is 0.
• DIMS[4]: The ending line number
To process an entire file (with no spatial subsetting), define DIMS as shown in the following code example. This example assumes you have already opened a file using ENVI_SELECT or ENVI_PICKFILE:
envi_file_query, fid, dims=dims
EVEC
Use this keyword to specify eigenvectors.
ENVI Reference Guide PC_ROTATE
554 Chapter 2: ENVI Routines
EVAL
Use this keyword to specify eigenvalues.
FORWARD
Set this keyword to specify that PC_ROTATE perform a forward principal components rotation. Otherwise, the inverse rotation is performed.
MEAN
Use this keyword to specify the mean of each band.
NO_PLOT (optional)Set this keyword to disable the resulting principal components eigenvalue plot.
OUT_DT
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
OUT_NB (optional)
Use this keyword for forward principal components rotation to specify the output number of bands for the principal components. The value must be less that than the number of elements of POS, and the default is the number of elements of POS. Only the first OUT_NB bands are stored in the resulting ENVI file.
If you perform an inverse principal components rotation, the output number of bands will be the number of elements of the MEAN keyword.
Example
PRO example_pc_rotate;; First restore all the base save files.;ENVI, /RESTORE_BASE_SAVE_FILES;; Initialize ENVI and send all errors; and warnings to the file batch.txt.;ENVI_BATCH_INIT, LOG_FILE = 'batch.txt';; Open the input file.;file = ENVI_PICKFILE(TITLE = 'mof94av.bil', FILTER = '*.bil')envi_open_file, file, r_fid=fid
IF (fid EQ -1) THEN BEGIN ENVI_BATCH_EXIT
PC_ROTATE ENVI Reference Guide
Chapter 2: ENVI Routines 555
RETURNENDIF;; Set the POS keyword to process all; spectral data. Output the result; to disk.;ENVI_FILE_QUERY, fid, dims=dims, NB = nbpos = LINDGEN(nb)out_name = 'testimg';; Calculate the statistics for the; input data file.;ENVI_DOIT, 'ENVI_STATS_DOIT', $ FID = fid, POS = pos, DIMS = dims, $ MEAN = avg, EVAL = eval, EVEC = evec, $ COMP_FLAG = 5;; Call the Principal Components; processing routine.;ENVI_DOIT, 'PC_ROTATE', $ FID = fid, POS = pos, DIMS = dims, $ MEAN = avg, EVAL = eval, EVEC = evec, $ OUT_DT = 4, OUT_NAME = out_name, $ OUT_NB = nb, R_FID = r_fid, $ /FORWARD;; Exit ENVI.;;ENVI_BATCH_EXITEND
ENVI Reference Guide PC_ROTATE
556 Chapter 2: ENVI Routines
PPI_DOIT
Use this procedure to calculate the Pixel Purity Index (PPI) for an image.
Syntax
ENVI_DOIT, 'PPI_DOIT', DIMS=array, FID=file ID, /IN_MEMORY, ITERATIONS=integer, OUT_BNAME=string array, OUT_NAME=string, P_FID=file ID, POS=array, PREV_DATA=array, PREV_ITER=integer, R_FID=variable, THRESH=variable
Keywords
See “Common Keywords” on page 34 for definitions of the following seven keywords.
DIMS
FID
IN_MEMORY
OUT_BNAME
OUT_NAME
POS
R_FID
ITERATIONS
Use this keyword to specify the total number of iterations to run. If using a previous PPI_DOIT output, then ITERATIONS specifies the additional number of iterations to run.
P_FID
Use this keyword to specify the file ID for a previous output file from the PPI_DOIT. If you do not use a previous PPI_DOIT file, then you must set P_FID to -1.
PREV_ITER
Use this keyword to specify the previous number of iterations performed on the data. You must set PREV_ITER to 0 if the data are not restarting a previous processing cycle.
PREV_DATA
Use this keyword to specify an array of the previous total pixel counts. These data are stored in a .cnt file from the previous run.
THRESH
Use this keyword to specify the threshold factor.
PPI_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 557
Example
pro example_ppi_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'mof94av.bil', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Call the PPI processing ; envi_doit,'ppi_doit', $ fid=fid, pos=pos, dims=dims, $ p_fid=-1, iterations=10000, $ thresh=3.0, prev_iter=0, $ out_name=out_name, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
ENVI Reference Guide PPI_DOIT
558 Chapter 2: ENVI Routines
PPI_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 559
VAX_IEEE_DOIT
Use this procedure to perform VAX IEEE floating-point conversion.
Syntax
ENVI_DOIT, 'VAX_IEEE_DOIT', /COPY_HEADER, IN_NAME=string, OFFSET=value, OUT_NAME=string
Keywords
COPY_HEADER
Set this keyword to specify that the header should be copied to the new output file.
IN_NAME
Use this keyword to specify an input filename for the VAX IEEE data.
OFFSET
Use this keyword to specify a byte offset to the start of the VAX IEEE floating-point data.
OUT_NAME
See “Common Keywords” on page 34 for a definition of this keyword.
Example
pro example_vax_ieee_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt ; envi_batch_init, log_file='batch.txt' ; ; Set the input VAX filename. ; offset = 0L in_name = 'vaxdata' out_name = 'testimg' ; ; Perform the VAX IEEE conversion. ; envi_doit, 'vax_ieee_doit', $ in_name=in_name, out_name=out_name, $ offset=offset ; ; Exit ENVI ; envi_batch_exit
ENVI Reference Guide VAX_IEEE_DOIT
560 Chapter 2: ENVI Routines
end
VAX_IEEE_DOIT ENVI Reference Guide
Chapter 2: ENVI Routines 561
WIDGET_AUTO_BASE
This function is used to create the top-level base widget for any auto-managed ENVI widget. The function returns the widget ID of the newly created base. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_AUTO_BASE([, GROUP=widget ID] [, TITLE=string] [, /XBIG] [, /YBIG])
Keywords
GROUP (optional)Use this keyword to specify the ID of an existing widget that serves as “group leader” for the newly created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. It is not possible to remove a widget from an existing group.
TITLE (optional)Use this optional string keyword to specify a title for the top-level widget.
XBIG (optional)Set this keyword if the widget will be large in the horizontal direction.
YBIG (optional)Set this keyword if the widget will be large in the vertical direction.
Example
; *******************************************************; This routine is an example of how to select multiple; ROIs using a compound widget.;; For more information see the ENVI Programmer's Guide.; *******************************************************; Copyright (c) 2000-2001, ITT Visual Information Solutions.; *******************************************************pro roi_multi_sel envi_select, title='Input Filename', fid=fid if (fid eq -1) then return roi_ids = envi_get_roi_ids(fid=fid, roi_names=roi_names) if (roi_ids[0] eq -1) then begin print, 'No regions associated with the selected file' return endif ; Compound widget for ROI selection base = widget_auto_base(title='ROI Selection') wm = widget_multi(base, list=roi_names, uvalue='list', /auto) result = auto_wid_mng(base) if (result.accept eq 0) then return
ENVI Reference Guide WIDGET_AUTO_BASE
562 Chapter 2: ENVI Routines
ptr = where(result.list eq 1) print, roi_names[ptr] print, roi_ids[ptr]end
WIDGET_AUTO_BASE ENVI Reference Guide
Chapter 2: ENVI Routines 563
WIDGET_EDIT
This function returns a compound widget used to edit multiple values from lists, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_EDIT(Base [, AUTO_MANAGE={0 | 1}] [, CEIL=value] [, DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}] [, FIELD=integer] [, FLOOR=value] [, /FRAME], LIST=string array [, PROMPT=string] [, SELECT_PROMPT=string], UVALUE=value [, VALS=array] [, XSIZE=value] [, YSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
CEIL (optional)Use this keyword to specify a maximum value allowed for input numbers. CEIL is only valid when the VALS keyword is specified.
DT (optional)
Figure 37-7: A Widget with Editable Items Displayed in a List
ENVI Reference Guide WIDGET_EDIT
564 Chapter 2: ENVI Routines
This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
FIELD (optional)Use this keyword to specify the number of decimal places to use when formatting numbers. This keyword has no effect unless DT=4 (floating point) or greater. FIELD is only valid when you specify the keyword VALS.
FLOOR (optional)Use this keyword to specify a minimum value allowed for input numbers. FLOOR is only valid when you specify the keyword VALS.
FRAME (optional)Set this keyword to draw a frame around the widget.
LIST
Use this keyword to specify a string array of items to edit. If you specify VAL, then LIST is the tag name associated with each value.
PROMPT (optional)Use this keyword to specify the prompt string to use for the widget.
SELECT_PROMPT (optional)Use this keyword to specify a prompt string associated with the item being edited.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
WIDGET_EDIT ENVI Reference Guide
Chapter 2: ENVI Routines 565
VALS (optional)Use this keyword to provide an array of values to edit. A string identifier should be associated with each value.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
YSIZE (optional)Use this keyword to specify the height of the widget, in characters.
Widget Event
When the widget is not auto-managed, widget events set event.result to the edited list or, if VAL is specified, to the array of edited numbers. Input numbers are always returned as double-precision, regardless of the value of the keyword DT. Widget events occur any time an edit takes place.
Example
Create a simple compound widget for editing multiple values from a list. Print the final edited list.
base = widget_auto_base(title='Edit test')list = ['Item A ', Item B ', Item C ', 'Item D ']vals = [10.0, 20.0, 30.0, 40.0]we = widget_edit(base, uvalue=’edit', list'=list, $
vals=vals, /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'New Values', result.edit
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_PARAM
ENVI Reference Guide WIDGET_EDIT
566 Chapter 2: ENVI Routines
WIDGET_GEO
This function returns a compound widget used to specify latitude and longitude values, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_GEO(Base [, AUTO_MANAGE={0 | 1}] [, DEFAULT=array] [, DMS=0], LAT_ONLY [, PROMPT=string], UVALUE=value)
Arguments
Base
This is the ID of the widget base.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
DEFAULT (optional)Use this keyword to specify a two-element array of floating-point values representing the default latitude and longitude in decimal degrees. If you set the keyword LAT_ONLY, then DEFAULT is a single-element, floating-point array.
DMS (optional)This keyword is set by default to put latitude and longitude in degrees, minutes and seconds. Set DMS to 0 to allow decimal degrees.
LAT_ONLY
Set this keyword to show only latitude values.
Figure 37-8: A Widget for Entering Latitude and Longitude Values
WIDGET_GEO ENVI Reference Guide
Chapter 2: ENVI Routines 567
PROMPT (optional)Use this keyword to specify a string array for the prompt string. If you do not specify any values, then the prompt array is set to [‘Lat’,‘Lon’].
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
Example
Create a simple compound widget to enter a latitude and longitude value. If the values are entered successfully, then print the result.
base = widget_auto_base(title='Simple Lat/Lon')wg = widget_geo(base, /dms, uvalue='geo', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Latitude: ', result.geo[0]print, 'Longitude: ', result.geo[1]
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_MAP
ENVI Reference Guide WIDGET_GEO
568 Chapter 2: ENVI Routines
WIDGET_MAP
This function returns a compound widget that allows you to input and edit map coordinates and projections. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_MAP(Base [, AUTO_MANAGE={0 | 1}] [, DEFAULT_MAP=array] [, DEFAULT_PROJ=structure] [, /FLIP] [, /FRAME], UVALUE=value)
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
DEFAULT_MAP (optional)Use this keyword to set the default map location for the compound widget. DEFAULT_MAP is a two-element array of double precision-values, where DEFAULT[0] is the default x map location, and DEFAULT_MAP[1] is the default y map location.
DEFAULT_PROJ (optional)Use this keyword to set the default map projection for the compound widget. DEFAULT_PROJ is a projection structure returned from ENVI_GET_PROJECTION or ENVI_PROJ_CREATE.
Figure 37-9: A Widget for Editing Map Coordinates and Projections
WIDGET_MAP ENVI Reference Guide
Chapter 2: ENVI Routines 569
FLIP (optional)Set this keyword to allow flipping between latitude/longitude and map coordinates.
FRAME (optional)Set this keyword to place a frame around the widget base.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
Widget Event
When the widget is not auto-managed, widget events set event.result to a structure with three tags: map_x, map_y, and proj.
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_GEO
ENVI Reference Guide WIDGET_MAP
570 Chapter 2: ENVI Routines
WIDGET_MENU
This function returns a compound widget used to create a menu, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_MENU(Base [, AUTO_MANAGE={0 | 1}] [, BUT_BASES=variable] [, DEFAULT_ARRAY=array] [, DEFAULT_PTR=value] [, /EXCLUSIVE], LIST=string array [, PROMPT=string] [, ROWS=integer], UVALUE=value)
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
BUT_BASES (optional)Use this keyword to specify a named variable that holds the returned array of the widget ID of each button. Specifying this keyword allows you to manage each button by making calls to the IDL routine WIDGET_CONTROL.
DEFAULT_ARRAY (optional)Use this keyword to specify an array indicating the state of each button. A value of 1 indicates the button is set, and a value of 0 indicates the button is not set.
DEFAULT_PTR (optional)Use this keyword to specify which single button should be set by default.
Figure 37-10: A Widget with Exclusive Radio Buttons
WIDGET_MENU ENVI Reference Guide
Chapter 2: ENVI Routines 571
EXCLUSIVE (optional)Set this keyword to make the menu items exclusive.
LIST
Use this keyword to specify an array of string values for the menu buttons.
PROMPT (optional)Use this keyword to specify the prompt string to use for the widget.
ROWS (optional)Use this keyword to specify the number of rows for the menu. The default value is 1.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
Widget Event
When the widget is not auto-managed, if you set EXCLUSIVE, event.result is set to a single value indicating which button was pressed. If you do not set EXCLUSIVE, event.result is a byte array of zeros and ones, where a value of 1 indicates a selected button.
Example
Create a simple compound widget to select one item from a exclusive menu. If the menu item is properly selected, then print the result.
base = widget_auto_base(title='Menu test')list = ['Button 1', 'Button 2', 'Button 3', 'Button 4']wm = widget_menu(base, list=list, uvalue=’menu’, /excl, $
/auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Menu Selected', result.menu
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_PMENU
ENVI Reference Guide WIDGET_MENU
572 Chapter 2: ENVI Routines
WIDGET_MULTI
This function returns a compound widget that allows you to select multiple items from a list, and it returns the base ID of the widget. ENVI uses this widget for spectral subsetting. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_MULTI(Base [, AUTO_MANAGE={0 | 1}] [, BUTTON_BASES=variable] [, DEFAULT=array], LIST=string array [, /NO_RANGE] [, PROMPT=string], UVALUE=value [, YSIZE=integer])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
BUTTON_BASES (optional)
Figure 37-11: A Widget for Selecting Items from a List
WIDGET_MULTI ENVI Reference Guide
Chapter 2: ENVI Routines 573
Use this keyword to specify a named variable that holds the returned array of the widget ID of each button. Specifying this keyword allows you to manage each button by making calls to the IDL routine WIDGET_CONTROL.
DEFAULT (optional)Use this keyword to specify a byte array of zeros and ones indicating the default selection state of each item in the multi-list. A value of 1 indicates that the item is selected, and a value of 0 indicates it is not selected.
LIST
Use this keyword to specify an array of string values for the menu buttons.
NO_RANGE (optional)Set this keyword to disable selection of items by specifying a range.
PROMPT (optional)Use this keyword to specify the prompt string to use for the widget.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
YSIZE (optional)Use this keyword to specify the height of the widget in pixels. The default value is 350.
Widget Event
When the widget is not auto-managed, widget events set event.result to an array of zeros and ones, where a 1 indicates a selected item.
Example
Create a simple compound widget to select multiple items from a list. If the items are properly selected, then print the result.
base = widget_auto_base(title='Multi test')list = ['Item 1', 'Item 2', 'Item 3', 'Item 4']wm = widget_multi(base, list=list, uvalue='list', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Selected Items', where(result.list eq 1)
ENVI Reference Guide WIDGET_MULTI
574 Chapter 2: ENVI Routines
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_SLIST
WIDGET_MULTI ENVI Reference Guide
Chapter 2: ENVI Routines 575
WIDGET_OUTF
This function returns an output filename selection widget that provides no option of output to memory. It returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_OUTF(Base [, AUTO_MANAGE={0 | 1}] [, /DIRECTORY] [, DEFAULT=string] [, FUNC=string] [, PROMPT=string], UVALUE=value [, XSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
DIRECTORY (optional)Set this keyword to allow selection of an output directory.
DEFAULT (optional)Use this keyword to specify the default text string to place in the widget.
FUNC (optional)Use this keyword to specify the name of a function to call with the input string. This allows you to call a custom routine to validate inputs. A value of 1 is returned if the entered filename is valid. Otherwise, a value of 0 is returned.
Figure 37-12: A Widget for Selecting or Choosing an Output Filename
ENVI Reference Guide WIDGET_OUTF
576 Chapter 2: ENVI Routines
PROMPT (optional)Use this keyword to specify the prompt string to use for the widget.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
Widget Event
When the widget is not auto-managed, widget events set event.result to the input string.
Example
Create a simple compound widget to select a file. If the file is properly selected, then print the filename.
base = widget_auto_base(title='File Selection test')wo = widget_outf(base, uvalue='outf', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Selected File', result.outf
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_OUTFM
WIDGET_OUTF ENVI Reference Guide
Chapter 2: ENVI Routines 577
WIDGET_OUTFM
This function returns an output file selection widget that includes the option of output to memory. It returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_OUTFM(Base [, AUTO_MANAGE={0 | 1}] [, DEFAULT=string] [, /FRAME] [, FUNC=string] [, PROMPT=string], UVALUE=value [, XSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
DEFAULT (optional)Use this keyword to specify the default text string to place in the widget.
FRAME (optional)Set this keyword to place a frame around the widget base.
FUNC (optional)
Figure 37-13: A Widget for Selecting Output to File or Memory
ENVI Reference Guide WIDGET_OUTFM
578 Chapter 2: ENVI Routines
Use this keyword to specify the name of a function to call with the input string. This allows you to call a custom routine to validate inputs. A value of 1 is returned if the entered filename is valid. Otherwise, a value of 0 is returned.
PROMPT (optional)Use this keyword to specify the prompt string to be used for the widget.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
Widget Event
When the widget is not auto-managed, widget events set event.result to a structure with two tags: name and in_memory. If in_memory is 0, then name is set to the input string. If in_memory is 1, then the user wants to leave the output in memory and not write the result to a file.
Example
Create a simple compound widget to select output to file or memory. If this is properly selected, then print the result.
base = widget_auto_base(title='File/Memory Selection test')wo = widget_outfm(base, uvalue=’outf', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnif ((result.outf.in_memory) eq 1) then $
print, 'Output to memory selected' $else $
print, 'Selected File', result.outf.name
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_OUTF
WIDGET_OUTFM ENVI Reference Guide
Chapter 2: ENVI Routines 579
WIDGET_PARAM
This function returns a compound widget used to enter a parameter, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_PARAM(Base [, AUTO_MANAGE={0 | 1}] [, CEIL=value] [, /CM] [, /COMMA] [, DEFAULT=string] [, DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}] [, FIELD=integer] [, FLOOR=value] [, /INCHES] [, /PERCENT] [, PROMPT=string] [, UNDEFINED=value], UVALUE=value [, XSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
CEIL (optional)Use this keyword to specify a maximum value allowed for input numbers.
COMMA (optional)Set this keyword to format numbers with commas (example: 3,124,000).
CM (optional)Set this keyword to allow the widget to annotate the entered parameter with “cm”. You cannot use CM with INCHES or PERCENT.
DEFAULT (optional)
Figure 37-14: A Widget for Entering Numeric Parameters
ENVI Reference Guide WIDGET_PARAM
580 Chapter 2: ENVI Routines
Use this keyword to set the default value for the parameter.
DT (optional)This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
FIELD (optional)Use this keyword to specify the number of decimal places to use when formatting numbers. This keyword has no effect unless DT=4 (floating point) or greater.
FLOOR (optional)Use this keyword to specify a minimum value allowed for input numbers.
INCHES (optional)Set this keyword to allow the widget to annotate the entered parameter with " " (the inch symbol). You cannot use INCHES with CM or PERCENT.
PERCENT (optional)Set this keyword to allow the widget to annotate the entered parameter with “%” (the percent symbol). You cannot use PERCENT with CM or INCHES.
PROMPT (optional)Use this keyword to specify the prompt string to use for the widget.
UNDEFINED (optional)Use this keyword to specify the value returned when the parameter is undefined. The default returned value is 10-34.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned
WIDGET_PARAM ENVI Reference Guide
Chapter 2: ENVI Routines 581
anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
Widget Event
When the widget is not auto-managed, widget events set event.result to the value of the input parameter. If the parameter is undefined, then the value of the keyword UNDEFINED is returned.
NoteThe data type of event.result is always double-precision. You are responsible for casting the return value to the appropriate data type.
Example
Create a simple compound widget for inputting one floating-point parameter. If the parameter is properly entered, then print the result.
base = widget_auto_base(title='Parameter test')we = widget_param(base, dt=4, field=3, floor=0., $
default=10., uvalue='param', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Parameter value = ', float(result.param)
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_EDIT
ENVI Reference Guide WIDGET_PARAM
582 Chapter 2: ENVI Routines
WIDGET_PMENU
This function returns a compound widget that displays a drop-down list. The function returns the base ID of the widget, and an interactive ENVI session is required to run it.
Syntax
Result = WIDGET_PMENU(Base [, AUTO_MANAGE={0 | 1}] [, DEFAULT=value], LIST=string array [, LOOKUP=array] [, PROMPT=string], UVALUE=value [, XSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
DEFAULT (optional)Use this keyword to specify the index entry of the default menu selection.
LIST
Use this keyword to specify a string array of drop-down list items. For the best results, pad list items with spaces to make all items equal in length.
LOOKUP (optional)Use this keyword to specify an array of values associated with each menu item.
PROMPT (optional)
Figure 37-15: A Widget with a Drop-down List
WIDGET_PMENU ENVI Reference Guide
Chapter 2: ENVI Routines 583
Use this keyword to specify the prompt string to be used for the widget.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
Widget Event
When the widget is not auto-managed, widget events set event.result to the index of the selected menu item.
Example
Create a simple compound widget with a drop-down list. When you click OK, print the selected menu item.
base = widget_auto_base(title='Menu test')list = ['Item 1', 'Item 2', 'Item 3', 'Item 4']we = widget_pmenu(base, list=list, uvalue='menu', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Menu Item Selected= ', list(result.menu)
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_MENU
ENVI Reference Guide WIDGET_PMENU
584 Chapter 2: ENVI Routines
WIDGET_RGB
This function returns a compound widget to modify a color value associated with an RGB image using the RGB, HLS, or HSV color system. The function returns the base ID of the widget, and an interactive ENVI session is required to run.
NoteAn interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_RGB(Base [, AUTO_MANAGE={0 | 1}] [, /BIT_24] [, INDEX=value], UVALUE=value)
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
BIT_24 (optional)
Figure 37-16: A Widget for Modifying Color Values
WIDGET_RGB ENVI Reference Guide
Chapter 2: ENVI Routines 585
Set this keyword to specify 24-bit color.
INDEX (optional)Use this keyword to select the color table index to edit. The default value is 0.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
Widget Event
When the widget is not auto-managed, widget events set event.result to a byte array of three elements (RGB), regardless of the color system. User-managed widgets can use WIDGET_CONTROL SET_VALUE to change the color index being edited. In this case, you should set SET_VALUE to a three-element array of RGB values for the current index. Or, you can set SET_VALUE to a four-element array, where the fourth value is a new color index to edit.
You can use WIDGET_CONTROL GET_VALUE to return the current RGB three-element array. The inputs and outputs from SET_VALUE and GET_VALUE are always RGB, regardless of the color system selected.
Example
Create a simple compound widget to modify the fifth color in the ENVI graphic color table. If the color is properly modified, then output the new RGB color triplet.
base = widget_auto_base(title='RGB test')we = widget_rgb(base, index=5, uvalue='rgb', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'New RGB color triplet= ', result.rgb
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEENVI_GET_RGB_TRIPLETS
ENVI Reference Guide WIDGET_RGB
586 Chapter 2: ENVI Routines
WIDGET_SLABEL
This function returns a widget used to display a string message with scroll bars. It is essentially a multi-line label widget that cannot be auto-managed on its own. You typically combine this widget with a compound widget that is auto-managed. The function returns the base ID of the widget, and an interactive ENVI session is required to run it.
Syntax
Result = WIDGET_SLABEL(Base [, /FRAME], PROMPT=string [, XSIZE=value] [, YSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
FRAME (optional)Set this keyword to create a frame around the widget.
PROMPT
Use this keyword to specify the text to display.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
YSIZE (optional)Use this keyword to specify the height of the widget, in characters.
Widget Event
This is a passive widget that does not generate events.
Example
The following example creates the widget shown in the above description.
Figure 37-17: A Widget for Displaying Text Messages
WIDGET_SLABEL ENVI Reference Guide
Chapter 2: ENVI Routines 587
base = widget_auto_base(title='WIDGET_SLABEL')ws = widget_slabel(base, prompt='This is a text message.')widget_control, base, /realize
However, instead of creating a standalone widget with a text message, you typically combine WIDGET_SLABEL with another compound widget that is auto-managed. Following is an example of combining WIDGET_SLABEL with WIDGET_STRING.
base = widget_auto_base(title='Edit String')ws = widget_string(base, uvalue='str', /auto)wss = widget_slabel(base, $
prompt='This is the WIDGET_SLABEL text message')result = auto_wid_mng(base)
Following is the resulting widget:
See Also
WIDGET_AUTO_BASE
ENVI Reference Guide WIDGET_SLABEL
588 Chapter 2: ENVI Routines
WIDGET_SLIST
This function returns a compound widget for creating lists, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_SLIST(Base [, AUTO_MANAGE={0 | 1}] [, DEFAULT=value] [, /FORCE] [, /FRAME], LIST=string array [, /NO_SELECT] [, PROMPT=string] [, SELECT_PROMPT=string], UVALUE=value [, XSIZE=value] [, YSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
DEFAULT (optional)Use this keyword to specify the list item that is selected by default.
FORCE (optional)Set this keyword to maintain the width specified by the keyword XSIZE when you set NO_SELECT. If you do not set FORCE when you set both XSIZE and NO_SELECT, the list widget size is then based on the width of the widest item in the list.
Figure 37-18: A Widget for Selecting Items from a Displayed List
WIDGET_SLIST ENVI Reference Guide
Chapter 2: ENVI Routines 589
FRAME (optional)Set this keyword to create a frame around the compound widget.
LIST
Use this keyword to specify a string array of items in the selection list.
NO_SELECT (optional)Normally, the item selected from the list is displayed in a separate text box. Set this keyword to prevent the selected item from being displayed outside the list.
PROMPT (optional)Use this keyword to specify the prompt string to be used for the widget.
SELECT_PROMPT (optional)Use this keyword to specify a string to use as the prompt appearing in the selection widget.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
YSIZE (optional)Use this keyword to specify the height of the widget, in characters.
Widget Event
When the widget is not auto-managed, widget events set event.result to the index of the selected item.
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_MULTI
ENVI Reference Guide WIDGET_SLIST
590 Chapter 2: ENVI Routines
WIDGET_SSLIDER
This function returns a compound widget for setting values using a slider, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_SSLIDER(Base [, AUTO_MANAGE={0 | 1}] [, CEIL=value] [, /DRAG] [, DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}] [, FIELD=integer] [, FLOOR=value] [, /INCHES], MAX=integer, MIN=integer, SCALE=integer, TITLE=string, UVALUE=value, VALUE=value [, XS=array])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
CEIL (optional)Use this keyword to specify a maximum value allowed for input numbers. The returned value will always equal to or less than this number, even if the slider is positioned higher.
DRAG (optional)Set this keyword to cause events to be generated continuously while the slider is being moved.
DT (optional)This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values:
Figure 37-19: A Widget with a Slider for Specifying Numeric Values
WIDGET_SSLIDER ENVI Reference Guide
Chapter 2: ENVI Routines 591
• 1: Byte (8 bits)
• 2: Integer (16 bits)
• 3: Long integer (32 bits)
• 4: Floating-point (32 bits)
• 5: Double-precision floating-point (64 bits)
• 6: Complex (2x32 bits)
• 9: Double-precision complex (2x64 bits)
• 12: Unsigned integer (16 bits)
• 13: Unsigned long integer (32 bits)
• 14: Long 64-bit integer
• 15: Unsigned long 64-bit integer
FIELD (optional)Use this keyword to set the number of decimal places used to format numbers. This keyword has no effect unless DT=4 (floating point) or greater.
FLOOR (optional)Use this keyword to set the minimum value allowed for input numbers. The returned value will always be equal to or greater than this number, even if the slider is positioned lower.
INCHES (optional)Set this keyword to cause the slider to be annotated with “ " ” (the inch symbol).
MAX
Use this keyword to specify an integer maximum for the slider. The value of MAX will be multiplied by the value of SCALE to arrive at the actual maximum slider value.
MIN
Use this keyword to specify an integer minimum for the slider. The value of MIN will be multiplied by the value of SCALE to arrive at the actual minimum slider value.
SCALE
Use this keyword to specify a multiplicative scale factor to use in conjunction with the MIN and MAX keywords. The default value is 1.
TITLE
Use this keyword to specify a title for the slider.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned
ENVI Reference Guide WIDGET_SSLIDER
592 Chapter 2: ENVI Routines
anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
VALUE
Use this keyword to set an initial slider value. The SCALE factor is not applied.
XS (optional)Use this keyword to specify a two-element array, where the first element is the slider size in pixels, and the second element is the text input widget size in characters. The default array is [150, 7].
Widget Event
When the widget is not auto-managed, widget events set event.result to the slider value. This value is already scaled by the SCALE factor. The returned value is always double-precision and should be cast to your selected data type.
Example
Create a simple compound widget to select a value using a slider. Print the final slider location.
base = widget_auto_base(title='Simple Slider')wg = widget_sslider(base, title='Samples', min=0, max=10, $
value=0, uvalue='slide', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Slider value', result.slide
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_PARAM
WIDGET_SSLIDER ENVI Reference Guide
Chapter 2: ENVI Routines 593
WIDGET_STRING
This function returns a compound widget used to enter a string, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_STRING(Base [, /ALL_EVENTS] [, /AUTO_MANAGE] [, DEFAULT=string] [, PROMPT=string], UVALUE=value [, XSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
ALL_EVENTS (optional)Set this keyword to specify that the widget generate an event for all supported events.
AUTO_MANAGE (optional)Set this keyword to specify that the widget be managed by the ENVI function AUTO_WID_MNG.
DEFAULT (optional)Use this keyword to specify a default string.
PROMPT (optional)Use this keyword to specify the prompt string to be used for the widget.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
Figure 37-20: A Widget for Entering Text
ENVI Reference Guide WIDGET_STRING
594 Chapter 2: ENVI Routines
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
Widget Event
When the widget is not auto-managed, widget events set event.result to the entered string.
Example
Create a simple compound widget to enter a string value. Print this string.
base = widget_auto_base(title='Edit String')ws = widget_string(base, uvalue='str', /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'New String ', result.str
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEWIDGET_PARAM
WIDGET_STRING ENVI Reference Guide
Chapter 2: ENVI Routines 595
WIDGET_SUBSET
This function returns a compound widget used to specify image subsets, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_SUBSET(Base [, AUTO_MANAGE={0 | 1}], DIMS=array, FID=file ID [, /ROI], UVALUE=value [, XS=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
Figure 37-21: A Standard Spatial Subset Widget (Left)
ENVI Reference Guide WIDGET_SUBSET
596 Chapter 2: ENVI Routines
DIMS
Use this keyword to specify a named variable that contains a five-element array holding the initial data dimensions. See “Common Keywords” on page 34 for a full definition of DIMS.
FID
Use this keyword to specify the file ID of the file in use. The file ID is used to get the file name and the number of samples and lines.
ROI (optional)Set this keyword to allow ROI subsetting of a file. The ROI ID is returned as the first element in the DIMS array.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
XS (optional)Use this keyword to specify the x size in characters
Widget Event
When the widget is not auto-managed, widget events set event.result to the DIMS array.
Example
Create a simple compound widget for selecting image subsets. Print out the new DIMS array.
envi_file_query, fid, dims=dimsbase = widget_auto_base(title='Subset test')ws = widget_subset(base, uvalue='subset', fid=fid,$
dims=dims, /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'New dims', result.subset
See Also
AUTO_WID_MNGWIDGET_AUTO_BASEENVI_SELECT
WIDGET_SUBSET ENVI Reference Guide
Chapter 2: ENVI Routines 597
WIDGET_TOGGLE
This function returns a compound widget used to create arrow toggle selections, and it returns the base ID of the widget. An interactive ENVI session is required to run this function.
Syntax
Result = WIDGET_TOGGLE(Base [, /AUTO_MANAGE] [, DEFAULT=string], LIST=string array [, PROMPT=string], UVALUE=value [, XSIZE=value])
Arguments
Base
This is the ID of the base widget.
Keywords
AUTO_MANAGE (optional)Use this keyword to specify how ENVI auto-manages the widget with AUTO_WID_MNG. The keyword value specifies if the widget must have a defined value. Setting this keyword to a value of 1 requires that the widget has either a default value or a value that you enter. Setting this keyword to 0 does not require a value. Do not use this keyword for user-managed widgets.
DEFAULT (optional)Use this keyword to specify the list item that is selected by default.
LIST
Use this keyword to specify a string array of items in the selection list.
PROMPT (optional)Use this keyword to specify the prompt string to be used for the widget.
UVALUE
Use this keyword to assign a “user value” to the widget. This value may be of any data type and organization. The user value exists entirely for your convenience. For widgets managed
Figure 37-22: A Widget with an Arrow Toggle Button
ENVI Reference Guide WIDGET_TOGGLE
598 Chapter 2: ENVI Routines
by the ENVI function AUTO_WID_MNG, UVALUE is a tag name in the returned anonymous structure. For user-managed widgets, you can set and use UVALUE however you wish. You must set UVALUE for all compound widgets.
XSIZE (optional)Use this keyword to specify the width of the widget, in characters.
Example
Create a simple compound widget for displaying a toggle selection. Print the final toggle selection.
base = widget_auto_base(title='Toggle test')list = ['Item A', 'Item B', 'Item C']sb = widget_base(base, /row)wt = widget_toggle(sb, uvalue='toggle', list=list, /auto)result = auto_wid_mng(base)if (result.accept eq 0) then returnprint, 'Toggle Selected', result.toggle
WIDGET_TOGGLE ENVI Reference Guide
Chapter 2: ENVI Routines 599
UNMIX_DOIT
Use this procedure to perform Linear Spectral Unmixing.
Syntax
ENVI_DOIT, 'UNMIX_DOIT', DIMS=array, ENDMEM=array, FID=file ID, /IN_MEMORY, M_FID=file ID, M_POS=long integer, OUT_BNAME=string array, OUT_NAME=string, POS=array, R_FID=variable [, WEIGHT=floating point
Keywords
See “Common Keywords” on page 34 for definitions of the following nine keywords.
DIMS
FID
IN_MEMORY
M_FID
M_POS
OUT_BNAME
OUT_NAME
POS
R_FID
ENDMEM
Use this keyword to specify an array of floating-point values representing the end members to unmix with. This array must already be resampled to the correct wavelength for the data. The dimensions of ENDMEM are [nb, num_endmem].
WEIGHT (optional)Use this keyword to specify a weight when applying a unit sum constraint. WEIGHT is a floating-point value greater than 0.
Example
pro example_unmix_doit ; ; First restore all the base save files. ; envi, /restore_base_save_files ; ; Initialize ENVI and send all errors ; and warnings to the file batch.txt
ENVI Reference Guide UNMIX_DOIT
600 Chapter 2: ENVI Routines
; envi_batch_init, log_file='batch.txt' ; ; Open the input file ; envi_open_file, 'mof94av.bil', r_fid=fid if (fid eq -1) then begin envi_batch_exit return endif ; ; Set the POS keyword to process all ; spectral data. Output the result ; to disk. ; envi_file_query, fid, dims=dims, nb=nb pos = lindgen(nb) out_name = 'testimg' ; ; Read in the endmember text file. ; The first column are the ; wavelengths and the next 19 ; columns are the endmembers. We will ; use the 19 endmembers for unmixing. ; The endmember data must also be ; transposed in order to send in ; a (nb, # endmember) array. ; envi_read_cols, 'm94_em.asc', $ endmem, skip=em_names, /read_skip endmem = transpose(endmem[1:*,*]) out_bname = ['Unmix EM:' + $ em_names[2:*], 'RMS Error'] ; ; Call the Unmixing processing ; routine. ; envi_doit,'unmix_doit', $ fid=fid, pos=pos, dims=dims, $ endmem=endmem, out_name=out_name, $ out_bname=out_bname, $ in_memory=0, r_fid=r_fid ; ; Exit ENVI ; envi_batch_exitend
UNMIX_DOIT ENVI Reference Guide
Index
Numerics3D image cubes, 179
AADAPT_FILT_DOIT, 40adaptive coherence estimator, 126adaptive filters, 40AIRSAR data
incidence angle images, 480pedestal height images, 46phase images, 48polarization signatures
extracting, 50resampling to ground ranges, 526scattering classification images, 53synthesizing images, 56viewing headers, 44
AIRSAR_HEADER_DOIT, 44AIRSAR_PED_HEIGHT_DOIT, 46AIRSAR_PHASE_IMAGE_DOIT, 48AIRSAR_POLSIG_DOIT, 50AIRSAR_SCATTER_DOIT, 53AIRSAR_SYNTH_DOIT, 56alpha residual spectra, 122annotation
user-defined, 412anomaly detection, 351ASCII
opening files, 333aspect, 546aspect ratio (MSS), 59ASPECT_DOIT, 59AUTO_WID_MNG, 61autoregistration, 132available bands list
color composites, 486displaying images, 194
AVHRR databuilding geometry files, 138calibrating, 136computing SST, 136warping, 140
Bbackground modeling, 388bad lines
replacing, 62BAD_DATA_DOIT, 62band math, 460band ratios, 482
ENVI Reference Guide 601
602
BandMax, 144batch mode
exiting, 147initializing, 148status, 149
buffer zone images, 151byte swap, 37
Ccalibrating
AVHRR data, 136empirical line, 120flat field, 153IAR reflectance, 153Landsat TM data, 542thermal IR to emissivity, 406TIMS data, 540
CF_DOIT, 64CLASS_CONFUSION_DOIT, 66CLASS_CS_DOIT, 70CLASS_DOIT, 72CLASS_MAJORITY_DOIT, 81CLASS_RULE_DOIT, 83CLASS_STATS_DOIT, 85classification
collecting endmembers, 162converting ROIs to classes, 349neural net, 300supervised, 72SVM, 394unsupervised, 72
clumping classes, 70collecting endmembers, 162color composite images, 486color transforms
HLS to RGB, 488HSV to RGB, 488Munsell HSV to RGB, 474RGB to HLS, 490RGB to HSV, 490RGB to Munsell HSV, 472
COM_CLASS_DOIT, 89combining classes, 89configuring, 243confusion matrices, 66
computing, 66constrained energy minimization, 155continuum removal, 91
CONTINUUM_REMOVE_DOIT, 91contrast stretching, 530
defaultsetting, 181
lookup tables, 449CONV_DOIT, 93CONVERT_DOIT, 96CONVERT_INPLACE_DOIT, 98convolution filters, 93co-occurrence texture filters, 535copyrights, 2COSMO-SkyMed data
saving metadata to XML, 425CROSS_TRACK_CORRECTION_DOIT, 100cross-track illumination correction, 100customizing
map projections, 294
Ddark subtraction, 103data fusion
image sharpening, 503data types, 36
converting interleave types, 96, 98variable codes, 36
data-specific utilitiesthermal IR, 406
decorrelation stretching, 105default stretches
setting, 181variable codes, 36
DEM_BAD_DATA_DOIT, 107DEMs
aspect, slope, shaded relief, 546replacing bad values, 107
deskewing MSS data, 109destriping data, 111digital elevation data
DEMsreplacing bad values, 107
DISP_GET_LOCATION, 113DISP_GOTO, 115DISP_OUT_IMG, 117
EELINE_CAL_DOIT, 120emissivity
Index ENVI Reference Guide
603
alpha residual spectra, 122calculating from thermal IR, 122normalization, 122
EMITTANCE_CALC_DOIT, 122empirical line calibration, 120endmember collection, 162ENVI header file
creating, 370, 435user-defined header values
assigning, 130preserving changes, 435retrieving, 248
ENVI image formatcreating, 427
ENVI save filesrestoring, 124
ENVI_ACE_DOIT, 126ENVI_ADD_PROJECTION, 129ENVI_ASSIGN_HEADER_VALUE, 130ENVI_AUTO_TIE_POINTS_DOIT, 132ENVI_AVHRR_CALIBRATE_DOIT, 136ENVI_AVHRR_GEOMETRY_DOIT, 138ENVI_AVHRR_WARP_DOIT, 140ENVI_BANDMAX_SELECT_BANDS, 144ENVI_BATCH_EXIT, 147ENVI_BATCH_INIT, 148ENVI_BATCH_STATUS_WINDOW, 149ENVI_BUFFER_ZONE_DOIT, 151ENVI_CAL_DOIT, 153ENVI_CEM_DOIT, 155ENVI_CENTER, 158ENVI_CLOSE_DISPLAY, 159ENVI_CLOVER_DOIT, 160ENVI_COLLECT_SPECTRA, 162ENVI_COMPUTE_SUN_ANGLES, 164ENVI_CONVERT_FILE_COORDINATES, 166ENVI_CONVERT_FILE_MAP_PROJECTION,
168ENVI_CONVERT_LIDAR_DATA_DOIT, 172ENVI_CONVERT_PROJECTION_COORDINA
TES, 175ENVI_CREATE_ROI, 177ENVI_CUBE_3D_DOIT, 179ENVI_DEFAULT_STRETCH_CREATE, 181ENVI_DEFINE_MENU_BUTTON, 183ENVI_DEFINE_ROI, 188ENVI_DELETE_ROIS, 190ENVI_DISP_QUERY, 191ENVI_DISPLAY_BANDS, 194ENVI_DOIT, 196
ENVI_ENTER_DATA, 198ENVI_ENVISAT_GEOREF_DOIT, 204ENVI_EVF_CLOSE, 206ENVI_EVF_DEFINE_ADD_RECORD, 207ENVI_EVF_DEFINE_CLOSE, 211ENVI_EVF_DEFINE_INIT, 212ENVI_EVF_INFO, 214ENVI_EVF_OPEN, 216ENVI_EVF_READ_RECORD, 217ENVI_EVF_TO_SHAPEFILE, 219ENVI_FILE_MNG, 221ENVI_FILE_QUERY, 222ENVI_FILE_TYPE, 228ENVI_FILTER_DOIT, 231ENVI_FX_DOIT, 233ENVI_GEOREF_FROM_GLT_DOIT, 240ENVI_GET_CONFIGURATION_VALUES, 243ENVI_GET_DATA, 244ENVI_GET_DISPLAY_NUMBERS, 246ENVI_GET_FILE_IDS, 247ENVI_GET_HEADER_VALUE, 248ENVI_GET_IMAGE, 251ENVI_GET_MAP_INFO, 253ENVI_GET_PATH, 254ENVI_GET_PROJECTION, 255ENVI_GET_RGB_TRIPLETS, 257ENVI_GET_ROI, 258ENVI_GET_ROI_DATA, 259ENVI_GET_ROI_DIMS_PTR, 261ENVI_GET_ROI_IDS, 262ENVI_GET_SLICE, 266ENVI_GET_STATISTICS, 267ENVI_GET_TILE, 269ENVI_GLT_DOIT, 271ENVI_GRID_DOIT, 273ENVI_GS_SHARPEN_DOIT, 276ENVI_ICA_DOIT, 279ENVI_ICA_INV_DOIT, 283ENVI_INFO_WID, 286ENVI_INIT_TILE, 287ENVI_IO_ERROR, 289ENVI_LAYER_STACKING_DOIT, 290ENVI_MAP_INFO_CREATE, 294ENVI_MASK_APPLY_DOIT, 298ENVI_NEURAL_NET_DOIT, 300ENVI_OPEN_DATA_FILE, 304ENVI_OPEN_FILE, 310ENVI_OSP_DOIT, 311ENVI_OUTPUT_TO_EXTERNAL_FORMAT,
314
ENVI Reference Guide Index
604
ENVI_PC_SHARPEN_DOIT, 317ENVI_PICKFILE, 319ENVI_PLOT_DATA, 321ENVI_PROJ_CREATE, 323ENVI_QUERY_VERSION, 330ENVI_RADARSAT_GEOREF_DOIT, 331ENVI_READ_COLS, 333ENVI_REGISTER_DOIT, 335ENVI_REPORT_ERROR, 340ENVI_REPORT_INC, 341ENVI_REPORT_INIT, 342ENVI_REPORT_STAT, 344ENVI_RESAMPLE_SPECTRA, 346ENVI_RESTORE_ROIS, 348ENVI_ROI_TO_IMAGE_DOIT, 349ENVI_RXD_DOIT, 351ENVI_SAVE_ROIS, 353ENVI_SEAWIFS_GEOMETRY_DOIT, 354ENVI_SEAWIFS_GEOREF_DOIT, 356ENVI_SEGMENT_DOIT, 359ENVI_SELECT, 361ENVI_SENSOR_TYPE, 365ENVI_SET_INHERITANCE, 367ENVI_SETUP_HEAD, 370ENVI_SMACC_DOIT, 378ENVI_SPECTRAL_RESAMPLING_DOIT, 381ENVI_STATS_DOIT, 383ENVI_SUBSPACE_BACKGROUND_STATS_D
OIT, 388ENVI_SUM_DATA_DOIT, 391ENVI_SVM_DOIT, 394ENVI_SYNTHETIC_COLOR_DOIT, 398ENVI_TCIMF_DOIT, 400ENVI_TCIMF_MF_DOIT, 403ENVI_THERMAL_CORRECT_DOIT, 406ENVI_TILE_DONE, 408ENVI_TOGGLE_CATCH, 409ENVI_TRANSLATE_PROJECTION_NAME,
410ENVI_TRANSLATE_PROJECTION_UNITS,
411ENVI_USER_DEFINED_ANNOTATION, 412ENVI_VEG_INDEX_AVAILABLE_INDICES,
419ENVI_VEG_INDEX_DOIT, 421ENVI_VEG_SUPPRESS_DOIT, 423ENVI_WRITE_COSMOSKYMED_METADATA
, 425ENVI_WRITE_DBF_FILE, 426ENVI_WRITE_ENVI_FILE, 427
ENVI_WRITE_FILE_HEADER, 435ENVI_WRITE_STATISTICS, 436ENVISAT data
georeferencing, 204error handling (programming)
reporting, 340EVF
closing, 206converting to shapefiles, 219defining, 211getting general information, 214getting vector records, 217initializing, 212opening, 216
external file formats, 304
Ffeature extraction
progamming, 233FFT filters, 231
forward, 438inverse, 440
file formatsASCII
sensor types (sensor.txt), 365file management, 221
file IDs, 247querying file information, 222querying map information, 253, 255retrieving spatial image data, 244retrieving spectral slices, 266saving files, 314
file types, 228filters
convolution, 93FFT, 231morphological, 466
flat field calibration, 153forward FFT filters, 438
Ggains and offsets, 443
applying, 443GEN_IMAGE_DOIT, 445geometry files
SeaWiFS data, 354georeferencing
Index ENVI Reference Guide
605
data typesENVISAT, 204RADARSAT, 331SeaWiFS, 356
input geometryGLTs, 240
layer stacking, 290GIS
exporting vectors to shapefiles, 219GLTs, 271
building, 271georeferencing, 240
Gram-Schmidt sharpening, 276
HHANDLE_VALUE, 448hill shade images
sun elevation, 164HIST_EXPORT_DOIT, 449histograms
lookup tables, 449HLS transforms, 488
forward, 490inverse, 488
HSV transforms, 488forward, 490inverse, 488
IIAR reflectance calibration, 153IDL
converting arrays to ENVI images, 427illumination correction, 100images
contrast stretching, 530displaying, 194masking, 298resizing, 484rotating, 497sharpening, 503synthetic color, 398
image-to-image registration, 335image-to-map registration, 335incidence angle images, 480independent components
forward rotation, 279inverse rotation, 283
inheritance structure, 367installation directories, 254interactive analysis tools
classification overlays, 160interactive stretching
lookup tables, 449defining, 449
interleavingconverting, 96, 98variable codes, 36
interpolating data, 273inverse FFT transforms, 440
Kkeywords, 15
LLandsat data
MSSaspect ratio, 59deskewing, 109
TMcalibrating, 542
LAS LIDAR dataconverting, 172
layer stacking, 290legalities, 2library routines
alphabetical list, 16common keywords, 34functional list, 28keywords, 15named variables, 14syntax, 12variable codes, 36
linear spectral unmixing, 599lookup tables
defining, 449
MMAGIC_MEM_CHECK, 452majority analysis, 81map projections
converting, 168file coordinates, 166
ENVI Reference Guide Index
606
latitude/longitude coordinates, 175custom, 294querying information, 253, 255type codes, 37unit codes, 37
maskingapplying, 298
MATCH_FILTER_DOIT, 454MATCH_FILTER_MT_DOIT, 457matched filtering, 454
MTMF, 457math, 460
band, 460MATH_DOIT, 460menus
adding buttons, 183minority analysis, 81MNF transforms
forward, 462inverse, 465
MNF_DOIT, 462MNF_INV_DOIT, 465model background, 388morphological filters, 466mosaicking, 468MTMF, 457multilooking SIR-C data, 509Munsell transforms
HSV to RGB, 474RGB to HSV, 472
NNDVI, 477neural net classification, 300
Ooccurrence texture filters, 538opening files, 310
external, 304previous, 361
orthogonal subspace projection, 311output formats, 314overlays
classification results, 160
PPC sharpening, 317PC_ROTATE, 553pedestal height images
AIRSAR, 46SIR-C, 512
phase imagesAIRSAR, 48SIR-C, 515
pixelscoordinates, 113locations, 115
plotsnew windows, 321
post classificationaccuracy, 66buffer zone images, 151clumping classes, 70combining classes, 89computing statistics, 85confusion matrices, 66majority/minority analysis, 81overlaying classes, 160ROC curves, 492rule images, 83segmenting images, 359sieving classes, 70
PostScript filessaving images, 117
PPI, 556PPI_DOIT, 556previous files
opening, 361principal components
forward rotation, 553processing status
increments, 341reports, 342
programming in ENVIkeywords, 15named variables, 14syntax, 12
Rradar tools
AIRSAR scattering classification images, 53incidence angle images, 480
Index ENVI Reference Guide
607
multilooking SIR-C data, 509pedestal height images, 46, 512phase images, 48, 515polarization signatures, 50, 518slant to ground range, 526synthesizing AIRSAR images, 56synthesizing SIR-C images, 521
RADAR_INC_ANGLE_DOIT, 480RADARSAT data
georeferencing, 331incidence angle images, 480resampling to ground ranges, 526
raster to vector conversion, 499rasterizing point data, 273RATIO_DOIT, 482reference channel emissivity, 122registration, 335
automatic, 132image-to-image, 335image-to-map, 335
reportingerrors, 340I/O processing errors, 289widgets, 286
resamplingslant to ground range, 526spectral data files, 346, 381
RESIZE_DOIT, 484resizing images, 484RGB
color triplets, 257displaying images, 486sharpening, 503
RGB_GET_BANDS, 486RGB_ITRANS_DOIT, 488RGB_TRANS_DOIT, 490ROC curves, 492ROI_THRESH_DOIT, 495ROIs
creating classification images, 349creating new, 177, 188deleting, 190growing, 495restoring, 348saving, 353
rotating images, 497rotations
forward PC, 553inverse MNF, 465
routines, 16
library, 16RTV_DOIT, 499rule images, 83RX anomaly detection, 351RXD-UTD anomaly detection, 351
SSAM
target finder, 144saturation stretching, 501saving
images, 314PostScript files, 117ROIs, 353
sea surface temperature (AVHRR), 136SeaWiFS data
georeferencing, 356segmenting images, 359sensor types, 365SFF, 528shaded relief, 546shapefiles
exporting vector layers, 219sharpening, 503
Gram-Schmidt, 276PC, 317
sieving classes, 70SIR-C data
incidence angle images, 480multilooking, 509pedestal height images, 512phase images, 515polarization signatures
extracting, 518resampling to ground ranges, 526synthesizing images, 521viewing CEOS headers, 506
SIRC_HEADER_DOIT, 506SIRC_MULTILOOK_DOIT, 509SIRC_PED_HEIGHT_DOIT, 512SIRC_PHASE_IMAGE_DOIT, 515SIRC_POLSIG_DOIT, 518SIRC_SYNTH_DOIT, 521slant to ground range, 526, 526SLICE_DOIT, 525slope, 546SLT2GND_DOIT, 526SMACC spectral tool, 378
ENVI Reference Guide Index
608
spectral mapping methodscontinuum removal, 91linear spectral unmixing, 599matched filtering, 454MTMF, 457SFF, 528
spectral resampling, 346, 381spectral slices, 525
extracting, 266SPECTRAL_FEATURE_DOIT, 528SST, 136statistics, 383
classification, 85output to ENVI statistics file, 436reports, 267summing bands, 391
STRETCH_DOIT, 530sun elevation, 164supervised classification, 72
neural net, 300SVM, 394
support vector machine. See SVMSVM classification, 394synthetic color images, 398
Ttasseled cap transforms, 533test data, 445texture filters
co-occurrence measures, 535occurrence measures, 538
thermal IR utilities, 406tie points
generating automatically, 132tiling
library routinescompleting processing, 408getting tile data, 269incrementing processing, 341initializing processing, 287
TIMS dataradiance calibration, 540
TIMS_CAL_DOIT, 540TMCAL_DOIT, 542TOPO_DOIT, 546TOPO_FEATURE_DOIT, 549topographic tools
classifying features, 549
modeling, 546replacing bad DEM values, 107
TOPSAR dataviewing headers, 44
trademarks, 2transforms
decorrelation stretching, 105MNF, 462sharpening, 503synthetic color images, 398tasseled cap, 533
Uunmixing, 599unsupervised classification, 72user-defined
header values, 435UTD anomaly detection, 351
VVAX to IEEE conversion, 559vectors
adding, 207exporting to shapefiles, 219rasterizing point data, 273
vegetation indices, 421broadband greenness
NDVI, 477calculating, 419tasseled cap, 533
vegetation suppression, 423vegetation tools
VI calculator, 419
Wwarping
AVHRR data, 140WIDGET_AUTO_BASE, 561WIDGET_EDIT, 563WIDGET_GEO, 566WIDGET_MAP, 568WIDGET_MENU, 570WIDGET_MULTI, 572WIDGET_OUTF, 575WIDGET_OUTFM, 577
Index ENVI Reference Guide
609
WIDGET_PARAM, 579WIDGET_PMENU, 582WIDGET_RGB, 584WIDGET_SLABEL, 586WIDGET_SLIST, 588WIDGET_SSLIDER, 590WIDGET_STRING, 593WIDGET_SUBSET, 595WIDGET_TOGGLE, 597widgets
centering offsets, 158image subsets, 595latitudes and longitudes, 566lists, 588map coordinates, 568
menus, 570multiple list values, 563multiple selections, 572numeric parameters, 579output filenames, 575output type, 577pulldown menus, 582reporting, 286RGB values, 584sliders, 590text messages with scroll bars, 586text strings, 593toggle buttons, 597top-level, 561
ENVI Reference Guide Index
610
Index ENVI Reference Guide