An ENVI 5 batch program

ENVI 5, released last week, has a new UI and API. I’d like to show a pair of examples that use the API: this week, a batch program; next week, an extension (the successor to a user function). Batch programs are used to perform a sequence of processing tasks, typically noninteractively. They may use routines from both the ENVI and IDL libraries. Since batch programs are invoked from IDL, they require ENVI+IDL. I’d like to show a familiar task: creating an NDVI image from the Bighorn Landsat 7 ETM+ scene included in the ENVI distribution. Here’s the beginning of the batch program:

pro envi5_batch_ex
   compile_opt idl2

   e = envi(/headless)

Calling ENVI as a function starts the interface to ENVI 5. (You can still access ENVI Classic (the new nickname for three-window ENVI) by calling ENVI as a procedure.) The HEADLESS keyword starts ENVI without a UI, similar to the Classic ENVI_BATCH_INIT routine. The return value from the ENVI function is a reference for this ENVI session. Next, set up a path to the Bighorn Landsat file and get a reference to it:

   infile = filepath('bhtmref.img', $
      root_dir=e.root_dir, $
      subdirectory=['classic','data'])
   bh = e.openraster(infile)

The reference e is used here twice: the ROOT_DIR property holds the path to the ENVI installation directory; the OpenRaster method creates a new instance of the ENVIRaster class for this file. The reference bh is analogous to a FID in Classic, but it also holds image metadata, so an ENVIRaster in effect combines the functionality of ENVI_OPEN_FILE and ENVI_FILE_QUERY in Classic. To compute NDVI, I’ll choose to use the Classic NDVI_DOIT routine. Most of the DOIT routines haven’t yet been ported from Classic to ENVI 5; this will occur over the next few service packs. I’ll show here a technique that’ll work in this transitional period. NDVI_DOIT requires an input FID, which we don’t have. Use the ENVIRASTERTOFID function to extract a FID from the existing ENVIRaster object:

   bh_fid = envirastertofid(bh)

Note that ENVIRASTERTOFID has a complement, ENVIFIDTORASTER, that converts a FID to an ENVIRaster. Next, set up additional information required by NDVI_DOIT:

   outfile = e.getpreference('output_directory') + 'bhtmref_ndvi.img'
   bh_dims = [-1, 0, bh.ncolumns-1, 0, bh.nrows-1]
   bh_pos = [4,3] - 1 ; Landsat [nir,red] bands
   bh_dt = 4 ; float

The GetPreference method allows programmatic access to certain ENVI preferences. I’m using it here to get the path to the user’s output directory, where NVDI_DOIT will write its result. The variables bh_dims, bh_pos and bh_dt set up the band dimensions, band position vector and data type for the NDVI calculation. Note how the number of samples and number of lines in the image are pulled from the ENVIRaster reference bh. Now that setup is complete, call NDVI_DOIT through the ENVI_DOIT wrapper:

   envi_doit, 'ndvi_doit', $
      fid=bh_fid, $
      dims=bh_dims, $
      pos=bh_pos, $
      /check, $
      out_bname='Calculated NDVI', $
      out_dt=bh_dt, $
      out_name=outfile, $
      r_fid=r_fid
   print,'New file written to: ' + outfile

Finish the program by closing the headless ENVI session and returning to IDL:

   e.close
end

The Close method is the analogue to the Classic ENVI_BATCH_EXIT routine. Execute this program with the Run button in the IDL Workbench or by calling it from the IDL command prompt:

IDL> envi5_batch_ex
% Compiled module: ENVI5_BATCH_EX.
% Restored file: ENVI.
New file written to: C:\mpiper\ENVI\output\bhtmref_ndvi.img

Grab the source code for this example here.