How to use Metadata_Override to override the existing metadata object

The ENVI::OpenRaster function method creates a new ENVIRaster from a file or URI.  The Metadata_Override keyword can be used in different ways to override or update an ENVIRasterMetadata object.

Override metadata in a file

The first example is when you want to directly override metadata in the file. You may want to do this if the file’s metadata is known to be incorrect or if you want to provide a more useful value. In this example, we use the qb_boulder_msi sample dataset from the ENVI data directory in your ENVI installation:

file = e.root_dir+ 'data\qb_boulder_msi'

raster = e.OpenRaster(file)

print, raster.metadata

IDL prints:

ENVIRASTERMETADATA <400542>

BAND NAMES               = 'Band 1', 'Band 2', 'Band 3', 'Band 4'

DESCRIPTION              = 'Demo QuickBird 2 data courtesy DigitalGlobe', 'Inc.  Not for commercial use.'

SENSOR TYPE              = 'QuickBird'

WAVELENGTH               = 485.00000,      560.00000,      660.00000,       830.00000

WAVELENGTH UNITS          = 'Nanometers'

 

Let's say I wish to override the generic band names with my own names. To do so, I can set up an ENVIRasterMetadata object, set band names, and then pass it into OpenRaster as the override.

raster.Close

metadata = enviRasterMetadata();  This gives me an empty metadata object, and I can add items to it.

metadata.AddItem, 'band names', ['My First Band', 'My Second Band', 'My Third Band', 'My Fourth Band']

raster = e.OpenRaster(file, METADATA_OVERRIDE=metadata)

print, raster.metadata

Now we get the same metadata from the file, but the band names have been overridden:

ENVIRASTERMETADATA <400880>

BAND NAMES               = 'My First Band', 'My Second Band', 'My Third Band', 'My Fourth Band'

DESCRIPTION              = 'Demo QuickBird 2 data courtesy DigitalGlobe', 'Inc.  Not for commercial use.'

SENSOR TYPE              = 'QuickBird'

WAVELENGTH               = 485.00000,      560.00000,      660.00000,       830.00000

WAVELENGTH UNITS          ='Nanometers'

Add Additional Metadata to a file

The second example is when you would like to add additional metadata items to the raster which do not exist in the file metadata. For example, if I know that the solar azimuth angle for the qb_boulder_msi image is 180 degrees and the sun elevation is 50 degrees, I can add these values using the Metadata_Override and these values can later be used by ENVI’s processing tools.

raster.Close

metadata = enviRasterMetadata()

metadata.AddItem, 'sun azimuth', 180

metadata.AddItem, 'sun elevation', 50

raster = e.OpenRaster(file, METADATA_OVERRIDE=metadata)

print, raster.metadata

The new items are included in the metadata and none of the existing metadata was removed:

ENVIRASTERMETADATA <401228>

BAND NAMES               = 'Band 1', 'Band 2', 'Band 3', 'Band 4'

DESCRIPTION              = 'Demo QuickBird 2 data courtesy DigitalGlobe', 'Inc.  Not for commercial use.'

SENSOR TYPE              = 'QuickBird'

SUN AZIMUTH              = 180.00000

SUN ELEVATION            = 50.000000

WAVELENGTH               = 485.00000,      560.00000,      660.00000,       830.00000

WAVELENGTH UNITS          ='Nanometers'

Add User-Defined Metadata to a file

In the third example, let's say a user wants to add user-defined metadata. ENVI does not directly use this metadata but it can be useful for a user to have the ability to add customized information to the file for later use. A user written extension, for instance,can make use of user-defined metadata. In this example, I have a metadata tag called “atmospheric pressure.” This is not a standard tag in ENVI, but perhaps the user has an extension that uses "atmospheric pressure" when processing data. 

raster.Close

metadata = enviRasterMetadata()

metadata.AddItem, 'atmospheric pressure', 1012.1d

raster = e.OpenRaster(file, METADATA_OVERRIDE=metadata)

print, raster.metadata

My user metadata has now been added to the raster in addition to the metadata that is in the header file:

ENVIRASTERMETADATA <401566>

ATMOSPHERIC PRESSURE      ='1012.100000'

BAND NAMES               = 'Band 1', 'Band 2', 'Band 3', 'Band 4'

DESCRIPTION              = 'Demo QuickBird 2 data courtesy DigitalGlobe', 'Inc.  Not for commercial use.'

SENSOR TYPE              = 'QuickBird'

WAVELENGTH               = 485.00000,      560.00000,       660.00000,      830.00000

WAVELENGTH UNITS          ='Nanometers'

Metadata can also be added or modified once the raster is open by using enviRasterMetadata::AddItem or enviRasterMetadata::UpdateItem, but the usefulness of using Metadata_Override is that the metadata is provided immediately when the file is opened and ENVI will always use it when displaying and processing the file. Metadata_Override is particularly useful when writing batch scripts that open many files and apply the same metadata object to them. 

Metadata_Override is supported for most file formats as well as sensor products. However, some are more restrictive than others, so Metadata_Override should be used with care. For example, when an NPP VIIRS DNB file is opened in the API, ENVI returns an array of 5 raster objects. In order to use Metadata_Override when opening this file, you must provide an array of 5 metadata objects. Additionally, Metadata_Override is not allowed with any external file type.  For a list of supported files (not of External_Type), see the ENVI::OpenRaster topic in the ENVI Help.

Review on 12/31/2013 MM