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 2.2¶
2.1.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.1.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.2. What’s new in CATALYST 2.1¶
2.2.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.2.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.2.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.2.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.2.5. DataType name¶
The DataType object can now be created by its name.
2.2.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.2.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.3. What’s new in 2019¶
2.3.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.3.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.3.3. Summation¶
A utility for summing up values while reducing numerical error can be found in
pci.api.summation.
2.4. What’s new in 2018¶
2.4.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.4.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.4.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.4.4. Dataset operations (dsops)¶
The module pci.api.dsops introduces higher-order functions and decorators to simplify
working with Dataset.
2.4.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.4.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.4.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.4.8. ops¶
The module pci.api.ops contains various functions to compare and round floating point numbers.
2.5. What’s new in 2017¶
2.5.1. NSPIO¶
Several improvements have been made to the pci.nspio module.
2.5.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.5.1.2. Counter.update status messages¶
The Counter.update has been modified to allow for an optional
status message.
2.5.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:
1def update(d):
2 status = '%d%% complete'.format(d*100)
3 print(status)
4
5def update_with_msg(d, msg):
6 status = '%d%% complete'.format(d*100)
7 if msg:
8 status += ' - ' + msg
9 print(status)
2.6. 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.6.1. New segment types¶
Support for additional segment types has been added in version 2016.
2.6.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.6.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.6.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.6.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.6.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.6.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.6.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.6.2.1.1. BasicReader in CATALYST 2015¶
The following example demonstrates how to read from BasicReader in version 2015:
1import pci
2assert pci.version[:4] == '2015' # check for version 2015
3
4from pci.api import datasource as ds
5
6# create a reader
7reader = ds.BasicReader('myfile.pix', [1,2,3])
8
9# read the whole raster
10raster = reader.read_raster(0, 0, reader.width, reader.height)
11
12# there is no guarantee when the file will be closed even if it is deleted
13del reader
2.6.2.1.2. BasicReader in CATALYST 2016¶
The following example demonstrates how to read from BasicReader in version 2016:
1import pci 2assert pci.version[:4] >= '2016' # check for version 2016 3 4from pci.api import datasource as ds 5 6# open the dataset 7with ds.open_dataset('myfile.pix') as dataset: 8 # create a reader 9 reader = ds.BasicReader(dataset, [1,2,3]) 10 11 # read the whole raster 12 raster = reader.read_raster(0, 0, reader.width, reader.height) 13 14 15# the with block context has exited, so the file is now closed 16...
2.6.3. cts improvements¶
A few classes and functions have been added to the pci.api.cts module.
2.6.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.6.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.
