This routine is obsolete and has been replaced with the ENVIRaster::Save and ENVIRaster::Export methods.

Use this procedure to convert an IDL image array in memory to an ENVI-format image. The input data are dimensioned as either BSQ [samples, lines, bands], BIL [samples, bands, lines], or BIP [bands, samples, lines]. The resulting image can either be stored as a disk file with an associated header file or stored in memory.

Syntax

ENVI_WRITE_ENVI_FILE, Data [, BBL=array] [, BNAMES=string array] [, BYTE_ORDER=variable] [, CLASS_NAMES=string array] [, /COMPRESSION] [, DEF_BANDS=array] [, DEF_STRETCH=value] [, DESCRIP=string] [, FILE_TYPE=variable] [, FUNC_COMPLEX={0 | 1 | 2 | 3 | 4}] [, FWHM=array] [, GEO_POINTS=array] [, /IN_MEMORY] [, INFO=value] [, INHERIT=value] [, INTERLEAVE={0 | 1 | 2}] [, LOOKUP=array] [, MAP_INFO=structure], NB=integer, NL=integer, NS=integer [, NUM_CLASSES=integer] [, /NO_COPY] [, /NO_OPEN] [, /NO_WRITE], OFFSET=value [, OUT_DT={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15}], OUT_NAME=variable [, PIXEL_SIZE=array] [, R_FID=variable] [, READ_PROCEDURE=variable] [, SENSOR_TYPE=integer] [, SPEC_NAMES=variable] [, UNITS=integer] [, WAVELENGTH_UNITS={0L | 1L}] [, WL=array] [, XSTART=integer] [, YSTART=integer] [, ZPLOT_AVERAGE=array] [, ZPLOT_TITLES=string array] [, ZRANGE=array]

Arguments

Data

This is a 2D or 3D data array of type byte, integer, unsigned integer, long integer, unsigned long integer, long 64-bit integer, unsigned long 64-bit integer, floating-point, double-precision, complex, or double-precision complex. The data may be in BSQ, BIL, or BIP storage order. The DATA array will be converted to an ENVI-format image.

Keywords

BBL (optional)

Use this keyword to specify an array of ones and zeros representing the good and bad bands, respectively. The number of elements in BBL must be equal to the number of bands in the image.

BNAMES (optional)

Use this keyword to specify the band names assigned to the data. BNAMES is a string array of size num_bands with band names. The default band names are ['band 1', 'band 2', etc.]

BYTE_ORDER (optional)

Use this keyword to specify a variable that contains a flag indicating the byte order of the data. Set BYTE_ORDER to a value of 1 for big-endian data (generated on SUN, SGI, and PowerMac platforms) or to a value of 0 for little-endian data (generated on PC x86). The default value is the byte order of your platform.

CLASS_NAMES (optional)

Use this keyword to specify a string array of class names for classification images. The first element (Class 0) is “Unclassified.” Only use CLASS_NAMES if the result is a classification image, in which case this keyword is required. If the result is not a classification image, this keyword is optional.

COMPRESSION (optional)

Set this keyword to write the file using the standard GZIP format. IDL’s GZIP support is based on the freely available ZLIB library by Mark Adler and Jean-loup Gailly (see http:\\www.zlib.net for details). This means that IDL’s compressed files are 100% compatible with the widely available gzip and gunzip programs.

DEF_BANDS (optional)

Set this keyword to a one- or three-element array specifying which bands to display upon opening the file in ENVI. If you set DEF_BANDS to a one-element array, ENVI loads a grayscale image in the display group. If you set DEF_BANDS to a three-element array, ENVI loads an RGB image in the display group. The values are zero-based. To load bands 4, 3, and 2 of a 7-band image, set DEF_BANDS to [3, 2, 1].

DEF_STRETCH (optional)

Use this keyword to specify the default contrast stretch to use whenever the image is displayed. Set DEF_STRETCH equal to the value returned from ENVI_DEFAULT_STRETCH_CREATE.

DESCRIP (optional)

Use this keyword to specify a text description of the data or of the type of processing performed.

FILE_TYPE (optional)

Use this keyword to specify a named variable that contains the integer file type value. See ENVI_FILE_TYPE for details on how to determine this value.

FUNC_COMPLEX (optional)

Set this keyword to one of the following values to specify the complex lookup function that determines how to display complex data.

  • 0: Power (default): The natural log of the magnitude
  • 1: Magnitude:
  • 2: Real: The real portion of the complex number
  • 3: Imaginary: The imaginary part of the complex number
  • 4: Phase:

Only set this keyword if the IDL data type of the image is complex or double-precision complex.

FWHM (optional)

Use this keyword to specify an array of FWHM responses for each band. The number of elements in this array is equal to the number of bands in the image.

GEO_POINTS (optional)

Use this keyword to specify a 16-element array of double-precision, floating-point values representing geographic coordinates for the upper-left, upper-right, lower-left, and lower-right corners of the image. The array consists of four groups of x and y pixel locations and their corresponding latitude and longitude values with the form [x, y, lat, lon]. South latitudes and west longitudes have negative values. The array is defined as follows:

  • GEO_POINTS[0:3]: Upper left
  • GEO_POINTS[4:7]: Upper right
  • GEO_POINTS[8:11]: Lower left
  • GEO_POINTS[12:15]: Lower right

IN_MEMORY (optional)

Set this keyword to specify that output should be stored in memory. If you do not set IN_MEMORY, output will be stored on disk and you must specify OUT_NAME (see below).

INFO (optional)

