This task sets metadata values for a raster file and writes the header file (.hdr) to disk. If a previous ENVI header file (.hdr) exists with the raster, this task overrides all of its metadata values.

Changing the header file of a raster can lead to unexpected situations if you run this task in the Modeler or in a batch program. An alternative is to use the EditRasterMetadata task, as it will not change the input raster. Using the EditRasterMetadata task will create a copy of the input raster with the edited metadata.

Tip: For rasters that already have an associated header file, use the ENVIRasterMetadata::UpdateItem method to edit metadata fields, then use the ENVIRaster::Save method to save the updates to the header file on disk.

Example

; Start the application
e = ENVI()
 
; Generate raster data.
data = Bytarr(500,500,3)
data[*,*,0] = Bytscl(Dist(500))
data[*,*,1] = Shift(Bytscl(Dist(500)),167,167)
data[*,*,2] = Shift(Bytscl(Dist(500)),334,334)
 
; Save the data to a raster object.
raster = ENVIRaster(data)
raster.Save
filename = raster.URI
 
; Get the task from the catalog of ENVITasks
Task = ENVITask('SetRasterMetadata')
 
; Define required metadata
Task.INPUT_RASTER = raster
Task.BYTE_ORDER = 'Network (IEEE)'
Task.DATA_TYPE = 'Byte'
Task.FILE_TYPE = 'ENVI'
Task.INTERLEAVE = 'BSQ'
Task.NBANDS = 3
Task.NCOLUMNS = 500
Task.NROWS = 500
 
; Define optional metadata
Task._DESCRIPTION = 'This is a test image.'
 
; Run the task
Task.Execute
 
; When the task runs, it closes the raster in order to 
; create the header file. Re-open the raster.
raster = e.OpenRaster(filename)
 
; Display the result
View1 = e.GetView()
Layer1 = View1.CreateLayer(raster)

Syntax

Result = ENVITask('SetRasterMetadata')

Input parameters (Set, Get): ACQUISITION_TIME, AUXILIARY_RPC_SPATIALREF, BAND_NAMES, BBL, BYTE_ORDER, CLASS_LOOKUP, CLASS_NAMES, CLASSES, CLOUD_COVER, COLOR_TABLE, COMPLEX_FUNCTION, DATA_GAIN_VALUES, DATA_IGNORE_VALUE, DATA_OFFSET_VALUES, DATA_REFLECTANCE_GAIN_DATA_REFLECTANCE_GAIN_VALUES, DATA_REFLECTANCE_OFFSET_VALUES, DATA_TYPE, DEFAULT_BANDS, DEFAULT_STRETCH, DEM_BAND, DEM_FILE, _DESCRIPTION, FILE_TYPE, FWHM, HEADER_LOCATION, HEADER_OFFSET, INPUT_RASTER, INTERLEAVE, NBANDS, NCOLUMNS, NROWS, OUTPUT_RASTER_URI, PRODUCT_TYPE, READ_PROCEDURES, REFLECTANCE_SCALE_FACTOR, SECURITY_TAG, SENSOR_TYPE, SOLAR_IRRADIANCE, SPATIALREF, SUN_AZIMUTH, SUN_ELEVATION, WAVELENGTH, WAVELENGTH_UNITS, X_START, Y_START, Z_PLOT_RANGE, Z_PLOT_TITLES

Output parameters (Get only): OUTPUT_RASTER

Parameters marked as "Set" are those that you can set to specific values. You can also retrieve their current values any time. Parameters marked as "Get" are those whose values you can retrieve but not set.

Input Parameters

ACQUISITION_TIME (optional)

Specify a string with the acquisition time, conforming to the ISO-8601 standard. The string 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.

AUXILIARY_RPC_SPATIALREF (optional)

Specify an ENVIRPCRasterSpatialRef object that provides secondary map information (if any) for the raster, in addition to its standard map information.

BAND_NAMES (optional)

Specify a string array with the names of raster bands.

BBL (optional)

Specify an integer array with the same number of elements as BAND_NAMES, where 0 indicates a bad band and 1 indicates a good band. This parameter is typically used with hyperspectral imagery.

BYTE_ORDER (required)

Specify one of the following strings, indicating the byte order of the raster:

  • Host (Intel): Least significant byte first; typically DEC and MS-DOS systems
  • Network (IEEE): Most significant byte first; all other platforms

This parameter applies to imagery with integer, long integer, 64-bit integer, unsigned 64-bit integer, floating point, double precision, and complex data types.

CLASS_LOOKUP (optional)

Specify a (3, n) byte array, where n is the number of classes, with RGB color definitions for each class in a classification file. For example, black is [0,0,0].

CLASS_NAMES (optional)

Specify a string array of class names in a classification file, where the number of elements must equal the number of classes.

CLASSES (optional)

Specify an unsigned integer value with the number of classes (including unclassified regions) in a classification file.

CLOUD_COVER (optional)

Specify a floating-point value (0 to 100.0) with the percentage of cloud cover within the raster.

