Raster Metadata

The term metadata generally refers to information that describes the contents of a data file. In the context of ENVI programming, it refers to the following:

• Standard fields (or tags) that provide additional information about an image (raster) file such as band names, percentage of cloud cover, and center wavelengths in each band. See the ENVI Header Files topic for a list of standard metadata fields. Standard fields are also listed in the Metadata Viewer.
• User-defined metadata that provides extra information about a raster file. An example would be a new "Vendor" field that lists the data provider for the image. User-defined metadata are listed under the "Supplementary Metadata" category in the Metadata Viewer.

Standard and user-defined metadata are contained in a metadata object associated with a raster.

Other characteristics of a raster file that are required for ENVI to open the file are stored as properties of the raster object, rather than metadata. Examples include data type, spatial reference (map information), and acquisition time. See the ENVIRaster topic for a list of these properties.

Standard Metadata

An existing ENVIRaster's METADATA property contains a reference to the populated ENVIRasterMetadata object associated with the raster.

The following example opens a file that returns an ENVIRaster and prints all available metadata tag names and values. This is an interactive example that involves editing metadata, so type the commands shown in boldface at the IDL command line.

1. Start the ENVI application without displaying the user interface.

IDL> e = ENVI(/HEADLESS)

2. Open a raster.

ENVI> File = FILEPATH('qb_boulder_msi', $

  ROOT_DIR = e.ROOT_DIR, SUBDIR = ['data'])

ENVI> Raster = e.OpenRaster(File)

3. Get the ENVIRasterMetadata object associated with the raster's metadata.

ENVI> Metadata = raster.METADATA

4. Print a string array of tag names.

ENVI> PRINT, Metadata.TAGS

IDL prints:

SENSOR TYPE DESCRIPTION BAND NAMES WAVELENGTH UNITS WAVELENGTH

5. To get the values for a specific metadata field, use brackets and sinqle quotes as follows:

ENVI> PRINT, Metadata['WAVELENGTH']

IDL prints:

485.00000 560.00000 660.00000 830.00000

6. Print all metadata tags and values.

ENVI> PRINT, Metadata

IDL prints:

ENVIRASTERMETADATA <293209>

  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 that you want to update the WAVELENGTH values. Because WAVELENGTH is a standard metadata field, you cannot directly edit its values. Instead, create a new metadata object and override the raster's metadata with the new metadata object. The next section shows how to do this.

User-Defined Metadata

This section shows how to create an empty metadata object and populate it with user-defined metadata tags. You will then override the metadata of a raster file with the new metadata object and save the raster and metadata to a new file on disk.

1. Start the ENVI application without displaying the user interface.

IDL> e = ENVI(/HEADLESS)

2. Create a new metadata object.

ENVI> UserMetadata = ENVIRasterMetadata()

3. Populate the metadata object with new fields, where the first item is the tag and the second item is the value for the tag.

ENVI> UserMetadata.AddItem, 'wavelength units', 'micrometers'

ENVI> UserMetadata.AddItem, 'wavelength', $

  [0.660, 0.560, 0.485]

ENVI> UserMetadata.AddItem, 'production date', '2012-10-24'

ENVI> UserMetadata.AddItem, 'location', 'Boulder, Colorado, U.S.A.'

ENVI> UserMetadata.AddItem, 'vendor', 'Acme, Inc.'

4. Update one of the metadata tags.

ENVI> UserMetadata.UpdateItem, 'production date', '2012-10-23'

5. Delete one of the metadata tags.

ENVI> UserMetadata.RemoveItem, 'vendor'

6. Print the contents of the metadata object to verify that the tags are correct. The results are displayed in the IDL Console.

ENVI> PRINT, UserMetadata

7. Open the file qb_boulder_msi (included in the ENVI installation path) and override its metadata with your new metadata object. The metadata for this raster will consist of the new metadata object plus any existing metadata within the raster.

ENVI> file = FILEPATH('qb_boulder_msi', $

  ROOT_DIR = e.ROOT_DIR, SUBDIR = ['data'])

ENVI> raster = e.OpenRaster(file, METADATA_OVERRIDE = UserMetadata)

8. The raster object now contains a METADATA property. Print this property to see the metadata tags.

ENVI> metadata = raster.METADATA

ENVI> PRINT, metadata.TAGS

Notice how the metadata consists of tags from your metadata object plus others that were already part of the raster object (such as DESCRIPTION, SENSOR TYPE, and BAND NAMES).

9. Retrieve a specific value for one of the metadata tags (production date) and store it as a variable. Then print the variable.

ENVI> Sensor = metadata['sensor type']

ENVI> PRINT, Sensor

10. Save the raster file to disk as an ENVI-format file. The file is saved in the temporary directory specified in the ENVI preferences.

ENVI> outFile = e.GetTemporaryFilename('dat')

ENVI> raster.Export, outFile, 'envi'

11. Close the ENVI session.

ENVI> e.Close

12. Open ENVI with the user interface.

IDL> e = ENVI()

13. Open the new output raster file.

ENVI> raster = e.OpenRaster(outFile)

14. Get the active view.

ENVI> view = e.GetView()

15. Load the raster as a new layer.

ENVI> layer = view.CreateLayer(raster)

16. Right-click on the image layer in the Layer Manager and select View Metadata. Confirm that the raster contains the new metadata fields in addition to its standard metadata.