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:
1 2 3 4 5 6 7 8 9 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 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.