COLOR_TABLE (optional)

Specify a (3, 256) byte array representing the full color table to use when displaying this raster.

COMPLEX_FUNCTION (optional)

Specify one of the following strings indicating the values to calculate from a raster with a complex data type. This will also determine what to use for displaying the image, for calculating statistics for the image, or for writing the image to a new file.

  • Imaginary
  • Magnitude
  • Phase
  • Power
  • Real

DATA_GAIN_VALUES (optional)

Specify a double-precision array of gain values for each band. Units are W/(m2 * µm * sr).

DATA_IGNORE_VALUE (optional)

Specify an integer indicating the pixel value that should be ignored in image processing.

DATA_OFFSET_VALUES (optional)

Specify a double-precision array of offset values for each band.

DATA_REFLECTANCE_GAIN_VALUES (optional)

Specify a double-precision array of reflectance gain values.

DATA_REFLECTANCE_OFFSET_VALUES (optional)

Specify a double-precision array of reflectance offset values.

DATA_TYPE (required)

Specify one of the following strings indicating the data type of the raster pixel data:

  • Byte
  • Complex
  • Double
  • Double-precision Complex
  • Float
  • Integer
  • Long Integer
  • Unsigned Integer
  • Unsigned Long Integer
  • 64-bit Long Integer
  • 64-bit Unsigned Long Integer

DEFAULT_BANDS (optional)

Specify an unsigned integer array of band numbers to automatically load into the current view every time the raster is opened.

DEFAULT_STRETCH (optional)

Specify one of the following strings indicating the stretch to apply when ENVI display the raster:

  • equalization
  • gaussian
  • linear range
  • logarithmic
  • x% linear (for example, 5% linear)
  • optimized linear
  • square root

DEM_BAND (optional)

Specify an unsigned integer indicating the index (starting at 1) of a selected DEM band associated with the raster, as indicated by the DEM_FILE parameter. If the DEM file contains a single band, or if you choose the first band of the input raster, the DEM_BAND value defaults to 0.

DEM_FILE (optional)

Specify a string with the fully qualified path and filename of a DEM associated with the raster.

_DESCRIPTION (optional)

Specify a string that describes the image or the processing performed.

FILE_TYPE (required)

Specify one of the following strings indicating the file format of the raster:

  • BIL
  • Custom
  • DTED
  • ENVI (default)
  • ENVI Meta File
  • GDB
  • GRID
  • HDF5
  • IMAGINE
  • JPEG
  • JPEG2000
  • MrSID
  • NITF
  • SERIES
  • TIFF

FWHM (optional)

Specify a double-precision array of full-width-half-maximum (FWHM) values of each band in the raster.

HEADER_LOCATION (optional)

Specify one of the following strings indicating where to save the associated header file (.hdr) after setting the raster metadata:

  • Same as raster file: (default)
  • Auxiliary File Directory: The directory specified in the Auxiliary File Directory field of the ENVI Preferences file.

HEADER_OFFSET (required)

Specify an unsigned integer value with the number of bytes of embedded header information present in the file. ENVI skips these bytes when reading the file. The default value is 0.

INPUT_RASTER (required)

Specify a raster on which to set the metadata values.

INTERLEAVE (required)

Specify one of the following strings indicating the data interleave of the raster. The default is BSQ.

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

NBANDS (required)

Specify an unsigned integer with the number of bands in the raster.

NCOLUMNS (required)

Specify an unsigned integer with the number of columns in the raster.

NROWS (required)

Specify an unsigned integer with the number of lines in the raster.

OUTPUT_RASTER_URI (optional)

