2. What’s new in CATALYST Python API¶

This section explains the new features in CATALYST by version.

2.1. What’s new in 2019¶

2.1.1. Data Downloading¶

The pci.downloaders package has been added to allow users to download data from various sensor APIs using one simple interface. In this release the following APIs are supported:

Copernicus API

Development Seed API (for Landsat-8 data)

NASA’s Common Metadata Repository API

Planet API

2.1.2. Model segment metadata¶

Prior to this release, unlike most other segment types, there was no object that represented a math model segment. So, while the ability to read and write a math model was available, the ability to read and write the segment metadata, description and history was not.

With the addition of MathModelIO this functionality is now available just like it is for other segment types.

2.1.3. Summation¶

A utility for summing up values while reducing numerical error can be found in pci.api.summation.

2.2. What’s new in 2018¶

2.2.1. Vectors¶

Support for vector segments has been added. A vector segment contains a collection of shapes with geometry and attributes. The geometry is stored as a tuple of numpy.ndarray with one array for each ring of the shape, and the attributes are stored as a sequence of Field.

A dataset that has vectors is represented by a pci.api.datasource.VectorDataset and a pci.api.datasource.VectorIO is used to read and write Shape, Field, or both to and from a vector segment.

2.2.2. File formats¶

The FileFormat class has been added for determining the file format of a Dataset, along with helper functions for getting the file format of a path, getting a format name, and getting the file extension of a format.

2.2.3. Swaths¶

A Dataset can have multiple swaths. You can use pci.api.datasource.get_swaths() to get the available swaths for a dataset.

2.2.4. Dataset operations (dsops)¶

The module pci.api.dsops introduces higher-order functions and decorators to simplify working with Dataset.

2.2.5. Input source¶

The module pci.api.inputsource is a framework that provides an abstraction to iterate over various sources (including file system and MFILE).

2.2.6. Path¶

The module pci.api.path contains functions to find files from various input sources. The files can be filtered by using subclasses of AbstractFilenameFilter.

2.2.7. Finder¶

The module pci.api.finder provides a framework for finding, filtering, and handling files from various input sources.

The subclasses of AbstractFilenameFinder can be used to search for files that satisfy subclasses of AbstractFilenameFilter. The resulting files can be handled by subclasses of AbstractFilenameHandler.

The module pci.api.dsfinder adds filters that can be used to test various Dataset attributes including; DataType, MathModelType, CRS.

2.2.8. ops¶

The module pci.api.ops contains various functions to compare and round floating point numbers.

2.3. What’s new in 2017¶

2.3.1. NSPIO¶

Several improvements have been made to the pci.nspio module.

2.3.1.1. Named NSPIO instances¶

When registering an NSPIO implementation, you can now specify the implementation name. You can register more than one function/class for each implementation. For more information, see NSPIO implementation naming.

You can also get a list of registered instances names by calling getInstanceNames() for each implementation. For example, you can get a list of registered counter implementations by calling Counter.getInstanceNames

2.3.1.2. Counter.update status messages¶

The Counter.update has been modified to allow for an optional status message.

2.3.1.3. Optional function arguments¶

When you write an NSPIO handler instance, you can now write a function with or without the optional argument.

For example, either of the following functions can be registered as a Counter implementation:

def update(d):
    status = '%d%% complete'.format(d*100)
    print(status)

def update_with_msg(d, msg):
    status = '%d%% complete'.format(d*100)
    if msg:
        status += ' - ' + msg
    print(status)

2.4. What’s new in 2016¶

The main features included in CATALYST 2016 are new segment types, the ability to close a Dataset, related interface changes, and added functionality to the pci.api.cts module.

2.4.1. New segment types¶

Support for additional segment types has been added in version 2016.

2.4.1.1. PCT¶

A PCT segment contains a pseudocolor table (PCT) for assigning RGB color to one-channel images. The pseudocolor table is represented by pci.api.gobs.PCT. A dataset that has a PCT is represented by a pci.api.datasource.PCTDataset and a pci.api.datasource.PCTIO is used to read and write a PCT to and from a PCT segment.

