The ENVI API is based on the IDL programming language and uses an object-oriented approach to manage the application state, data files, and display. Code examples are available for all of the API routines in ENVI Help to get you started, but to add more flexibility and customization, you should be familiar with basic IDL programming concepts. You should first review the IDL Programming help topic if you have limited experience with IDL. In addition to IDL, you should understand some rudimentary concepts about objects.

Objects

Objects are the building blocks of a program; each object contains data and routines and does one specific thing. For example, the ENVIRaster object is a self-contained item that manages all aspects of an image (raster). It has properties, or things that describe the raster data type such as rows and columns; and it has methods, or actions that you can perform such as saving the image to disk.

The ENVI API was designed to manage the state and behavior of objects and to provide a simple interface for customizing ENVI. You do not need any object-oriented programming skills to write ENVI API scripts. You can still use IDL's traditional procedures and functions as well as objects to create your own programs. Object-based programs allow you to build more robust applications from groups of re-usable elements. Applications built from objects are generally easier to maintain and extend when compared to structured programming techniques.

For example:

e = ENVI()
File = e.GetTemporaryFilename()
Raster = ENVIRaster(File)

ENVIRaster is an object that manages raster data; by issuing a function call to ENVIRaster (using File as an argument), you are creating a new instance of the object. Those who are familiar with object-oriented programming will notice that there are no separate calls to initialize or clean up the object; this is done for you.

Similarly, customers who wrote programs to extend ENVI Classic using its procedure-based methods relied on the FID and R_FID keywords to pass file references back and forth between program components; by using objects (which contain both routines and data), they no longer need to explicitly manage file references.

The next section demonstrates some of these concepts by showing you how to write simple scripts.

Writing your First Script

A script is another name for a program, whether you issue commands one-by-one at the IDL command line or you write a full IDL program that can be run and compiled. In this section, you will learn a couple of different ways to write scripts to customize ENVI processes.

Interactive Mode

Many of the code examples for ENVI API help topics are designed for you to copy and paste into the IDL command line. Issuing commands like this is referred to as interactive mode. Use this mode when you want to display data and interact with the ENVI application. Start IDL and type the following text (shown in bold) at the command line to launch the ENVI application. Case does not matter; program calls are shown in uppercase for consistency:

IDL> e = ENVI()

Copy and paste the following text into the IDL command line. 

IDL> File = FILEPATH('qb_boulder_msi', Subdir=['data'], Root_Dir=e.Root_Dir)

This locates a sample QuickBird image from the ENVI installation folder. The IDL FILEPATH command is a shortcut to access files that are in the IDL installation path so that you do not need to type the full path. The e.Root_Dir property contains the location of the ENVI root directory, which is typically:

Windows: C:\Program Files\C:\Program Files\INSTALL_DIR\ENVIxx

Linux: /usr/local/INSTALL_DIR/envixx

Mac: /Applications/INSTALL_DIR/envixx

Once IDL has found the file on disk, you can open the file within ENVI. Type the following text:

IDL> Raster = e.OpenRaster(File)

Next, display the image. To do this, retrieve a new view and populate it with a data layer:

IDL> View = e.GetView()
IDL> Layer = View.CreateLayer(Raster)

View the image at full extent:

IDL> View.Zoom, /FULL_EXTENT

Close the ENVI session:

IDL> e.Close

This was a simple example that displayed an image. You will learn more about writing data-processing tasks later.

Batch Mode

You can also write a script that runs ENVI in batch mode without any user interaction or user interface. This is a good option when you need to process multiple files at once. To write a batch script:

  • Include an IDL PRO declaration statement and an END statement.
  • Add COMPILE_OPT IDL2 after the PRO declaration statement.
  • Use the /HEADLESS keyword when starting the ENVI application.
  • Optionally include a FOR loop to do image processing with multiple files.
  • Close the ENVI session using the e.Close statement.
  • Save the script with the same filename as the PRO declaration statement.
  • Compile and run the program in IDL.

Example 1: Simple Batch Program

Here is an example that opens a group of sample data files from the \data\time_series folder of the ENVI installation. It extracts the acquisition time from each file and prints the results to the IDL console:

PRO TimeSeriesExample
  COMPILE_OPT IDL2
   
  ; Start the application
  e = ENVI(/HEADLESS)
   
  ; Select input files
  TimeSeriesDir = Filepath('', Subdir=['data','time_series'], $
    Root_Dir = e.Root_Dir)
  Rasters = File_Search(TimeSeriesDir, 'AirTemp*.dat')
   
  ; Get the acquisition times
  For i=0, N_Elements(Rasters)-1 DO BEGIN
    Raster = e.OpenRaster(Rasters[i])
    PRINT, Raster.Time.Acquisition
  Endfor
   
  e.Close
END

Example 2: ENVI Startup Preferences

Suppose that you want to always launch ENVI with two views containing two images that you frequently work with. You can write a short batch program once to do all of these tasks, then specify the path to your batch program from an IDL Workbench shortcut. This type of batch program cannot have PRO and END statements as in Example 1. These instructions are for Windows users.

  1. Start IDL and click the New Pro button.
  2. Copy and paste the following code into the IDL Editor:
    3. ; Display two ENVIRasters
    e = ENVI()
     
    ; Open ENVIRaster
    file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $
      SUBDIRECTORY=['data'])
    raster = e.OpenRaster(file)
     
    ; Display the data in two views
    view1 = e.GetView()
    layer1 = view1.CreateLayer(raster)
    view2 = e.CreateView()
    layer2 = view2.CreateLayer(raster, /CIR)
     
    ; Geographically link the two views
    view1.GeoLink, view2
  3. Save the program as myenvisetup.pro in your current IDL workspace.
  4. From the IDL menu bar, select Window > Preferences.
  5. Select IDL on the left side of the Preferences dialog.
  6. Click Browse next to the Startup file field, and select myenvisetup.pro.
  7. Click OK in the Preferences dialog.

Debugging

IDL has several debugging routines to locate bugs in scripts. In instances when you want a clean environment for debugging, use the .RESET_SESSION command instead of restarting IDL. We do not recommend using .FULL_RESET_SESSION unless you are developing external code.

Where to Find Help

Additional tools are available to help you learn more about ENVI API routines:

  • Start with the Routines topic and click each link to see the different groups of available routines.
  • Each routine has an associated help topic with simple code examples.
  • In ENVI Help, enter search terms in the Search window to locate API topics of interest. Or, browse through the Table of Contents under the Programming section to see a list of available routines.
  • See the Syntax Styles section for a description of the Syntax statements in API help topics.
  • While typing a routine name at the IDL command line, press Ctrl+Space to display a list of routine and variable names that begin with the characters that you typed. Then highlight an item from the Content Assist window to display the syntax for that routine. See the IDL Content Assist topic for more information.
  • Refer to IDL Help for information on using IDL routines in your scripts.