How to add a Custom File Reader to Classic ENVI

The classic ENVI interface offers the ability to write a fully customized reader for unusual types of data files. This functionality allows such files to be opened and read by ENVI in their native format without the need to convert it to ENVI Image Format, and also provides a mechanism for pre-processing data on-the-fly as it is provided to ENVI.

An ENVI Custom File Reader consists of 3 parts, each a separate IDL procedure:

1. an Open routine
   
2. a Spatial Reader, and
   
3. a Spectral Reader

The custom open routine is essentially a User Function that passes the header information for the data file to ENVI. Typically the open routine will open the file using IDL File I/O conventions, extract the embedded header, close the data file, and then call ENVI_SETUP_HEAD to enter the data into the Available Bands List. If the image data in the file are in a flat binary format and no pre-processing of the data is required, then this one routine completes the Custom File Reader -- no Spatial and Spectral read routines are required -- and ENVI will automatically handle all requests for data. If the format of the data file is more complicated than flat binary, or the data require additional pre-processing, the READ PROCEDURE keyword to ENVI_SETUP_HEAD must be used to define the spatial and spectral read procedures. These procedures are automatically called by ENVI whenever there is a request for data from the file. The procedures are used to open the data file, extract the requested spatial or spectral subset, and pass this data back to ENVI.

The Open Routine

The open routine should be written as any other User Function (and perhaps added to the ENVI Menu system under the File button). When the user needs to open the data file, they choose this User Function instead of any of the other ENVI readers. A typical open routine might have the following structure:

pro OPEN_MY_CUSTOM_FILE, event

filename = ENVI_PICKFILE(title='select a custom file')
IF (filename eq "") THEN return

OpenR, unit, filename, /Get_LUN
...parse header information from the file...
Free_LUN, unit

ENVI_SETUP_HEAD,...

end

Also, if the custom file reader includes spatial and spectral read routines, these must be defined in the call to ENVI_SETUP_HEAD with the READ_PROCEDURE keyword:

ENVI_SETUP_HEAD, ...read_prodecure=["my_spatial_routine","my_spectral_routine"],...

The ENVI Header for a Special File

When ENVI_SETUP_HEAD is called in the custom open routine, the programmer has the option of writting the ENVI header file to disk (with the WRITE keyword). The ENVI header file is particularily useful because it stores ancillary information about the data file, such as its map information, that will be available whenever the data file is used in ENVI. However, if the data file remains in its native format, an ordinary ENVI header file would not provide the special instructions needed for ENVI to open the data file. In order to circumvent this problem, ENVI provides an easy mechanism for associating files of a specific format with the custom open routines that read them. This association is made through the use of a special header field called the filetype. If the filetype is defined in the ENVI header file, the associated custom open routine is called.

The menu directory in your ENVI installation tree contains a special ASCII file called filetype.txt. This file contains an index that associates custom file types with their opean routines. is organized like the ENVI menu definition files, with each line defining a specific file type according to the following format:

{file description} {filetype name} {custom open routine}

The text in the first set of curly brackets is just desciptive, the text in the second set of brackets is a unique ASCII string that defines the filetype, the text in the last set of brackets is the name of the User Function which is the custom open routine for the file. The ENVI header file contains a corresponding (optional) field for this filetype definition. If this filetype field is defined then ENVI will automatically use the custom open routine to open the file even if the generic image reader is used (i.e., File -> Open Image File). The advantage of this technique is that it allows ancillary information about the data file, such as map information, to be stored in an ENVI header even if the data file remains in its native format. Then, whenever the file is used in a future ENVI session the additional header information will be available.

In the open routine, if the header is written to a file using the /write keyword to ENVI_SETUP_HEAD, but the FILETYPE keyword is not set, then the next time the file is opened in ENVI it may be read incorrectly because of the presence of the header file. Thus, it is recommended that the header file only be written to disk if a new filetype has been defined.

Before defining the file type in the call to ENVI_SETUP_HEAD, the filetype name string (defined by the second set of curely brackets in the filetype.txt file) is used to obtain ENVI's internal integer ID for the filetype. This system is used so that ENVI can add new built-in filetypes in future releases (i.e., the filetype names will never change, but their internal integer IDs may). The batch mode routine ENVI_FILE_TYPE is used to get this integer ID. For example, if the new filetype had the following definition:

{my special file} {myfile} {open_myfile}

Then in the custom open routine, you would include the following:

filetype_id = ENVI_FILE_TYPE("myfile")
ENVI_SETUP_HEAD, ...filetype=filetype_id...

The Spatial Read Routine

- define keywords
- UNIT passed to you
- give some basic tips
- need to check for interleave
- can do ANYTHING to the data you wish

The Spectral Read Routine

- define keywords
- UNIT not passed to you, so don't forget to close the file