2. What’s new in CATALYST Python API¶

This section explains the new features in CATALYST by version.

2.1. What’s new in CATALYST 3.4¶

2.1.1. ECEF to WGS84 transformation¶

The new class pci.api.cts.ECEFTransform was added to represent a transformation between Earth-Centered, Earth-Fixed (ECEF) coordinates and geodetic coordinates (specifically, WGS84).

2.2. What’s new in CATALYST 3.3¶

2.2.1. CATALYST Python exceptions mapped to Python built-in errors¶

All of the exceptions raised by the CATALYST Python API or algorithms are now mapped to standard Python built-in errors. Thus, you can choose to catch CATALYST Python exceptions or standard built-in Python errors. Read the documentation for the individual CATALYST Python API exception classes, pci.exceptions, to see which Python built-in error class you can use.

2.2.2. Eliminated pci.exceptions.UnicodeSafeException¶

The pci.exceptions.UnicodeSafeException class existed to support unicode error messages in both Python 3.8 and later. Since the CATALYST Python API no longer works with Python 3.8, the class was eliminated, simplifying the CATALYST exception hierarchy. If your code catches pci.exceptions.UnicodeSafeException you must change the code to catch another class. Good candidates are pci.exceptions.PCIException and the python built-in exception Exception.

2.3. What’s new in CATALYST 3.2¶

2.3.1. Automatic handling of pathlib.Path¶

Any function that takes a string as a parameter, whether in the CATALYST Python API or PPF can now take a pathlib.Path object for this argument, and it will automatically be converted to a string.

So this example will work as expected, there is no need to manually convert the pathlib.Path object.

from pathlib import Path
from pci.api import datasource as ds

with ds.open_dataset(Path('/path/to/myfile.pix')) as dataset:
    print(f'size = {dataset.width}x{dataset.height}')

2.4. What’s new in CATALYST 3.1¶

2.4.1. Platform Agnostic Method to Check for Network / Mounted Files¶

New function pci.api.path.is_local_file() to check if a file is local.

Returns true if the file is on the local system. Returns false if the file is on a network or mounted drive.

2.4.2. Functions to test for and get the NoData value of a channel¶

New function pci.api.datasource.AuxiliaryData.get_chan_no_data_value() gets the channels no data value.

New function pci.api.datasource.AuxiliaryData.chan_has_no_data_value() tests if the channel has no data value.

2.4.3. File formats¶

All FileFormat implementations other than GDB have been removed, since this format is now capable of properly handling all supported formats.

2.4.4. Control Point Image Location¶

The implementation of pci.api.gobs.ControlPoint never actaully populated more than one image location. So, ControlPoint.image_locations has been deprecated and replaced by ControlPoint.image_location.

2.5. What’s new in CATALYST 3.0¶

2.5.1. New Global DEM function¶

New function pci.get_global_dem_filename() to get the name of the global DEM file provided by CATALYST Earth software.

2.6. What’s new in CATALYST 2.2¶

2.6.1. RPC Math Model Changes¶

New function pci.api.mathmodel.rpc_txt_to_math_model() to create an instance of an pci.api.mathmodel.RpcMathModel from an RPC TXT file.

2.6.2. Data Downloading¶

The pci.downloaders package has been modified to allow users to download VIIRS (VNP43IA2, VNP43IA4, VNP43MA2, and VNP43MA4) datatsets via the NASA CMR API.

2.7. What’s new in CATALYST 2.1¶

2.7.1. Data Downloading¶

The pci.downloaders package has been modified to allow users to download Landsat Level 2/Collection 2 images via the USGS API.

The Development Seed API has been removed, and the USGS API will be developed further to satisfy all Landsat requests.

2.7.2. New CRS and map units functions¶

Two functions, pci.api.cts.create_wgs84_crs() and pci.api.cts.create_wgs84_3d_crs(), to create pci.api.cts.CRS objects for WGS 84.

Function to create a pci.api.cts.GeocodingInfo from four corners: pci.api.cts.crs_corners_to_geocodinginfo()

Function to create a UTM map units string from a longitudate and latitude coordinate. pci.api.cts.get_utm_mapunits_from_long_lat().

Function to create a UTM map units string from a x, y, and crs (CRS) coordinate. pci.api.cts.get_utm_mapunits().

2.7.3. RPC Math Model¶

A new class pci.api.mathmodel.RpcMathModel has been added to allow creation of of Rational Polynomial Coefficient (RPC) models directly in Python from the polynomial coefficients and allows you to access additional data members that are not available in other pci.api.mathmodel.MathModel types.

2.7.4. Polygon orientation¶

A polygon’s vertices can either be oriented clockwise (like ESRI standard) or counter clockwise (like OGC Simple features standard). This release has added functionality to determine or modify the PolygonOrientation of a Shape. Additionally, you can get the orientation of an individual ring of a polygon using ring_orientation.

2.7.5. DataType name¶

The DataType object can now be created by its name.

2.7.6. Reading and Writing rasters with multiple data types¶

The ability to work with channels of different data types together has been added with the pci.api.datasource.MultitypeReader and pci.api.datasource.MultitypeWriter

2.7.7. Vector Segment Bounding Box (updated)¶

The pci.downloaders.vector.get_seg_bbox() function has been modified to return all four corners instead of just the upper left and lower right so that it will be valid for reprojected results.

2.8. What’s new in 2019¶

2.8.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.8.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.8.3. Summation¶

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

2.9. What’s new in 2018¶

2.9.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.9.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.9.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.9.4. Dataset operations (dsops)¶

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

2.9.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.9.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.9.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.9.8. ops¶

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

2.10. What’s new in 2017¶

2.10.1. NSPIO¶

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

2.10.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.10.1.2. Counter.update status messages¶

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

2.10.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.11. 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.11.1. New segment types¶

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

2.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.3. cts improvements¶

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

2.11.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.11.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.