Specify a string with the fully qualified filename and path of the associated OUTPUT_RASTER.

  • If you do not specify this parameter, or set it to an exclamation symbol (!), ENVI creates a temporary file.
  • If you set it to the hash symbol (#), ENVI creates a file in the temporary directory, but this file will not be deleted when ENVI closes.

PRODUCT_TYPE (optional)

Specify one of the following strings indicating the product type, if the raster is a DigitalGlobe dataset:

  • Basic Product
  • Stereo Product
  • Standard Product
  • Orthorectified Product
  • Digital Elevation Model Product

For Suomi NPP VIIRS datasets:

  • SDR
  • EDR

READ_PROCEDURES (optional)

Specify a two-element string array with the names of spatial and spectral read routines for ENVI Classic file readers.

REFLECTANCE_SCALE_FACTOR (optional)

Specify a floating-point value that, when divided into the pixel data, would scale it from 0-1 reflectance. For example, if the value of 10,000 in the pixel data represents a reflectance value of 1.0, enter a reflectance scale factor of 10,000.

SECURITY_TAG (optional)

Specify a string with security information inherited from formats that typically contain security classification levels (such as NITF).

SENSOR_TYPE (optional)

Specify one of the following strings, indicating the sensor type of the input raster. Strings are case-sensitive.

AATSR

MASTER

ADAR

MERIS

ADEOS

MIVIS

ADRG

MODIS

Air Photo

MOMS-02

AIRSAR

NAXAR-LEGION

AISA

NIGERIASAT

ALOS

NIGERIASAT-2

ALSAT

NPP VIIRS

ALSAT-2A

OrbView-3

ALSAT-2B

PACE-OLI

ALSAT-1B

PeruSat

ASAR

PINEO-4

ASTER

PINEO-3

AVHRR

PlanetScope

AVIRIS

PLEIADES-1A

BEIJING

PLEIADES-1B

Capella

PRISMA

CARTOSAT-1

PROBA-V

CASI

QuickBird

COSMO-SkyMed

RADARSAT

DEIMOS-2

RADARSAT-2

DEIMOS-1

RapidEye

DMC

RASAT

DMSP

ResourceSat2 AWiFS

Dragonette

ResourceSat2 LISS-III

DUBAISAT-2

ResourceSat2 LISS-IV

DUBAISAT-1

Scanned Image

EnMAP

SEAWIFS

EO-1 ALI

SEBASS

EO-1 Hyperion

Sentinel-3

EROS

Sentinel-2

ERS

Sentinel-2A

FORMOSAT-2

Sentinel-2B

FormoSat-5

Sentinel-1

GeoEye-1

SIR-C

GEOSCAN

SkySat-1

GER63

SPIN-2

GF-2

SPOT

GF-1

SPOT-7

GOES-16

SPOT-6

GOES-R

SSOT

GOKTURK-2

STRM

Goturk-1

SuperView-1

GRUS

TerrSAR-X

Himawari-9

THEOS-2

Himawari-8

TIMS

HYDICE

TMS

HyMap

TRWIS III

Hyperion

UK-DMC

ICEYE

UK DMC2

IKONOS

Umbra

IRS LISSIII

Unknown

IRS Pan

UrtheCastTheia

IRS WIFS

USGS DEM

JERS-1

VNREDSAT-1

Julin-1

WorldView-2

KOMPSAT-3

WorldView-1

KOMPSAT-2

WORLDVIEW-4

Landsat ETM

WORLDVIEW-3

Landsat ETM+

X-SAR

Landsat MSS

ZhulHai-1

Landsat OLI

ZY3-1

Landsat OLI-2

ZY-1-02C

Landsat TIR

ZY-1-02D

Landsat TIRS-2

ZY1E

Landsat TM

 

LeicaADS

 

MAS

 

SOLAR_IRRADIANCE (optional)

Specify a double-precision array of top-of-atmosphere solar irradiance values per band. Units are W/(m2 * µm).

SPATIALREF (optional)

Specify an ENVIPseudoRasterSpatialRef, ENVIRPCRasterSpatialRef, or ENVIStandardRasterSpatialRef object that indicates the spatial reference of the raster.

SUN_AZIMUTH (optional)

Specify a double-precision value with the angle of the sun (in degrees) from due north in a clockwise direction.

SUN_ELEVATION (optional)

Specify a double-precision value with the angle of the sun (in degrees) above the horizon.

WAVELENGTH (optional)

Specify a double-precision array that lists the center wavelength values of each band in an image. Units should be the same as those used for the FWHM parameter and also set in the WAVELENGTH_UNITS parameter.

WAVELENGTH_UNITS (optional)

Specify one of the following strings indicating the units of the wavelengths in the WAVELENGTH parameter. The default value is Nanometers.

  • GHz
  • Index
  • MHz
  • Micrometers
  • Nanometers
  • Wavenumber
  • Unknown

X_START (required)

Specify an unsigned integer with the X image coordinate for the upper-left pixel in the image. Images that are spatial subsets of larger images often use an image coordinate system that references the parent (or larger) image so that you can link and dynamically overlay the two images. The default value is 0.

Y_START (required)

Specify an unsigned integer with the Y image coordinate for the upper-left pixel in the image. Images that are spatial subsets of larger images often use an image coordinate system that references the parent (or larger) image so that you can link and dynamically overlay the two images. The default value is 0.

Z_PLOT_RANGE (optional)

Specify a two-element double-precision array with the default minimum and maximum values for Z (spectral) plots.

Z_PLOT_TITLES (optional)

Specify a two-element string array with the X-axis and Y-axis titles for Z (spectral) plots.

Output Parameters

OUTPUT_RASTER

Updating the header file requires closing the raster. Use this parameter to reopen and return a reference to the raster.

Methods

Execute

Parameter

ParameterNames

Properties

DESCRIPTION

DISPLAY_NAME

NAME

REVISION

TAGS

Version History

ENVI 5.3

Introduced

ENVI 5.5

Changed the OUTPUT_RASTER_URI parameter to be required.

ENVI 5.7

Added the COLOR_TABLE parameter.

See Also

ENVITask, EditRasterMetadata task, ENVISubsetRaster, ENVIRasterMetadata, ENVIRaster::WriteMetadata, ENVIRaster::Save, Raster Metadata (ENVI API Programming), ENVI Header Fields