Getting Started with Writing ENVI API Scripts

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:

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: