Toolbox Extensions

You can create custom IDL routines that interact with the ENVI application and perform specialized tasks. An example is processing an input dataset with your own algorithm and writing it to an output file. You can make these routines (called extensions) available from the ENVI application's Toolbox. See Example for instructions.

You can also create extensions with the ENVI Extension Wizard, which is accessed from the IDL Workbench. See the IDL Help topic "ENVI Extension Wizard" for more information.

This topic contains the following sections:

Best Practices
Build SAVE Files
Deploy Extensions
Configure the Toolbox Structure
Example

Best Practices

When writing a Toolbox extension, keep the following practices in mind:

The extension must be a procedure and should be the last routine in a .pro file of the same name.

Insert COMPILE_OPT IDL2 after the PRO statement.
Follow error-handling procedures to catch any errors in your code.
The extension can accept an event argument that contains the UVALUE set during the call to ENVI::AddExtension.
To get the current ENVI instance, use the following command:

e = ENVI(/CURRENT)

For initialization tasks while starting ENVI, or to customize the layout of your extension in the Toolbox, create a procedure named filename_extensions_init inside the filename.pro file. See Configure the Toolbox Structure.

Build SAVE Files

If you are going to provide extensions to other users who have only an ENVI runtime license or who will run the ENVI application in IDL runtime mode, you must deploy them as IDL SAVE files. See the SAVE routine in the IDL Help for more details.

SAVE files allow you to:

Distribute a Toolbox extension to an end user who does not have an ENVI+IDL license.
Hide the source code from the end user.

When building SAVE files, keep the following practices in mind:

Issue .RESET_SESSION in your IDL session to ensure you only build the SAVE file with the routines that are part of the Toolbox extension.
After issuing .RESET_SESSION, compile the routines that are used in the Toolbox extension.
Issue RESOLVE_ALL after compilation to resolve all dependencies, but exclude ENVI itself.
To ensure cross-platform compatibility, name SAVE files with all lower-case characters.

Here is an example of building a SAVE file:

.RESET_SESSION

.COMPILE emboss_band1.pro

RESOLVE_ALL, /CONTINUE_ON_ERROR, SKIP_ROUTINES='ENVI'

SAVE, FILENAME='emboss_band1.sav', /ROUTINES

Deploy Extensions

When ENVI starts, it searches three locations (and their subfolders) to find .pro and .sav extensions that should be added to the Toolbox:

Name	Location	Search Order	Access	Description
ENVI_EXTENSIONS	User-defined	1	User	An optional user-accessible location defined by an environment variable. It is useful for installing shared extensions in environments where the installation directory is not accessible.
Install directory	`Install_Dir/ENVIxx/extensions`	2	Admin	This is the preferred location for deploying extensions accessible by all users. However, administrator (admin) privileges are required to deploy here.
Preferences directory	`user_home/.idl/envi/extensionsx_x`	3	User	An extensions folder under the application user directory. Extensions deployed here are only accessible by the user account under which they were installed. You can change this directory using the Extensions File Directory entry in the ENVI Preferences dialog. This folder should not contain any `.pro` or `.sav` files that are not Toolbox extensions.
IDL package directory	Defined by the IDL_PACKAGE_PATH preference in IDL	4	User	If an IDL package that contains an ENVI toolbox extension has been installed, its directory will contain an additional `envi_extensions` subfolder. See the IPM topic in IDL Help for details.

If multiple definitions of the same extension are discovered in different locations, the first one discovered following the search order previously described will be used.

If a routine called by a Toolbox extension resides in a directory defined by !PATH, that file will be used first before ENVI searches any other location.

Note: Issue the .RESET_SESSION command if you add an extension to one of the previous directories and want the Toolbox to display the new extension in the current session.

Configure the Toolbox Structure

You can specify a folder structure where the extension will reside inside of the Toolbox. Write a custom routine filename_extensions_init (where filename is the name of the extension file) above the extension routine in your extension file. See the sample code under Example.

If ENVI discovers the filename and filename_extensions_init routines, the latter routine will be called upon application startup instead of adding the extension automatically to the Toolbox Extensions folder. If this routine does not add the extension to the Toolbox, the extension will not be automatically added.

The filename_extensions_init routine consists of two lines of code:

PRO myroutine_extensions_init

e = ENVI(/CURRENT)

e.AddExtension, 'My Routine', 'myroutine', PATH='My Routines'

END

See ENVI::AddExtension for more information.

Example

The following example shows how to create and deploy a Toolbox extension called emboss_band1 as a SAVE file. The example also shows how to rename the extension inside the Toolbox Extensions folder by adding a emboss_band1_extension_init routine to the extension file.

Create a file named emboss_band1.pro with the following contents:

PRO emboss_band1_extensions_init

COMPILE_OPT IDL2

; Get ENVI session

e = ENVI(/CURRENT)

; Add the extension to a subfolder

e.AddExtension, 'Emboss Band 1', 'emboss_band1'

END

PRO emboss_band1

COMPILE_OPT IDL2

; General error handler

CATCH, err

IF err NE 0 THEN BEGIN

CATCH, /CANCEL

IF OBJ_VALID(e) THEN $

e.ReportError,'ERROR: ' + !error_state.msg

MESSAGE,/RESET

RETURN

ENDIF

; Get ENVI session

e = ENVI(/CURRENT)

; Prompt for the input file

inFile = DIALOG_PICKFILE(DIALOG_PARENT = e.WIDGET_ID, $

TITLE='Please select input file', $

/MUST_EXIST)

; Prompt for the output file

outFile = DIALOG_PICKFILE(DIALOG_PARENT = e.WIDGET_ID, $

TITLE = 'Please select output file')

; Open the input file and display it

raster = e.OpenRaster(inFile)

view = e.GetView()

layer1 = view.CreateLayer(raster, BANDS = [0])

; Create the output

rasterNew = ENVIRaster(URI=outFile, INHERITS_FROM=raster)

; Iterate through the tiles of the original data set

; for the first band

tiles = raster.CreateTileIterator(BANDS = [0])

FOREACH tile, Tiles DO BEGIN

data = EMBOSS(tile, /EDGE_WRAP)

rasterNew.SetTile, Data, Tiles

ENDFOREACH

; Save the data and display

rasterNew.Save

layer2 = view.CreateLayer(rasterNew)

; Create a portal and flicker

portal = view.CreatePortal()

portal.Animate

END

Issue the following commands to generate a SAVE file. If emboss_band1.pro is not in the current directory of the IDL path, provide the full path in the .COMPILE command. The SAVE file will be saved to the current directory unless you specify a full path in which to save.

.RESET_SESSION

.COMPILE emboss_band1.pro

RESOLVE_ALL, /CONTINUE_ON_ERROR, SKIP_ROUTINES='ENVI'

SAVE, FILENAME = 'emboss_band1.sav', /ROUTINES

Close IDL.
Move the file emboss_band1.sav into install_dir\ENVIxx\extensions. If you do not have write permission to that directory, you can define an ENVI_EXTENSIONS environment variable that points to the directory that contains the SAVE file.
Launch ENVI from the Start menu.
In the Toolbox Extensions folder, notice that the extension Emboss Band 1 is now listed. Double-click this entry.
When prompted for the input file, select install_dir\ENVIxx\data\qb_boulder_msi.
When prompted for the output file, enter a valid filename and path.
When the script finishes executing, the original file and the new file will appear in the layer manager and a portal will flicker between the layers.