How to Add a User Function to Classic ENVI

Note: This help articles applies only to the classic ENVI interface, and not to the new default interface in ENVI version 5 and later.

Adding your own IDL functions (also known as user functions) to the classic ENVI interface is easy, just follow the steps outlined below.

Once you have written or acquired the code for a user function, it is a two step process to add the function to ENVI: in the first step you add a new button to the ENVI menu for your function, and in the second you place your user function code in a directory where ENVI can find it.

Adding a menu button

You can add your new menu button anywhere you wish on either the main ENVI menu or the Display menu, or both. You can also repeat this new menu button as many times as you wish. For example, if you're adding a user function which will georeference Radarsat imagery, you might want to add this user function's button under both the Register menu and also the Radar Tools menu. Each button on the main ENVI menu and the Display menu are defined by a one-line entry in a special ASCII file called a menu file (or a .men file). The menu file for the main ENVI menu is called envi.men, and for the display menu display.men, and both are stored in the menu directory under your ENVI's installation. For default installations of ENVI X.X, you'll find the menu files in these paths:

ENVI 4.4:

Windows	drive_letter:\program files\itt\idl64\products\envi44\menu
UNIX	/usr/local/itt/idl_6.4/products/envi_4.4/menu


ENVI 3.6 to 4.3:

Windows	drive_letter:\rsi\idlXX\products\enviXX\menu
UNIX	/usr/local/rsi/idl_X.X/products/envi_X.X/menu


ENVI 3.4 and before:

Windows	drive_letter:\rsi\enviXX\menu
Macintosh	hard drive:RSI:ENVIXX:MENU
UNIX	/usr/local/rsi/envi_X.X/menu

1. Using any text editor (for example, MS Word, Wordpad, vi, or even the IDLDE editor) open the menu file of the menu where you want your user function's button to appear. The top of the menu file contains a brief explanation of how the file is organized. Following these comments, each line in the file defines one of the menu buttons. A small portion from the top of the envi.men file for ENVI 4.3 is displayed here:
   
   

   0 {File}
     1 {Open Image File} {open envi file} {envi_menu_event}
     1 {Open Vector File} {open vector file} {envi_menu_event}
     1 {Open External File} {separator}
       2 {Landsat}
         3 {Fast} {open eosat tm} {envi_menu_event}
         3 {GeoTIFF} {open tiff} {envi_menu_event}
         3 {HDF} {open envi file} {envi_menu_event}
         3 {NLAPS} {open nlaps} {envi_menu_event}

   The number at the beginning of each line defines how many levels deep the menu button is nested (beginning with zero). The text in the first set of curly brackets defines what will appear on the menu button. The instruction in the middle set of curly brackets is used internally by ENVI for advanced programmatic controls (it contains the user value for the widget button). The final set of curly brackets lists the name of the procedure that is executed when the user selects this button (i.e., this is the name of your user function's IDL procedure). When a line does not contain all of these entries but only the level number and one set of curly brackets, then it is treated as a new pull-down menu. For example, the first line in the excerpt above is a new pull-down menu labeled File, which contains a button called Open Image File. When a user chooses the button called Open Image File ENVI executes a procedure called envi_menu_event.

   Note:   When the {separator} item is added to any line in the menu file, a line will be added between the menu button where the separator is listed and the button immediately above it.

2. Scroll down into the menu file until you find the position where you want to add your user function's button. For example, if you wanted to add the new button under the Basic Tools pull-down menu then you would scroll down until you find the following section in the envi.men file:
   

     0 {Basic Tools}
     1 {Resize Data (Spatial/Spectral)} {file resize} {envi_menu_event}
     1 {Subset Data via ROIs} {subset via roi} {envi_menu_event}
     1 {Rotate/Flip Data} {file rotate} {envi_menu_event}

   • Next, simply add a new line to the menu file to define your user function's button. For example, if your user function which performs an Image to Map registration on Radarsat imagery is named warp_rsat, and is stored in a file called warp_rsat.pro, then you might add the following line to the menu file (shown in boldface font below):
     
     

       0 {Basic Tools}
       1 {Resize Data (Spatial/Spectral)} {file resize} {envi_menu_event}
       1 {Subset Data via ROIs} {subset via roi} {envi_menu_event}
       1 {Rotate/Flip Data} {file rotate} {envi_menu_event}
       1 {Register Radarsat Imagery} {not used} {warp_rsat}

     In this example, the text "not used" appears in the middle set of curly brackets. Remember, the middle set of brackets defines the button's user value, which is a special IDL widget programming control. Unless your user function's code explicitly checks for the user value of the button that was selected, the text that is placed in this position has no effect. You can even leave the middle set of curly brackets blank if you wish, although the brackets themselves must be present or ENVI will not be able to properly parse the menu file when ENVI starts up. Also, note that the final set of curly brackets contains the name of the procedure, not the name of the file that contains the procedure.

   • Save the modified menu file, overwriting the old file.

Storing your user function file where ENVI expects to find it

When ENVI starts up, it automatically checks a special directory located under the main ENVI installation called save_add to see if it contains any IDL .pro (procedure) or .sav (save) files. If any files are located they are automatically compiled or restored so that the IDL procedures or functions that they contain will be available from within the ENVI session. Thus, it is convenient to store the user function's file in this directory, especially if you have a single file that contains many separate user functions. Alternatively, if your user functions are named the same as the .pro or .sav files that contain them then you may also store them in any directory that is in the IDL path, and IDL's auto-compilation feature will automatically compile or restore the user function when needed.

A special note for ENVI users without IDL

Because ENVI without IDL is an IDL Run Time application, it can't compile any ASCII .pro files. For this reason, all user functions added to ENVI (without IDL) must be stored in binary .sav files. For more information on how to make save files for ENVI (without IDL) please see the Help Article Adapting user functions for use in ENVI without IDL.