PCI Geomatics Help Center

How can we help you today?

Reading and Writing Metadata to Files and Channels

PCI Geomatics -


This tutorial outlines how to read and write metadata to a pix file. Specifically it looks at various functions with the Python API’s AuxiliaryData class and how they can be used to work with metadata from a PIX file.


The AuxiliaryData class includes many useful functions which make it easy to read and edit metadata. Editing metadata in Focus requires manual work, while this tutorial shows you how you can automate metadata editing using Python. You can also integrate these functions into larger batch workflows to edit metadata for multiple images at once.


  • Geomatica 2016 or later installed
  • Python 101 (basic understanding of python coding concepts)
    • How to access modules and classes
  • Some experience programming with Geomatica (recommended)

Data Package

  • Click Here to download the data required for this tutorial


The AuxiliaryData class in the Geomatica Python API allows us to access file and channel metadata from within python. This tutorial outlines how read and write metadata, including how to copy metadata from one file to another. Before you start the python script open the file Landsat_7_NS.pix in Focus. To view the file’s metadata right-click on the folder in the file tab and then click properties. To view channel metadata expand the channel list in the files tab, right-click the channel and click properties. Take note of the various metadata fields at both the file and channel level. We will be editing the file metadata, channel 1 metadata and channel 1 description in our Python script.

Fig 1: File Level Metadata before editing

Fig 2: Channel 1 Metadata before editing

Fig 3: Channel 1 Description before editing

1. Import modules and open datasets

We will make use of the Python API datasource class to get the auxiliary data from the file. Two files will be used in this script: Landsat_7_NS.pix and the raw Landsat 7 file LE70080292000195EDC00_MTL.txt.


from pci.api import datasource as ds

# open the dataset
header_file = r"I:\Data\Sensors\Landsat7\NovaScotia\LE70080292000195EDC00_MTL.txt-MS"
pix_file = r"I:\Data\Sensors\Landsat7\NovaScotia\Landsat_7_NS.pix"


2. Open the datasets and read the metadata

In able to access the datasets metadata we will have to open each dataset.

with ds.open_dataset(pix_file, ds.eAM_WRITE) as pix, ds.open_dataset(header_file, ds.eAM_READ) as mtl:

    # Reading metadata from files
    aux_mtl = mtl.aux_data
    aux_pix = pix.aux_data


You want to open the datasets in a with clause to ensure that they will be automatically closed when the clause is exited. Use ds.open_dataset to open each of the files. You will need to specify two inputs; the image and the access mode . The raw Landsat 7 image (header_file) can only be opened for reading, as we cannot edit this type of file. However, we will be copying metadata from this file to the pix file. You will notice that the pix file is opened as WRITE which means we will be able to read and write to this file.

Now that the images are open you can read in the metadata from each file. The auxiliary data and metadata about a file and the raster channels can be extracted using mtl.aux_data and pix.aux_data. The auxiliary data for the two datasets will be saved to their respective variables.

3. Working with file level metadata

We can now extract metadata information from the metadata map. There is metadata for the entire file and each channel within this map. In the code below we extract the file level metadata, create a new metadata field, copy metadata and search for a specific metadata value.

# **Working with File Level metadata**
    file_level_metadata = aux_pix.file_metadata
    print file_level_metadata

    # Get a value from the file metadata
    platform_name = aux_pix.get_file_metadata_value('PlatformName')
    print "Platform Name: " + platform_name

    # Copy metadata value from one file to another
    new_date = aux_mtl.get_file_metadata_value('Acquisition_DateTime')
    aux_pix.set_file_metadata_value("AcquisitionDate", new_date)

    print aux_pix.file_metadata


There are a number of print statements in the code above. These were added to help illustrate the output of each procedure. On line 14 the file level metadata is extracted from the pix file’s auxiliary data. The metadata will be stored in a metadata map which can be indexed like a dictionary. The metadata for the pix file looks like {Country: Canada, PlatformName: Landsat-7 ETM+, Province: Nova Scotia}. In this case Country, PlatformName and Province are the metadata key names as shown in Fig 1. The metadata map also includes the corresponding values for each key.

You can extract a value for a specific key as shown on line 18. get_file_metadata_value requires one value, the name of the metadata key. The variable platform_name now contains the value of the PlatformName key (Landsat-7 ETM+).

In the aux_pix there is no information related to the acquisition date of the image. We will copy this information from aux_mtl and add it to a new metadata value in aux_pix. On line 22 the value of the metadata field Acqusition_DateTime from the aux_mtl is saved to the variable new_date. On the next line we use set_file_metadata_value to save the value new_date to a newly created metadata field AcquisitionDate. When you print aux_pix.file_metadata you will notice that the new field has been added.

4. Working with channel level metadata

In addition to the file level metadata, aux_pix also includes the metadata for each channel. In this next section of code we extract the channel count and work with channel 1 to set a new description and delete a metadata value.

# **Working with Channel Level metadata**
    # Get the number of channels
    channel_count = aux_pix.chan_count
    print "Channel count: " + str(channel_count)

    # Set a new channel description
    chan_desc = aux_pix.get_chan_description(1)
    print "Old channel description was: " + chan_desc
    aux_pix.set_chan_description("B1: Blue (0.45-0.52)",1)

    # Delete metadata value
    aux_pix.remove_chan_metadata_value('Extra_Field', 1)

    # set the modified auxiliary data to the dataset
    pix.aux_data = aux_pix


On line 29 the channel count is extracted using chan_count. It is then printed on line 30.

The channel description for channel 1 in aux_pix is extracted on line 33. We will then change the channel 1 description on line 35 with set_chan_description. Remember that you must specify the channel number when using the channel specific functions.

On line 38 the field Extra_Field is removed using remove_chan_metadata_value. This is the final edit that we will make to the metadata.

Throughout the script so far we have been editing a copy of the metadata map, aux_pix. In order to save these changes to the actual pix file we need to set the modified auxiliary data (aux_pix) back to the dataset (pix). This is completed on line 41. You can check the Python API documentation for more information on the AuxiliaryData class.

Once you run this script you can reopen the file in Focus and view the metadata again. You will notice the changes that we made, as outlined in the following three figures.

Fig 5: File Level Metadata after editing

Fig 6: Channel 1 Metadata after editing

Fig 7: Channel 1 Description after editing

Have more questions? Submit a request


Powered by Zendesk