2.4.1.2. LUT¶

A LUT segment contains a lookup table (LUT) for applying enhancements to raster data. The lookup table is represented by pci.api.gobs.LUT. A dataset that has a LUT is represented by a pci.api.datasource.LUTDataset, and a pci.api.datasource.LUTIO is used to read and write a LUT to and from a LUT segment.

2.4.1.3. Text¶

A text segment contains text data. A dataset that has a text segment is represented by a pci.api.datasource.TextDataset, and a pci.api.datasource.TextIO is used to read and write a string to and from a text segment.

2.4.1.4. Array¶

An array segment contains an array of numbers. The array can be single-dimensional or multi-dimensional. The array is represented by a numpy.ndarray. A dataset that has an array is represented by a pci.api.datasource.ArrayDataset, and a pci.api.datasource.ArrayIO is used to read and write a numpy.ndarray to and from an array segment.

2.4.1.5. Orbit¶

An orbit segment contains ephemeris data related to the orbit of a sensor. The ephemeris data is represented by a pci.api.mathmodel.EphemerisData. A dataset that has an orbit segment is represented by a pci.api.datasource.EphemerisDataset, and it can be used to read and write EphemerisData to and from an orbit segment.

2.4.2. Dataset interface changes¶

In version 2016, the close member function was added to pci.api.datasource.Dataset, which you can use to specify when a file is closed.

While Dataset was a context manager in previous versions, this change ensures that it is closed when the with block is exited, where previously, this was not the case.

Additional new Dataset member functions include, synchronize to flush data to disk, is_open to check if a Dataset is open, and is_linked to check if a Dataset is a linked PIX file.

2.4.2.1. BasicReader and BasicWriter¶

Along with the addition of the close member function, the constructors of pci.api.datasource.BasicReader and pci.api.datasource.BasicWriter have been modified so that they now take a Dataset as an argument instead of filename. By doing so, a developer can ensure that the Dataset is properly closed also when using a BasicReader and BasicWriter, because it will be closed when the with block context is exited.

2.4.2.1.1. BasicReader in CATALYST 2015¶

The following example demonstrates how to read from BasicReader in version 2015:

import pci
assert pci.version[:4] == '2015' # check for version 2015

from pci.api import datasource as ds

# create a reader
reader = ds.BasicReader('myfile.pix', [1,2,3])

# read the whole raster
raster =  reader.read_raster(0, 0, reader.width, reader.height)

# there is no guarantee when the file will be closed even if it is deleted
del reader

2.4.2.1.2. BasicReader in CATALYST 2016¶

The following example demonstrates how to read from BasicReader in version 2016:

import pci
assert pci.version[:4] >= '2016'  # check for version 2016

from pci.api import datasource as ds

# open the dataset
with ds.open_dataset('myfile.pix') as dataset:
    # create a reader
    reader = ds.BasicReader(dataset, [1,2,3])

    # read the whole raster
    raster = reader.read_raster(0, 0, reader.width, reader.height)


# the with block context has exited, so the file is now closed
...

2.4.3. cts improvements¶

A few classes and functions have been added to the pci.api.cts module.

2.4.3.1. Earth models¶

The class pci.api.cts.EllipsInfo represents an ellipsoid, and the class pci.api.cts.DatumInfo represents a horizontal datum. These classes can be used to get information about Earth models.

2.4.3.2. CRS utilities¶

The functions pci.api.cts.is_crs_pixel() and pci.api.cts.is_crs_local() have been added to check the type of CRS.

Some utility functions have been added to get a string representation of a CRS including pci.api.cts.crs_to_mapunits(), pci.api.cts.crs_to_mapunits_params(), pci.api.cts.crs_to_userproj(), and pci.api.cts.crs_to_epsg().

Finally, pci.api.cts.get_utm_zone() has been added to determine the best UTM zone to use for a specified point on the Earth.