Use this procedure to create header information for a disk file. In order for disk files to be used in ENVI Classic, they need the associated header information. The required keywords (DATA_TYPE, INTERLEAVE, NB, NL, NS, OFFSET) define the basic set of information needed to access the data in the file. The optional keywords allow you to define more specific file information.

In memory, data files do not need to call ENVI_SETUP_HEAD. Instead, they use ENVI_ENTER_DATA.

Syntax

ENVI_SETUP_HEAD [, ACQUISITION_TIME=variable] [, BBL=array{0 | 1}] [, BNAMES=string array] [, BYTE_ORDER=variable], CLASS_NAMES=string array [, CLOUD_COVER=variable] [, DATA_GAINS=variable] [, DATA_IGNORE_VALUE=variable] [, DATA_OFFSETS=array], DATA_TYPE={1 | 2 | 3 | 4 | 5 | 6 | 9 | 12 | 13 | 14 | 15} [, DEF_BANDS=array] [, DEF_STRETCH=value] [, DESCRIP=string] [, FILE_TYPE=variable], FNAME=string [, FUNC_COMPLEX={0 | 1 | 2 | 3 | 4}] [, FWHM=array] [, GEO_POINTS=array] [, INFO=value] [, INHERIT=value], INTERLEAVE={0 | 1 | 2} [, LOOKUP=array] [, MAP_INFO=structure], NB=integer, NL=integer, NS=integer [, NUM_CLASSES=integer], OFFSET=integer [, /OPEN] [, PIXEL_SIZE=array] [, POINTER_INFO=structure] [, R_FID=variable] [, READ_PROCEDURE=variable] [, REFLECTANCE_SCALE_FACTOR=variable] [, SENSOR_TYPE=integer] [, SOLAR_IRRADIANCE=variable] [, SPEC_NAMES=variable] [, SUN_AZIMUTH=variable] [, SUN_ELEVATION=variable] [, UNITS=integer] [, WAVELENGTH_UNIT={0 | 1 | 2 | 3 | 4 | 5 | 6}] [, WL=array] [, /WRITE] [, XSTART=integer] [, YSTART=integer] [, ZPLOT_AVERAGE=array] [, ZPLOT_TITLES=string array] [, ZRANGE=array]

Keywords

ACQUISITION_TIME (optional)

Use this keyword to specify a named variable containing a string with the date and time when the image was acquired. This string conforms to the ISO-8601 standard and can be in any of the following formats:

YYYY-MM-DD
YYYY-MM-DDTHH:MM:SS.DZ
YYYY-MM-DDTHH:MM:SS:Dooo:mm

Where:

  • YYYY is the four-digit year
  • MM is the two-digit month
  • DD is the two-digit day
  • T separates the date and time
  • HH is the two-digit hour
  • MM is the two-digit minute
  • SS is the two-digit second
  • D is the decimal fraction of a second with up to double-precision
  • Z indicates that the time is in Coordinate Universal Time (UTC)
  • ooo is a two-digit offset in hours from UTC time. If the offset is negative, a minus symbol (-) precedes the value.
  • mm is an optional partial-hour offset (in minutes) from UTC time.

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 (with num_band elements) of 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 1 for big-endian data (generated on SUN, SGI, and PowerMac platforms) or to 0 for little-endian data (generated on PC x86). The default value is the byte order of your platform.

CLASS_NAMES

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.

CLOUD_COVER (optional)

Use this keyword to specify a named variable that contains the percentage of cloud cover in the image (0 to 1.0).

DATA_GAINS (optional)

Use this keyword to specify a named variable that contains an array of gain values for each band in the dataset.

DATA_IGNORE_VALUE (optional)

Use this keyword to specify a named variable that contains a scalar number representing the data value to ignore in the dataset. If set, DATA_IGNORE_VALUE is the same type as the input dataset, and an undefined ignore value is represented by the double-precision number 1e-34. Currently, this value is used only in user-written ENVI Classic code.

DATA_OFFSETS (optional)

Use this keyword to specify a named variable that contains an array of offsets for each band in the dataset.

DATA_TYPE

Use this keyword to specify the IDL data type of the file, using the following IDL convention.

  • 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

DEF_BANDS (optional)

Set this keyword to a one- or three-element array specifying which bands to display upon opening the file in ENVI Classic. If you set DEF_BANDS to a one-element array, ENVI Classic loads a grayscale image in the display group. If you set DEF_BANDS to a three-element array, ENVI Classic 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 stretch information. 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.

FNAME

Use this keyword to specify the name and path of the disk file. FNAME is a string variable that ENVI Classic uses to open the file for reading.

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: sqrt[(real)2 + (imaginary)2]
  • 2: Real: The real portion of the complex number
  • 3: Imaginary: The imaginary part of the complex number
  • 4: Phase: arctan(imaginary/real)

Note: 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

INFO (optional)

Use this keyword to store information that is passed 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

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.

OFFSET

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

OPEN (optional)

Set this keyword to add the file to the Available Bands List. The default is not to add the file to this list.

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 representing the x and y pixel sizes, respectively.

POINTER_INFO (optional)

If FILE_TYPE='HDF SD', use this keyword to specify an anonymous structure containing data_set and ndims fields. The data_set field is a long integer indicating the HDF SD dataset index in the HDF file. The ndims field is a long integer indicating the number of dimensions of data_set.

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.

REFLECTANCE_SCALE_FACTOR (optional)

Use this keyword to specify a named variable that contains a single scalar number used to convert the input data into reflectance. For example, you can use REFLECTANCE_SCALE_FACTOR to convert integer scaled reflectance data into floating-point [0, 1] reflectance values.

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.

SOLAR_IRRADIANCE (optional)

Use this keyword to specify a named variable that denotes the top-of-atmosphere solar irradiance per band. Units are W/(m2 * µm).

SPEC_NAMES (optional)

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

SUN_AZIMUTH (optional)

Use this keyword to specify a named variable with the angle of the sun (in degrees) from due north in a clockwise direction.

SUN_ELEVATION (optional)

Use this keyword to specify a named variable with the angle of the sun (in degrees) above the horizon.

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_UNIT (optional)

Use this keyword to specify a named variable that contains a value indicating the wavelength units. The valid values are as follows:

  • 0: Micrometers
  • 1: Nanometers
  • 2: Wavenumber
  • 3: GHz
  • 4: MHz
  • 5: Index
  • 6: Unknown

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.

WRITE (optional)

Set this keyword to write an output header to disk. The default is to not write an output header. It is valid to add a file to the Available Bands List (using the keyword OPEN) and not write the header file to disk. You should always set the WRITE keyword for files that you wish to open in a later ENVI Classic session.

XSTART (optional)

Use this keyword to specify the x starting sample for the first pixel in the file. The default is 0. Use XSTART in conjunction with YSTART to preserve the spatial reference for subsetted files. When processing a file, the XSTART of the output file is typically set 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 is 0. Use YSTART in conjunction with XSTART to preserve the spatial reference for subsetted files. When processing a file, the YSTART of the output file is typically set 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 representing the x and y window size (in pixels) for the Z Profile. The window size must be a value of 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 with the x-axis and y-axis plot titles. 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.