1. If you still have the previous IDL and ENVI session open, go to the IDL workbench and after the ENVI prompt type:
ENVI> e = envi(/current) ENVI> e.close
This will close ENVI. Because you started this session as just IDL, closing ENVI will not close IDL.
2. From the IDL workbench, select File Open or click on the Open icon from the file manipulation menu bar:
3. Navigate to your extend\src directory and examine the available files. In addition to
batch_envi_veg_ind.pro from the previous exercise there are several other batch examples. These files contain several types of ENVI_DOIT routines, so looking through them should give you some basic familiarity with how different keywords are called and used. In addition, a few of them contain ways to search for and run operations on multiple files or to accept input from the user prior to initiating the batch. Select the file batch_envi_enh_lee.pro and click Open.
4. The batch code for running the enhanced lee filter in batch_envi_enh_lee.pro is similar to our simple example from the previous exercise. There are, however, a few areas of code worth pointing out:
; Get the dims information from the file.
envi_file_query, ENVIRasterToFID(img), dims=dims
; Run Enhanced Lee Filter in batch mode.
Library Routines Extending ENVI
pos=lindgen(img.nbands), $
dims=dims, $
fid=ENVIRasterToFID(img), $
method=6, $ ; Enhanced Lee
kx=5,$
cu=0.52, $
cmax=1.73, $
damp=0.0, $
out_name=out_file
In this case, we are running an ENVI process that requires several more parameters, including the standard keywords POS and DIMS. The METHOD, KX, CU, CMAX, and DAMP keywords are all explained in the help for ADAPT_FILT_DOIT. These correspond to parameters you would see when running the tool from ENVI’s Toolbox (Filter → Enhanced Filter).
To set dims, we use the older routine, ENVI_FILE_QUERY. ENVI_FILE_QUERY accepts a FID, rather than a raster object, so we use ENVIRasterToFID to get a FID from our ENVIRaster object “IMG.” Similarly, we use the NBANDS property of our ENVIRaster to generate our POS array. The result of this operation for an 8-band image will be [0,1,2,3,4,5,6,7] which will tell ENVI to use every band in the image.
Optional: If you are not sure what a tool or batch program is doing, check to see which DOIT routine is being used, then search for it in the Toolbox. You may need to check the help for that particular DOIT routine. Open and run the tool and try lining up parameters in the tool versus the ones in the DOIT. There will not always be a one-to-one correspondence (sometimes extra things are exposed in the GUI, sometimes in the API), but you will be able to get a good feel for how to set the parameters programmatically by exploring the GUI tools.
5. Change the hard coded input and output file paths as necessary. Then click the Run button to compile and run batch_envi_enh_lee_rq.pro. This batch program is similar to the previous example, except that it makes use of a convenience routine not included with the ENVI default. This program is ENVIRasterQuery, an object interface to get keywords and parameter settings after querying a file. By default, all the settings of ENVIRasterQuery match those of the input file. Therefore, it should be used when you intend to run the process on the entire file, rather than a subset.
6. In the following lines, we can see how ENVIRasterQuery is used:
; Get a Query object to access the raster's properties
img_info = ENVIRasterQuery(img)
; Run Enhanced Lee Filter in batch mode.
envi_doit, 'adapt_filt_doit', $
pos=img_info.pos, $ ; Standard Keyword POS
dims=img_info.dims, $ ; Standard Keyword DIMS
fid=img_info.fid, $ ; Standard Keyword FID
method=6, $ ; Enhanced Lee
kx=5,$ ; Kernel size
cu=0.52, $ ; Homogenous Area Cutoff
cmax=1.73, $ ; Heterogenous Area Cutoff
damp=1.0, $ ; Dampening coefficient
out_name=out_file ; Output file
Extending ENVI Library Routines
ENVIRasterQuery greatly simplifies the necessary IDL knowledge required to run a batch process, so if lines like pos=lindgen(nb) still seem a bit esoteric to you, feel free to use it in your own batch programs. You will need to keep a copy of it in the same directory you call batch programs from, or elsewhere in your IDL path.
Note: You can see which directories are in your IDL path by typing the following at the command line:
ENVI> print, !path
7. There is one other section of code to highlight from batch_envi_enh_lee_rq.pro, namely the block in which ENVI is started:
; Start ENVI in headless mode unless ENVI is open.
e = envi(/current)
if e eq !null then begin e = envi(/headless)
must_exit = 1B
endif else must_exit = 0B
This code checks to see if ENVI is open, and if it is not open, starts a new process. Otherwise, we use the current ENVI process. A code block like this allows us to write a batch program that will still run whether or not ENVI was open. You’ll notice that the must_exit variable is assigned a value of 1 in the case that ENVI was not open. We check on this and exit ENVI at the end of the program if necessary with the following line:
; Exit ENVI unless ENVI was already open.
if must_exit then e.close
8. Next, open and look at batch_ica.pro. Note the following lines of code: pro batch_ica, in_file, out_file99
compile_opt idl2, logical_predicate
[…]
; If called from command line use command line arguments.
args = command_line_args(count=args_count)
if args_count then begin
in_file = args[0]
out_file = args[1]
endif
The code above enables batch_ica to be run either from the workbench or IDL command line, or from an external process such as your operating system command line. In either case, the input file and output file names must be passed as parameters. The way to call this from IDL is shown in the next step.
9. To run batch_ica.pro hit the button and then go to the command line. Type: ENVI> batch_ica, file_which("boulder-etm.dat"), $
"C:\ ENVI_coursefiles\envidata50\extend\boulder_ica.dat"
10. Note that your output file path will probably differ. Also, if boulder-etm.dat is not in your file path, you may need to hard code the input file path (it is located in your extend directory). 11. Now you can run this program multiple times from the command line and supply a different input
ENVI Extensions Extending ENVI
and output file each time, without worrying about what the settings are. Constructing programs like this is referred to as modularizing them; breaking them into the necessary components so those components can be re-used or called as needed. If you have a little bit of IDL programming knowledge, it’s possible to do things like construct a string array of file names from a file search in order to run your batch process on every file in a particular directory.
12. Also note that BATCH_ICA is written to be compatible with earlier versions of ENVI (compile_opt idl2, logical_predicate). For this reason, it uses the procedural interface to ENVI, and makes calls to ENVI_BATCH_INIT and ENVI_BATCH_EXIT rather than e = envi(/headless) and e.close(). Note that if you want to share code with colleagues using a version of ENVI prior to 5.0, your batch routines will need to be written this way instead. You can consult the help topic on these routines for more information.
Optional: Note that there are other batch and programming examples included in your extend\src directory in the course data. These include a few batch examples not discussed directly in the text that make use of things like regular expressions, file routines, and GUI elements to help direct batch processing. Each of these components is commented in the code at a detailed level to help a new user learn how to use similar coding practices in their own batch programs.
Note on code use/license: Feel free to copy and paste from and/or use these batch programs as templates for your own work. This code is not protected and is meant for instructional purposes. This code has no warranty and represents no obligation from Exelis VIS, and therefore the following legal terms apply: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
ENVI Extensions
You may have noted the presence of the Extensions folder in the ENVI Toolbox. Programs that are placed in the Extensions folder, and that meet the necessary IDL criteria to be recognized by ENVI as extensions are automatically accessible. These routines must end in .pro (text code) or .sav (compiled code), and contain an IDL procedure that will execute when the tool is clicked on in the menu.
Extending ENVI ENVI Extensions
The Directories topic under the File Preferences contains the file path to the current Extensions File Directory. For your system configuration, it may be necessary to make sure this exists somewhere in your user space so you can modify its contents (on Windows, somewhere under your username folder, and on Unix-based systems like Linux and Mac, somewhere in your home folder).
Note: If you do not have write permissions to the directory, you will need to change the Extensions File Directory path to a location where you have write permissions prior to attempting the final two exercises of this chapter.