Use this keyword to store information to pass to your spatial and spectral readers. INFO is retrieved from ENVI_FILE_QUERY using the keyword H_INFO, which is a handle to the data. Use HANDLE_VALUE and the handle H_INFO to retrieve the data for INFO.

INHERIT (optional)

Use this keyword to specify the file inheritance. Set INHERIT equal to the value returned from ENVI_SET_INHERITANCE.

INTERLEAVE (optional)

Set this keyword to one of the following integer values to specify the interleave output:

  • 0: BSQ
  • 1: BIL
  • 2: BIP

LOOKUP (optional)

Use this keyword to specify an array of long integers representing class RGB values. The LOOKUP array contains an RGB triplet for each class specified by the keyword NUM_CLASSES. The dimensions of the array are [3, num_classes+1], and the RGB triplet is ordered [r, g , b]. You must set LOOKUP when entering a classification image.

MAP_INFO (optional)

Use this keyword to specify map information. Set MAP_INFO equal to the structure returned from ENVI_MAP_INFO_CREATE.

NB

Use this keyword to specify the number of bands in the file.

NL

Use this keyword to specify a the number of lines in the file.

NS

Use this keyword to specify the number of samples in the file.

NUM_CLASSES (optional)

Use this keyword to specify the number of classes for classification files. Remember to include Class 0 (“Unclassified”) in the number of classes. You should only use this keyword for classification files.

NO_COPY (optional)

Set this keyword to prohibit duplicating the Data array on output. If you set this keyword, the Data argument array is incorporated into the ENVI session directly, rendering the variable Data undefined after the call to ENVI_WRITE_ENVI_FILE. The default is to make a copy of the data.

NO_OPEN (optional)

Set this keyword to prohibit adding the output file to the Available Bands List. The default is to add the output file to this list.

NO_WRITE (optional)

Set this keyword to prohibit writing an output header file to disk. The default is to write an output header. It is valid to add a file to the Available Bands List and not write the header file to disk. If you set the NO_WRITE keyword, you have to manually specify the file parameters when you open the file in a later ENVI session. The keyword has no effect when you set the keyword IN_MEMORY.

OFFSET

Use this keyword to specify the offset (in bytes) to the start of the data in the file.

OUT_DT (optional)

This keyword indicates the IDL data type of the output data. Set the keyword to one of the following integer values. The default output data type is the same as the input data type.

  • 1: Byte (8 bits)
  • 2: Integer (16 bits)
  • 3: Long integer (32 bits)
  • 4: Floating-point (32 bits)
  • 5: Double-precision floating-point (64 bits)
  • 6: Complex (2x32 bits)
  • 9: Double-precision complex (2x64 bits)
  • 12: Unsigned integer (16 bits)
  • 13: Unsigned long integer (32 bits)
  • 14: Long 64-bit integer
  • 15: Unsigned long 64-bit integer

OUT_NAME (optional)

Use this keyword to specify a string with the output filename for the resulting data. If you set the keyword IN_MEMORY, you do not need to specify OUT_NAME.

PIXEL_SIZE (optional)

Use this keyword to specify the pixel size of images that are not georeferenced. PIXEL_SIZE is a two-element array of floating-point values specifying the x and y pixel sizes, respectively.

R_FID (optional)

ENVI Classic library routines that result in new images also have an R_FID, or “returned FID.” This is simply a named variable containing the file ID to access the processed data. Specifying this keyword saves you the step of opening the new file from disk.

READ_PROCEDURE (optional)

Use this keyword to specify a named variable that contains a string array of the procedure names for the spatial and spectral readers, respectively.

SENSOR_TYPE (optional)

Use this keyword to specify an integer value related to the sensor type. See ENVI_SENSOR_TYPE for details on how to determine the integer sensor type value.

SPEC_NAMES (optional)

Use this keyword to specify a named variable that contains a string array of spectral library names. Only set this keyword for a spectral library file.

UNITS (optional)

Use this keyword to specify the PIXEL_SIZE units for images that are not georeferenced. UNITS is an integer value returned from ENVI_TRANSLATE_PROJECTION_UNITS. Georeferenced images do not use this value. Instead, they use the pixel size and units contained in the map information structure.

WAVELENGTH_UNITS (optional)

Use this keyword to specify the wavelength units. Set to 0L for micrometers, or set to 1L for nanometers.

WL (optional)

Use this keyword to specify an array of wavelength values. The number of elements in this array is equal to the number of bands.

XSTART (optional)

Use this keyword to specify the x starting sample for the first pixel in the file. The default value is 0. Use XSTART in conjunction with YSTART to preserve the location within the original file for subsetted files. When processing a file, you typically set the XSTART of the output file to the XSTART of the input file, plus the value of DIMS[1] (the starting sample).

YSTART (optional)

Use this keyword to specify the y starting line for the first pixel in the file. The default value is 0. Use YSTART in conjunction with XSTART to preserve the spatial reference for subsetted files. When processing a file, you typically set the YSTART of the output file to the YSTART of the input file, plus the value of DIMS[3] (the starting line).

ZPLOT_AVERAGE (optional)

Use this keyword to specify a two-element array of long integers for the x and y window size (in pixels) for the Z Profile. The window size must be 1 or greater. The Z Profile is formed from the average of the profiles within the specified window. The default window size is [1, 1].

ZPLOT_TITLES (optional)

Use this keyword to specify a two-element string array for x- and y-axis titles for any spectral plots derived from the image. The default x-axis title is “Band Number” for images with no wavelength information and “Wavelength” for images with wavelength information. The default y-axis title is “Value.”

ZRANGE (optional)

Use this keyword to specify a 2D array for the lower and upper spectral plot range.