3.3.4. pci.api.datasource module

This module handles the reading and writing of datasets. Using the classes in this module, you can read and write different types of data from datasets, including raster data, metadata, coordinate systems, math models, control points, look-up tables, and more.

3.3.4.1. Dataset

class pci.api.datasource.Dataset

Bases: Boost.Python.instance

This class represents a dataset stored in a file, database, or some other data store mechanism. The dataset may or may not exist. Dataset cannot be instantiated directly. It must be opened using open_dataset(), open_dataset_format(), new_dataset(), or create_linked_pix().

Note, the dataset must be closed before calling PCI algorithms such as ortho and autogcp, otherwise unpredictable results and errors may occur.

Dataset is a context manager, which means that it can be used in a with statement.

Here is a quick example of how to write a crs to disk.

1
2
3
4
5
6
7
 from pci.api import datasource as ds

 def write_crs(uri, crs):
    'Write the specified crs to the dataset specified by uri.'
    with ds.open_dataset(uri, ds.eAM_WRITE) as dataset:
        # the crs will be flushed to disk when with clause exits.
        dataset.crs = crs
add_event((Dataset)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new file level HistoryEvent for this dataset. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

property aux_data

The AuxiliaryData for the dataset. Using this property gives you a copy of this object’s AuxiliaryData. If you wish to modify the contents of the object’s AuxiliaryData, you have to reassign it to this object after modifying it; as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 from pci.api import datasource as ds

 with ds.open_dataset(uri, ds.eAM_WRITE) as dataset:
     # get a copy of the aux_data from dataset
     aux = dataset.aux_data

     # set a file metdata field
     aux.set_file_metadata_value('new_field', 'modified')

     # set the modified aux_data to dataset
     dataset.aux_data = aux
clear_file_events((Dataset)self) → None :

Clear all file level HistoryEvents from this dataset.

close((Dataset)self) → None :

Close the dataset. Once closed, this dataset, can no longer be read or written to.

New in version 2016.

property crs

The coordinate system for the dataset.

delete((Dataset)self) → FileAccessState :

Delete the dataset. Returns the FileAccessState, eSuccess upon success, eFailed if the delete failed, eLocked if the file is locked, and eUnknown otherwise.

property exists

True if the dataset exists on disk, False otherwise.

get_file_events((Dataset)self) → HistoryEventVec :

Get a HistoryEventVec of file level history from the dataset.

is_linked((Dataset)self) → bool :

Return True if this dataset is a linked pix file and False otherwise.

New in version 2016.

is_open((Dataset)self) → bool :

Return True if the dataset is currently open, False otherwise

New in version 2016.

property linked_files

If this dataset is a linked PIX file, then this member variable is the list of files linked to by this dataset, or an empty list otherwise.

property name

The name of the dataset

synchronize((Dataset)self) → None :

Synchronize the dataset. Typically this results in flushing of output to disk.

New in version 2016.

class pci.api.datasource.AccessMode

Bases: Boost.Python.enum

Specifies the access mode when opening a Dataset. eAM_READ specifies read mode and eAM_WRITE specifies write mode.

eAM_READ = pci.api.datasource.AccessMode.eAM_READ
eAM_WRITE = pci.api.datasource.AccessMode.eAM_WRITE
class pci.api.datasource.AccessCapabilities

Bases: Boost.Python.instance

The class holds information about the I/O capabilites of a dataset.

property is_readable

If True, the dataset can be read.

property is_updatable

If True, the dataset can be updated.

property is_writeable

If True, the dataset can be written.

class pci.api.datasource.FileAccessState

Bases: Boost.Python.enum

Specifies the access state of a file.

  • eSuccess - Specifies that access operation succeeded.

  • eFailed - Specifies that access operation failed.

  • eLocked - Specifies that access operation was not attempted because the file is locked.

  • eUnknown - Used in all other cases.

eSuccess = pci.api.datasource.FileAccessState.eSuccess
eFailed = pci.api.datasource.FileAccessState.eFailed
eLocked = pci.api.datasource.FileAccessState.eLocked
eUnknown = pci.api.datasource.FileAccessState.eUnknown
pci.api.datasource.open_dataset((string_)uri[, (AccessMode)mode=pci.api.datasource.AccessMode.eAM_READ]) → Dataset :

Open a dataset at the specified uri, with the specified mode. Use eAM_READ to open in read only mode, or eAM_WRITE to open in read/write mode. If the dataset cannot be opened, or the dataset doesn’t exist and eAM_READ is specified, the a DataException is thrown.

pci.api.datasource.open_dataset_format((string_)format, (string_)uri[, (AccessMode)mode=pci.api.datasource.AccessMode.eAM_READ]) → Dataset :

Open a dataset using the specifed format, at the specified uri, with the specified mode. Use eAM_READ to open in read only mode, or eAM_WRITE to open in read/write mode. If the dataset cannot be opened, or the dataset doesn’t exist and eAM_READ is specified, the a DataException is thrown.

pci.api.datasource.new_dataset((string_)uri, (string_)format, (string_)options) → Dataset :

Open a new dataset at the specified uri. Use the specified format, and the specified options. This function does not create the file, just the object that can be used to create it. To create the file, call RasterDataset.create() or RasterDataset.create_multitype().

pci.api.datasource.can_open_dataset((string_)uri[, (AccessMode)mode=pci.api.datasource.AccessMode.eAM_READ]) → bool :

Check to see if the dataset sepcified by uri can be opened in the AccessMode specified by mode.

pci.api.datasource.create_linked_pix((string_)new_file, (string_)linked_file) → Dataset :

Create and return a new Dataset, specified by new_file, representing a linked pix file. The existing file containing the channels to link is specified by linked_file.

pci.api.datasource.get_swaths((string_)path) → list :

Get a list of swaths for the specified path. To open a swaths as a Dataset, simply append an item from the returned list to the path.

The following example shows how to get all of the swaths for a Sentinel-2 scene:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 from pci.api import datasource as ds

 path = 's2data/S2A_MSIL1C_20171116T185811_N0206_R113_T12VVJ_20171116T203454.SAFE/MTD_MSIL1C.xml'
 swaths = ds.get_swaths(path)

 # there are swaths for 10m, 20m and 60m resolution
 assert (swaths == [u':Band Resolution:10M', u':Band Resolution:20M', u':Band Resolution:60M'])

 for swath in swaths
     with ds.open_dataset(path + swath) as dataset:
         # do something with each Sentinel-2 swath 
         ... 

New in version 2018.

3.3.4.2. Raster

class pci.api.datasource.RasterDataset

Bases: Boost.Python.instance

This class provides raster-specific functionality on top of Dataset. RasterDataset does not inherit from Dataset, but classes that are derived from RasterDataset will also inherit from Dataset.

property chan_count

The number of channels in the dataset.

create((RasterDataset)self, (RasterInfo)info) → None :

Immediately create a new file or data source for this raster dataset, based on the raster information specified by info.

create_multitype((RasterDataset)self, (uint_)cols, (uint_)rows, (DataTypeVec)data_types) → None :

Immediately create a new file or data source for this raster dataset with dimension cols by rows with *len(data_types) channels. Each channel will have the datatype set in data_types. This method allows creation of files with channels of heterogeneous data types.

get_channel_info((RasterDataset)self, (uint_)chan) → ChannelInfo :

Get information about the image channel specified by chan.

get_history_io((RasterDataset)self, (uint_)chan) → HistoryIO :

Get the HistoryIO, for the channel specified by chan, to read, update or write history of a single channel.

property height

The height of the raster in pixels.

property raster_capabilities

Get the AccessCapabilities raster capabilities for the this dataset.

property width

The width of the raster in pixels.

class pci.api.datasource.MarginBehaviour

Bases: Boost.Python.enum

The margin behaviour dictates the value of a pixel in the margin when the margin is past the edges of the image. In other words when trying to reading pixel values inside of the margin and the margin is past the edge of the pixel, how should an algorithm behave? Essentially, this fabricates fictitious data so that operations needing data in the margins function over the entire image.

  • eException - Invalid option, throw an exception.

  • eReflection - Reflect the pixel values using the edge of the image as the axis of reflection.

  • eReplication - Replicate the raster as a texture. The margins are filled as if raster repeats itself in all directions. For example, the bottom margin will correspond to the top of the raster and the top margin will correspond to the bottom of the raster, etc.

  • eZero - Set the values of the pixels to zero.

eException = pci.api.datasource.MarginBehaviour.eException
eReflection = pci.api.datasource.MarginBehaviour.eReflection
eReplication = pci.api.datasource.MarginBehaviour.eReplication
eZero = pci.api.datasource.MarginBehaviour.eZero
class pci.api.datasource.IRasterIterable

Bases: Boost.Python.instance

This interface allows users to iterate over Raster tiles in a datasource. It allows a raster reader or writer to be used in a for loop.

For example:

1
2
3
4
5
6
7
from pci.api import datasource as ds

with ds.open_dataset('myfile.pix') as dataset:
    reader = ds.BasicReader(dataset)

    for tile in reader:
        process_tile(tile)
set_optimal_tile_size((IRasterIterable)self) → None :

Set the dimensions of the iteration tile to be the optimal size, based on the data source. These dimensions are typically based on the size of the image tiles on disk.

property tile_count

The number of tiles, based on the current tile size, in the data source.

property tile_size

A 2-element tuple of the row and column dimensions of the iteration tiles.

3.3.4.2.1. Reading

class pci.api.datasource.IRasterReader

Bases: pci.api.datasource.IRasterIterable

Interface for reading rasters channels from a file or data source into a Raster.

property aux_data

The AuxiliaryData for the file or data source.

property chans_count

The number of channels in the raster.

property crs

The coordinate system for the file or data source.

property datatype

The DataType of the raster

property geocoding

The geocoding for the file or data source.

property height

The height of the raster, in pixels.

property margin_behaviour

The MarginBehaviour for filling margins when a raster is read.

property margins

A 2-element tuple representing the x and y margins that are added to a raster when it is read.

read_raster((IRasterReader)self, (uint_)col, (uint_)row, (uint_)width, (uint_)height) → Raster :

Read a single raster tile, starting at (row, col) of size (width, height). The resulting raster will have margins be the size specified by IRasterReader.margins, and will be filled according to the rule specified by IRasterReader.margin_behaviour.

set_optimal_tile_size((IRasterIterable)self) → None :

Set the dimensions of the iteration tile to be the optimal size, based on the data source. These dimensions are typically based on the size of the image tiles on disk.

property tile_count

The number of tiles, based on the current tile size, in the data source.

property tile_size

A 2-element tuple of the row and column dimensions of the iteration tiles.

property width

The width of the raster, in pixels.

class pci.api.datasource.BasicReader((object)self, (Dataset)dataset[, (VecUInt)chans=[]])None

Bases: pci.api.datasource.IRasterReader

This class reads raster channels of a file. All channels must have the same type. Construct by specifying the Dataset dataset. When dataset is closed, this object will become invalid. A list of channels can be optionally specifed, as chans; if not specified, all channels in the dataset will be used.

In Geomatica 2016 the constructor was changed to require an open Dataset. The constructed object will only remain valid as long as the Dataset remains open.

Changed in version 2016.

property aux_data

The AuxiliaryData for the file or data source.

property chans_count

The number of channels in the raster.

property crs

The coordinate system for the file or data source.

property datatype

The DataType of the raster

property geocoding

The geocoding for the file or data source.

property height

The height of the raster, in pixels.

property margin_behaviour

The MarginBehaviour for filling margins when a raster is read.

property margins

A 2-element tuple representing the x and y margins that are added to a raster when it is read.

read_raster((IRasterReader)self, (uint_)col, (uint_)row, (uint_)width, (uint_)height) → Raster :

Read a single raster tile, starting at (row, col) of size (width, height). The resulting raster will have margins be the size specified by IRasterReader.margins, and will be filled according to the rule specified by IRasterReader.margin_behaviour.

set_optimal_tile_size((IRasterIterable)self) → None :

Set the dimensions of the iteration tile to be the optimal size, based on the data source. These dimensions are typically based on the size of the image tiles on disk.

property tile_count

The number of tiles, based on the current tile size, in the data source.

property tile_size

A 2-element tuple of the row and column dimensions of the iteration tiles.

property width

The width of the raster, in pixels.

class pci.api.datasource.MultitypeReader((object)self, (Dataset)dataset[, (VecUInt)chans=[][, (DataType)datatype=<DataType: INVALID>]])None

Bases: pci.api.datasource.IRasterReader

This class reads raster channels of a file. The channels can have different data types. Construct by specifying the Dataset dataset. When dataset is closed, this object will become invalid. A list of channels can be optionally specifed, as chans; if not specified, all channels in the dataset will be used. All channels will be converted to the specified datatype, if not specified, the data type of the reader will be determined automatically as the data type of the selected channels with the highest precision and/or bit depth. Data values that can’t be represented by the data type of the reader will be truncated to an appropriate value.

property aux_data

The AuxiliaryData for the file or data source.

property chans_count

The number of channels in the raster.

property crs

The coordinate system for the file or data source.

property datatype

The DataType of the raster

property geocoding

The geocoding for the file or data source.

property height

The height of the raster, in pixels.

property margin_behaviour

The MarginBehaviour for filling margins when a raster is read.

property margins

A 2-element tuple representing the x and y margins that are added to a raster when it is read.

read_raster((IRasterReader)self, (uint_)col, (uint_)row, (uint_)width, (uint_)height) → Raster :

Read a single raster tile, starting at (row, col) of size (width, height). The resulting raster will have margins be the size specified by IRasterReader.margins, and will be filled according to the rule specified by IRasterReader.margin_behaviour.

set_optimal_tile_size((IRasterIterable)self) → None :

Set the dimensions of the iteration tile to be the optimal size, based on the data source. These dimensions are typically based on the size of the image tiles on disk.

property tile_count

The number of tiles, based on the current tile size, in the data source.

property tile_size

A 2-element tuple of the row and column dimensions of the iteration tiles.

property width

The width of the raster, in pixels.

3.3.4.2.2. Writing

class pci.api.datasource.IRasterWriter

Bases: pci.api.datasource.IRasterReader

Interface for writing rasters channels from an Raster to a file or data source.

property aux_data

The AuxiliaryData for the file or data source.

property chans_count

The number of channels in the raster.

create((IRasterWriter)self, (RasterInfo)info) → None :

Create a new file, with the attributes specified by info.

property crs

The coordinate system for the file or data source.

property datatype

The DataType of the raster

property file_exists

True if the file exists on disk, False otherwise.

property geocoding

The geocoding for the file or data source.

property height

The height of the raster, in pixels.

property margin_behaviour

The MarginBehaviour for filling margins when a raster is read.

property margins

A 2-element tuple representing the x and y margins that are added to a raster when it is read.

read_raster((IRasterReader)self, (uint_)col, (uint_)row, (uint_)width, (uint_)height) → Raster :

Read a single raster tile, starting at (row, col) of size (width, height). The resulting raster will have margins be the size specified by IRasterReader.margins, and will be filled according to the rule specified by IRasterReader.margin_behaviour.

set_optimal_tile_size((IRasterIterable)self) → None :

Set the dimensions of the iteration tile to be the optimal size, based on the data source. These dimensions are typically based on the size of the image tiles on disk.

property tile_count

The number of tiles, based on the current tile size, in the data source.

property tile_size

A 2-element tuple of the row and column dimensions of the iteration tiles.

property width

The width of the raster, in pixels.

write_raster((IRasterWriter)self, (Raster)raster) → None :

Write the raster specified by raster to disk.

class pci.api.datasource.BasicWriter((object)self, (RasterDataset)dataset[, (VecUInt)chans=[]])None

Bases: pci.api.datasource.IRasterWriter

This class reads and writes raster channels of a file. All channels must have the same type. Construct by specifying the Dataset dataset. When dataset is closed, this object will become invalid. A list of channels can be optionally specifed, as chans; if not specified, all channels in the dataset will be used.

In Geomatica 2016 the constructor was changed to require an open Dataset. The constructed object will only remain valid as long as the Dataset remains open.

Changed in version 2016.

property aux_data

The AuxiliaryData for the file or data source.

property chans_count

The number of channels in the raster.

create((IRasterWriter)self, (RasterInfo)info) → None :

Create a new file, with the attributes specified by info.

property crs

The coordinate system for the file or data source.

property datatype

The DataType of the raster

property file_exists

True if the file exists on disk, False otherwise.

property geocoding

The geocoding for the file or data source.

property height

The height of the raster, in pixels.

property margin_behaviour

The MarginBehaviour for filling margins when a raster is read.

property margins

A 2-element tuple representing the x and y margins that are added to a raster when it is read.

read_raster((IRasterReader)self, (uint_)col, (uint_)row, (uint_)width, (uint_)height) → Raster :

Read a single raster tile, starting at (row, col) of size (width, height). The resulting raster will have margins be the size specified by IRasterReader.margins, and will be filled according to the rule specified by IRasterReader.margin_behaviour.

set_optimal_tile_size((IRasterIterable)self) → None :

Set the dimensions of the iteration tile to be the optimal size, based on the data source. These dimensions are typically based on the size of the image tiles on disk.

property tile_count

The number of tiles, based on the current tile size, in the data source.

property tile_size

A 2-element tuple of the row and column dimensions of the iteration tiles.

property width

The width of the raster, in pixels.

write_raster((IRasterWriter)self, (Raster)raster) → None :

Write the raster specified by raster to disk.

class pci.api.datasource.MultitypeWriter((object)self, (Dataset)dataset[, (VecUInt)chans=[][, (DataType)datatype=<DataType: INVALID>]])None

Bases: pci.api.datasource.IRasterWriter

This class reads and writes raster channels of a file. The channels can have different data types. Construct by specifying the Dataset dataset. When dataset is closed, this object will become invalid. A list of channels can be optionally specifed, as chans; if not specified, all channels in the dataset will be used. All channels will be converted to the specified datatype, if not specified, the data type of the writer will be determined automatically as the data type of the selected channels with the highest precision and/or bit depth. Data values that can’t be represented by the data type of the writer will be truncated to an appropriate value.

property aux_data

The AuxiliaryData for the file or data source.

property chans_count

The number of channels in the raster.

create((IRasterWriter)self, (RasterInfo)info) → None :

Create a new file, with the attributes specified by info.

property crs

The coordinate system for the file or data source.

property datatype

The DataType of the raster

property file_exists

True if the file exists on disk, False otherwise.

property geocoding

The geocoding for the file or data source.

property height

The height of the raster, in pixels.

property margin_behaviour

The MarginBehaviour for filling margins when a raster is read.

property margins

A 2-element tuple representing the x and y margins that are added to a raster when it is read.

read_raster((IRasterReader)self, (uint_)col, (uint_)row, (uint_)width, (uint_)height) → Raster :

Read a single raster tile, starting at (row, col) of size (width, height). The resulting raster will have margins be the size specified by IRasterReader.margins, and will be filled according to the rule specified by IRasterReader.margin_behaviour.

set_optimal_tile_size((IRasterIterable)self) → None :

Set the dimensions of the iteration tile to be the optimal size, based on the data source. These dimensions are typically based on the size of the image tiles on disk.

property tile_count

The number of tiles, based on the current tile size, in the data source.

property tile_size

A 2-element tuple of the row and column dimensions of the iteration tiles.

property width

The width of the raster, in pixels.

write_raster((IRasterWriter)self, (Raster)raster) → None :

Write the raster specified by raster to disk.

3.3.4.3. Metadata

class pci.api.datasource.AuxiliaryData((object)self, (uint_)chans)None

Bases: Boost.Python.instance

Class containing auxiliary information and metadata about files and channels. Construct by specfiying the number of channels as chans.

property chan_count

Number of channels

property file_metadata

A dict of the file level metadata. Using this property gives you a copy of this object’s file level metadata. If you wish to modify the contents of this object’s metadata, you have to reassign it to the object after modifying it; as follows:

For example:

1
2
3
4
5
6
7
8
 # get a copy of the file level metadata
 metadata = aux.file_metadata

 # set a file metdata field
 metadata['new_field'] = 'modified'

 # set the metadata back to the AuxiliaryData
 aux.file_metadata = metadata
get_chan_description((AuxiliaryData)self, (uint_)chan) → str :

Get the channel description for the channel chan.

get_chan_metadata((AuxiliaryData)self, (uint_)chan) → dict :

Get a copy of the metadata dict for the channel chan.

get_chan_metadata_value((AuxiliaryData)self, (string_)key, (uint_)chan) → str :

Get the channel metadata value for the key key for the channel chan.

get_cleaned_metadata((AuxiliaryData)self) → AuxiliaryData :

Return an AuxiliaryData object with private metadata tags removed (e.g. ‘_Overview’, LAYER_CRC and DBLayout).

get_file_metadata_value((AuxiliaryData)self, (string_)key) → str :

Get the file metadata value for the key key.

remove_chan_metadata_value((AuxiliaryData)self, (string_)key, (uint_)chan) → None :

Remove the channel metadata value for the key key for the channel chan.

remove_file_metadata_value((AuxiliaryData)self, (string_)key) → None :

Remove the file metadata value for the key key.

set_chan_description((AuxiliaryData)self, (string_)desc, (uint_)chan) → None :

Set the channel description descr for the channel chan.

set_chan_metadata((AuxiliaryData)self, (MetadataMap)metadata, (uint_)chan) → None :

Set the metadata for the channel chan.

set_chan_metadata_value((AuxiliaryData)self, (string_)key, (string_)value, (uint_)chan) → None :

Set the channel metadata value value for the key key for the channel chan.

set_file_metadata_value((AuxiliaryData)self, (string_)key, (string_)value) → None :

Set the file metadata value value for the key key.

class pci.api.datasource.ChannelInfo

Bases: Boost.Python.instance

The class holds information about the datatype of a channel. This class cannot be created directly from python.

property data_type

Get the DataType of this channel, as it is used in the Raster objects.

property raw_data_type

Get the DataType of this channel, as it is stored on disk.

class pci.api.datasource.DescriptionIO

Bases: Boost.Python.instance

This class provides access to a data source’s name and description.

property description

The description of the data source.

property type

The type of the data source.

class pci.api.datasource.HistoryIO

Bases: Boost.Python.instance

This abstract class provides access to history information for a file or data source.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

class pci.api.datasource.KVPMetadataIO

Bases: Boost.Python.instance

This class provides access to a data source’s metadata key-value pairs.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

class pci.api.datasource.MetadataIO

Bases: pci.api.datasource.HistoryIO, pci.api.datasource.DescriptionIO, pci.api.datasource.KVPMetadataIO

This class provides access to all metadata for data source.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

property description

The description of the data source.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

property id

The ID of the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

property type

The type of the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

3.3.4.4. Bitmaps

class pci.api.datasource.BitmapDataset

Bases: Boost.Python.instance

This class provides bitmap-specific functionality on top of Dataset. BitmapDataset does not inherit from Dataset, but classes that are derived from BitmapDataset will also inherit from Dataset.

property bitmap_capabilities

Get the AccessCapabilities bitmap capabilities for the dataset.

property bitmap_ids

A VecUInt of bitmap IDs accessible from this dataset.

create_bitmap((BitmapDataset)self) → int :

Create a bitmap segment in the dataset. Return the segment number of the newly created bitmap segment.

delete_bitmap((BitmapDataset)self, (uint_)seg) → None :

Delete the bitmap segment seg from the dataset.

get_basic_reader((BitmapDataset)self, (VecUInt)segs) → IRasterReader :

Get a BasicReader that can read a Raster from the bitmap segments specified by segs.

get_basic_writer((BitmapDataset)self, (VecUInt)segs) → IRasterWriter :

Get a BasicWriter that can read and write a Raster from/to the bitmap segments specified by segs.

get_bitmap_metadata_io((BitmapDataset)self, (uint_)seg) → MetadataIO :

Get a MetadataIO that can be used to read and write metadata for bitmap segment seg.

read_mask((BitmapDataset)self, (uint_)seg, (RasterInfo)info, (RasterContext)context) → Mask :

Read a Mask from segment seg. Specify the raster info on context of the resulting mask.

write_mask((BitmapDataset)self, (Mask)mask[, (int_)seg=-1]) → int :

Write the Mask mask to segment seg. If seg is -1, create a new segment. Return the segment id of the segment that was written to or created.

3.3.4.5. Coordinate systems

class pci.api.datasource.GeocodedDataset

Bases: Boost.Python.instance

This class provides acces to GeocodingInfo for a Dataset. The GeocodingInfo provides a way to convert between raster coordinates and geocoded X/Y coordinates. GeocodedDataset does not inherit from Dataset, but classes that are derived from GeocodedDataset will also inherit from Dataset.

property geocoding

The GeocodingInfo for the dataset.

property resolution_in_meters

Get the resolution in meters for the dataset. A tuple of (x_resolution, y_resolution) is returned if it can be determined, or None otherwise. If the dataset uses geographic coordinates, then the resolution of the center pixel, in meters, will be returned.

class pci.api.datasource.CrsIO

Bases: Boost.Python.instance

This class provides access to a CRS for a data source.

read_crs((CrsIO)self) → CRS :

Read the CRS from the data source.

update_crs((CrsIO)self, (CRS)crs) → None :

Write the CRS crs to the data source.

3.3.4.6. Arrays

class pci.api.datasource.ArrayDataset

Bases: Boost.Python.instance

This class provides access to array segments on top of Dataset. ArrayDataset does not inherit from Dataset, but classes that are derived from ArrayDataset will also inherit from Dataset.

New in version 2016.

property array_capabilities

Get the AccessCapabilities array segment capabilities for the dataset.

create_array((ArrayDataset)self) → int :

Creates a new array segment in the dataset. Return the ID of the new segment

delete_array((ArrayDataset)self, (uint_)id) → None :

Delete array segment specified by id from the dataset.

get_array_io((ArrayDataset)self, (uint_)id) → ArrayIO :

Get the array segment, specified by id from the dataset.

get_array_io_ids((ArrayDataset)self) → VecUInt :

Get a list of array segments IDs in the dataset.

class pci.api.datasource.ArrayIO

Bases: pci.api.datasource.MetadataIO

This class provides access to an array segment for a dataset.

New in version 2016.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

property description

The description of the data source.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

property id

The ID of the data source.

property ndim

The number of dimensions in the array.

read_array((ArrayIO)self) → object :

Read a numpy.ndarray, that may be multi-dimensional, containing the data in the array segment.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

property shape

A list of the sizes of each dimension in the array segment.

property type

The type of the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_array((ArrayIO)self, (object)array) → None :

Overwrite the existing array segment with the numpy.ndarray array. All existing data in the segment is discarded.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

3.3.4.7. Control points

class pci.api.datasource.ControlPointDataset

Bases: Boost.Python.instance

This class provides access to all control point segments on top of Dataset. ControlPointDataset does not inherit from Dataset, but classes that are derived from ControlPointDataset will also inherit from Dataset.

property controlpoint_capabilities

Get the AccessCapabilities control point segment capabilities for the dataset.

create_controlpoint_io((ControlPointDataset)self) → int :

Create a new control point segment in the dataset. Returns the ID of the new segment.

delete_controlpoint_io((ControlPointDataset)self, (uint_)id) → None :

Delete control point segment specified by id from the dataset.

get_controlpoint_io((ControlPointDataset)self, (uint_)id) → ControlPointIO :

Read control point segment specified by id from the dataset.

get_controlpoint_io_ids((ControlPointDataset)self) → VecUInt :

Get a list the IDs of all control points segments in the dataset.

class pci.api.datasource.ControlPointIO

Bases: pci.api.datasource.CrsIO, pci.api.datasource.MetadataIO

This class provides access to a control point segment for a data source.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

property description

The description of the data source.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

property id

The ID of the data source.

read_crs((CrsIO)self) → CRS :

Read the CRS from the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

read_points((ControlPointIO)self) → ControlPointContainer :

Read a ControlPointContainer from the datasource.

property type

The type of the data source.

update_crs((CrsIO)self, (CRS)crs) → None :

Write the CRS crs to the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

write_points((ControlPointIO)self, (ControlPointContainer)container) → None :

Overwrite the control point segment with the pci.api.gobs.ControlPointContainer container. All existing data in the segment is discarded.

3.3.4.8. Text

class pci.api.datasource.TextDataset

Bases: Boost.Python.instance

This class provides access to all text segments on top of Dataset. TextDataset does not inherit from Dataset, but classes that are derived from TextDataset will also inherit from Dataset.

New in version 2016.

create_text((TextDataset)self) → int :

Creates a new text segment in the dataset. Return the ID of the new segment.

delete_text((TextDataset)self, (uint_)id) → None :

Delete text segment specified by id from the dataset.

get_text_io((TextDataset)self, (uint_)id) → TextIO :

Get the text segment, specified by id from the dataset.

get_text_io_ids((TextDataset)self) → VecUInt :

Get a list of all text segments IDs in the dataset

property text_capabilities

Get the AccessCapabilities text segment capabilities for the dataset.

class pci.api.datasource.TextIO

Bases: pci.api.datasource.MetadataIO

This class provides access to a text segment for a data source.

New in version 2016.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

property description

The description of the data source.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

property id

The ID of the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

read_text((TextIO)self) → str :

Read a text segment. All carriage returns ('\r') in the segment are converted to new lines ('\n') during reading.

property type

The type of the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

write_text((TextIO)self, (string_)text) → None :

Writes the text to the text segment. All newlines ('\n') will be converted to carriage returns ('\r') for storage in the text segment, and if not present, a carriage return will be added to the end of the segment.

3.3.4.9. Math models

class pci.api.datasource.MathmodelDataset

Bases: Boost.Python.instance

This class provides access to math model segments on top of Dataset. MathmodelDataset does not inherit from Dataset, but classes that are derived from MathmodelDataset will also inherit from Dataset.

property can_write_mathmodels

True if math models can be written to this dataset, False otherwise.

create_model((MathmodelDataset)self, (MathModelType)model_type) → int :

Create a new math model segment for a model of type model_type in the dataset.

delete_model((MathmodelDataset)self, (uint_)id) → None :

Delete math model segment specified by id from the dataset.

get_model_by_id((MathmodelDataset)self, (uint_)id) → MathModel :

Get the math model specified by its id (or segment number).

get_model_io((MathmodelDataset)self, (uint_)id) → MathmodelIO :

Get the math model segment, specified by id, from the dataset.

property mathmodel_capabilities

Get the AccessCapabilities math model segment capabilities for the dataset.

property model_count

The number of math model segments in the dataset

property model_ids

A list of math model segment IDs available in this dataset

update_model((MathmodelDataset)self, (uint_)id, (MathModel)model) → None :

Update the math model segment, specified by id with the math model model.

write_model((MathmodelDataset)self, (MathModel)model) → int :

Write the math model model to a new segment on disk, return the new segment id.

class pci.api.datasource.MathmodelIO

Bases: pci.api.datasource.MetadataIO

This class provides access to a math model segment for a data source.

New in version 2019.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

property description

The description of the data source.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

property id

The ID of the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

read_model((MathmodelIO)self) → MathModel :

Read a math model segment.

property type

The type of the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

write_model((MathmodelIO)self, (MathModel)model) → None :

Write a math model to the math model segment.

3.3.4.10. Ephemeris

class pci.api.datasource.EphemerisDataset

Bases: Boost.Python.instance

This class provides access to ephemeris segments on top of Dataset. EpehemerisDataset does not inherit from Dataset, but classes that are derived from EpehemerisDataset will also inherit from Dataset.

New in version 2016.

property can_write_ephemeris

Return a flag indicating whether this file format supports writing ephemeris data.

property ephemeris_count

Get the number of ephemeris segments in the dataset.

property ephemeris_ids

A list of ephemeris segment IDs available in the dataset.

get_ephemeris_by_id((EphemerisDataset)self, (uint_)id) → EphemerisData :

Get EphemerisData from the given segment ID.

get_model_from_ephemeris((EphemerisDataset)self, (uint_)id[, (uint_)control_id=0]) → MathModel :

Get a MathModel for the ephemeris segment corresponding to the given ephemeris segment id and control point segment id control_id. If control_id is 0, no control point segment is used.

write_ephemeris((EphemerisDataset)self, (EphemerisData)ephemeris) → int :

Write the EphemerisData ephemeris to a new ephemeris segment. Returns the ID of the newly created segment.

3.3.4.11. Lookup table (LUT)

class pci.api.datasource.LUTDataset

Bases: Boost.Python.instance

This class provides access to all look-up table segments on top of Dataset. LUTDataset does not inherit from Dataset, but classes that are derived from LUTDataset will also inherit from Dataset.Classic LUT segments support exactly 256 input values, and all input and output values must be 8-bit unsigned values. Breakpoint LUT segments support any number of input values (must be at least 2), and input and output values can be any datatype.

New in version 2016.

create_lut((LUTDataset)self[, (LUT)lut=None]) → int :

Create a new look-up table segment in the dataset. Returns the ID of the new segment. Optionally, specify a LUT lut that will give a hint of what type of segment to create. If lut specifies a look-up table that can be written to a classic LUT segment, then a classic LUT segment will be created. Otherwise, a breakpoint LUT segment will be created. This LUT will not be written to disk, but just used as a guide to indicate the segment type to create.

delete_lut((LUTDataset)self, (uint_)id) → None :

Delete look-up table segment specified by id from the dataset.

get_lut_io((LUTDataset)self, (uint_)id) → LUTIO :

Get the look-up table segment, specified by id, from the dataset.

get_lut_io_ids((LUTDataset)self) → VecUInt :

Get a list the IDs of all look-up segments in the dataset.

property lut_capabilities

Get the AccessCapabilities look-up segment capabilities for the dataset.

class pci.api.datasource.LUTIO

Bases: pci.api.datasource.MetadataIO

This class provides access to a look-up table segment for a data source.

New in version 2016.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

property description

The description of the data source.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

property id

The ID of the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

read_lut((LUTIO)self) → LUT :

Read a LUT from the datasource.

property type

The type of the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

write_lut((LUTIO)self, (LUT)lut) → None :

Overwrite the look-up table segment with the LUT lut. All existing data in the segment is discarded.

pci.api.datasource.get_default_lut((Dataset)dataset, (uint_)chan) → tuple :

Get the default look-up table segment from the channel chan in dataset. Returns a 3-element tuple of look-up table file, segment type and segment number respectively. The look-up table file indicates the file that the look-up table resides in if the look-up table is in the same file as dataset, then the first element of the tuple will be None. The segment type indicates the type of segment on disk; it will be ‘LUT’ for a classic look-up table, or ‘BLUT’ for a breakpoint look-up table. The segment number indicates the segment number of the referenced look-up table segment.

New in version 2016.

pci.api.datasource.set_default_lut((Dataset)dataset, (uint_)chan, (object)lutfile, (string_)segtype, (uint_)seg) → None :

Set the default look-up table segment for the specified chan in dataset. Specify the file that contains the look-up table as lutfile or None if the look-up table is in the same file. Specify the segment type as segtype supported values are ‘LUT’ for a classic look-up table and ‘BLUT’ for a breakpoint look-up table. Specify the look-up table segment number as seg.

New in version 2016.

3.3.4.12. Pseudocolor table (PCT)

class pci.api.datasource.PCTDataset

Bases: Boost.Python.instance

This class provides access to all pseudo-colour table segments on top of Dataset. PCTDataset does not inherit from Dataset, but classes that are derived from PCTDataset will also inherit from Dataset. This class supports both classic PCT segments and breakpoint PCT segments. Classic PCT segments support exactly 256 input values, and all input values must be 8-bit unsigned values. Breakpoint PCT segments support any number of input values (must be at least 2), and input values can be any datatype.

New in version 2016.

create_pct((PCTDataset)self[, (PCT)pct=None]) → int :

Create a new pseudo-colour table segment in the dataset. Returns the ID of the new segment. Optionally, specify a PCT pct that will give a hint of what type of segment to create. If pct specifies a pseudo-colour table that can be written to a classic PCT segment, then a classic PCT segment will be created. Otherwise, a breakpoint PCT segment will be created. This PCT will not be written to disk, but just used as a guide to indicate the segment type to create.

delete_pct((PCTDataset)self, (uint_)id) → None :

Delete pseudo-colour table segment specified by id from the dataset.

get_pct_io((PCTDataset)self, (uint_)id) → PCTIO :

Get the pseudo-colour table segment, specified by id, from the dataset.

get_pct_io_ids((PCTDataset)self) → VecUInt :

Get a list the IDs of all pseudo-colour segments in the dataset.

property pct_capabilities

Get the AccessCapabilities pseudo-colour segment capabilities for the dataset.

class pci.api.datasource.PCTIO

Bases: pci.api.datasource.MetadataIO

This class provides access to a pseudo-colour table segment for a data source.

New in version 2016.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

property description

The description of the data source.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

property id

The ID of the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

read_pct((PCTIO)self) → PCT :

Read a PCT from the datasource.

property type

The type of the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

write_pct((PCTIO)self, (PCT)pct) → None :

Overwrite the pseudo-colour table segment with the PCT pct. All existing data in the segment is discarded.

pci.api.datasource.get_default_pct((Dataset)dataset, (uint_)chan) → tuple :

Get the default pseudo-colour table segment from the channel chan in dataset. Returns a 3-element tuple of pseudo-colour table file, segment type and segment number respectively. The pseudo-colour table file indicates the file that the pseudo-colour table resides in if the pseudo-colour table is in the same file as dataset, then the first element of the tuple will be None. The segment type indicates the type of segment on disk; it will be ‘PCT’ for a classic pseudo-colour table, or ‘BPCT’ for a breakpoint pseudo-colour table. The segment number indicates the segment number of the referenced pseudo-colour table segment.

New in version 2016.

pci.api.datasource.set_default_pct((Dataset)dataset, (uint_)chan, (object)pctfile, (string_)segtype, (uint_)seg) → None :

Set the default pseudo-colour table segment for the specified chan in dataset. Specify the file that contains the pseudo-colour table as pctfile or None if the pseudo-colour table is in the same file. Specify the segment type as segtype supported values are ‘PCT’ for a classic pseudo-colour table and ‘BPCT’ for a breakpoint pseudo-colour table. Specify the pseudo-colour table segment number as seg.

New in version 2016.

3.3.4.13. Vectors

class pci.api.datasource.VectorDataset

Bases: Boost.Python.instance

This class provides access to vector segments on top of Dataset. VectorDataset does not inherit from Dataset, but classes that are derived from VectorDataset will also inherit from Dataset.

Changed in version 2018.

create_noraster((VectorDataset)self) → None :

Immediately create a new file or data source for this vector dataset, that has no raster channels.

create_vector((VectorDataset)self[, (string_)name='Vector'[, (GeometryType)layer_type=pci.api.datasource.GeometryType(-1)]]) → int :

Create a new vector segment called name in the dataset. Returns the ID of the new segment.

delete_vector((VectorDataset)self, (uint_)id) → None :

Delete vector segment specified by id from the dataset.

get_vector_io((VectorDataset)self, (uint_)id) → VectorIO :

Get the vector segment, specified by id, from the dataset.

get_vector_io_ids((VectorDataset)self) → VecUInt :

Get a list the IDs of all vector segments in the dataset.

class pci.api.datasource.GeometryType

Bases: Boost.Python.enum

The type of geometry contained in a vector segment.

  • Collection - The segment contains a mixture of various geometry types.

  • Line - The segment contains line strings.

  • Point - The segment contains points

  • Polygon - The segment contains polygons

  • Table - The segment contains a table of fields with no geometry

  • TopoArc - The segment contains topological arcs

  • TopoArea - The segment contains topological areas

  • TopoNode - The segment contains topological points

New in version 2018.

class pci.api.datasource.VectorIO

Bases: pci.api.datasource.MetadataIO, pci.api.datasource.CrsIO

This class provides access to a vector segment for a data source.

New in version 2018.

add_event((HistoryIO)self, (string_)action, (string_)details[, (object)start_time=None[, (object)end_time=None]]) → None :

Add a new HistoryEvent for this segment/channel. The type of action is specified by action and the details of this action can be specified by details. The start_time and end_time can be specified as a datetime.datetime. If either of these times are None then the current local time will be used.

add_field((VectorIO)self, (FieldDefinition)field_def) → None :

Add a new Field to the segment.

clear_events((HistoryIO)self) → None :

Clear all HistoryEvents from this segment/channel.

delete_kvps((KVPMetadataIO)self, (StringVec)keys) → None :

Delete all key-value pairs specified by keys from the data source.

delete_shape((VectorIO)self, (int_)id) → None :

Delete the Shape specified by shape ID id from the vector segment.

property description

The description of the data source.

property fields_count

The number of fields in this segment

property geometry_type

Get the GeometryType of the segment.

get_events((HistoryIO)self) → HistoryEventVec :

Get a HistoryEventVec from the segment/channel

get_record((VectorIO)self, (int_)id) → Record :

Get the Record for the Shape specified by shape ID id.

property id

The ID of the data source.

property name

The name of the vector segment

query_attributes((VectorIO)self, (string_)query_string[, (VecInt)subset=[]]) → VecInt :

Perform an attribute query on the vector segment. Return a sequence of shape ids that satisfy the query specified by query_string. If query_string is empty, then all existing valid shape ids are returned. If subset is not empty, then it specifies the subset of shape ids in the segment to search so the return value will be limited to those that are in this list.

A query expression must conform to the following grammar structure:

EXPRESSION: PRIMARY
            not(EXPRESSION)
            (EXPRESSION) BINARY_OP (EXPRESSION)

PRIMARY: FIELDNAME OPERATOR VALUE

OPERATOR : =
          <=
          >=
          <
          >

BINARY_OP : and
            or
VALUE : number
        'string'

FIELDNAME : valid fieldname of the vector segment or 'ShapeId'

            attribute = 1
            not(attribute = 1)
            (attribute < 12 and attribute > 4) or(group < 2)
query_polygon((VectorIO)self, (Shape)polygon[, (bool)fully_within=False[, (VecInt)subset=[]]]) → VecInt :

Perform a spatial query on the vector segment. Return a sequence of shape ids that overlap the polygon specified by polygon. If fully_within is True, then only return shapes that are fully within the search polygon, otherwise return shapes that partially overlap the search polygon.If subset is not empty, then it specifies the subset of shape ids in the segment to search so the return value will be limited to those that are in this list.

NOTE: If polygon has internal rings, they will be ignored, only the outer ring is considered for this query.

query_rectangle((VectorIO)self, (float)xmin, (float)ymin, (float)xmax, (float)ymax[, (VecInt)subset=[]]) → VecInt :

Perform a spatial query on the vector segment. Return a sequence of shape ids that overlap the rectangle specified by xmin, ymin, xmax, ymax. If subset is not empty, then it specifies the subset of shape ids in the segment to search so the return value will be limited to those that are in this list.

read_crs((CrsIO)self) → CRS :

Read the CRS from the data source.

read_kvps((KVPMetadataIO)self) → dict :

Read a dict of key value pairs from the data source.

read_shape((VectorIO)self, (int_)id) → Shape :

Read the Shape specified by shape ID id from this vector segment.

read_shapes((VectorIO)self, (VecInt)ids) → ShapeContainer :

Read the Shapes specified by shape IDs ids from this vector segment.

property record_definition

Get the RecordDefinition for this segment.

set_record((VectorIO)self, (int_)id, (Record)record) → None :

Set the Record record for the Shape specified by shape ID id.

property shape_count

The number of Shapes in the segment

property shape_ids

The IDs for all Shapes in the segment

property type

The type of the data source.

update_crs((CrsIO)self, (CRS)crs) → None :

Write the CRS crs to the data source.

update_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Update the data source’s key-value pairs with kvps. When the kvps contains a pair with a key that does not exist, the pair is added to the data source.

update_shape((VectorIO)self, (int_)id, (Shape)shape) → None :

Update the Shape specified by shape ID id in this vector segment with the Shape specified by shape.

update_shapes((VectorIO)self, (VecInt)ids, (ShapeContainer)shapes) → None :

Update the Shapes specified by shape IDs ids in this vector segment with the Shapes specified by shapes.

write_kvps((KVPMetadataIO)self, (MetadataMap)kvps) → None :

Write the specified key-value pairs kvps to the data source. This function first clears all the key-value pairs in the data source before writing.

write_shape((VectorIO)self, (Shape)shape) → int :

Write the Shape specified by shape to the vector segment.

write_shapes((VectorIO)self, (ShapeContainer)shapes) → VecInt :

Write the Shapes specified by shapes to the vector segment.

3.3.4.14. Signatures

class pci.api.datasource.SignatureDataset

Bases: Boost.Python.instance

This class provides access to all signature segments on top of Dataset. SignatureDataset does not inherit from Dataset, but classes that are derived from SignatureDataset will also inherit from Dataset.

New in version 2019.

property signature_ids

Get a list of all signature segment IDs in the dataset.

3.3.4.15. Sensor Data

Remote sensing platform, e.g. Landsat, have multiple sensors such as panchromatic (PAN), multi-spectral (MS), and thermal. The data for these sensors can be classified as ‘radiometric’ and ‘non-radiometric’. Radiometric data has spectral information i.e. ‘Minimum Wavelength’, and ‘Maximum Wavelength’ - for example ‘Blue’, ‘Green’, and ‘Red’ spectral bands. Example of non-radiometric data include the ‘Quality’ band which does not have spectral wavelength data but the quailty inforamtion for each pixel.

This class is designed to retreive both the radiometric and non-radiometric infromation for given data.

The class has a function ‘sensor_data’ to give user a list of sensors and list of corresponding radiometric and n-radiometric data.

class pci.api.datasource.SensorDataInfo((object)self, (string_)filename)None

Bases: Boost.Python.instance

This class encapsulates an image, its sensor and band in each sensor. An image file can have single or multiple swaths. An example of multi-swath image is Landsat-8 which contains both the Panchromatic and Multispectral sensors (swaths).In collection-2 for Landsat the radiometric and non-radiometric channles are read in a single container.

property file_with_swath

Returns a list of ‘file name with swath’ which are read from AuxiliaryData.

property image_acquisition_date_time

Returns Image Acquisition Date and Time.

property platform_name

Returns the platform name string.

property sensor_data

Returns a list of a sensor’s PAN, MS radiometric, and MS non-radiometric data.

property swaths

Returns a list of swaths which are read from AuxiliaryData.

class pci.api.datasource.SensorData

Bases: Boost.Python.instance

This class encapsulates an image’s sensor and its data. It stores a sensor’s general information, radiometric channels for PAN and MS, and non-radiometric data for MS.

property ms_non_radiometric_data

Returns a list of MS non-radiometric data from this channel.

property ms_radiometric_data

Returns a list of MS radiometric data from this channel.

property pan_radiometric_data

Returns a list of PAN radiometric data from this channel.

property sensor_code

The short sensor code for the platform. For example PAN for Panchromatic, MS for Mulrispectral.

property sensor_name

Returns the sensor name string.

class pci.api.datasource.NonRadiometricData((object)self, (string_)filename)None

Bases: Boost.Python.instance

The class encapsulating non-radiometric data in an image file. The list of non-radiometric data from the input file is build by looking at the AuxiliaryData of the data read from the input file.

property bands

Get list of non-spectral bands in the sensor.

class pci.api.datasource.NonSpectralBand

Bases: Boost.Python.instance

The class for non-spectral image bands from AuxiliaryData.

property chan_num

Return the corresponding channel number on file

property description

The description for non-spectral band.

property radiometric_trans_quantity

The radiometric trans quantity for non-spectral band.

class pci.api.datasource.RadiometricData((object)self, (string_)filename)None

Bases: Boost.Python.instance

The class to retrieve the radiometric information. The example of information include: ‘Band Description’, ‘Minimum Wavelength’, ‘Maximum Wavelength’, ‘Central Wavelength’, and ‘Spectral Response Function’.

property spectral_bands

Return a reference to the Spectral Bands vector

class pci.api.datasource.SpectralBand

Bases: Boost.Python.instance

The class to encapsulate band’s spectral information such as: minimum and maximum wavelength, description, type, spectral response.

property central_wavelength
property chan_num

Return the corresponding channel number on file

property description

Return band description

property max_wavelength
property min_wavelength
property type

Return band description

3.3.4.16. File formats

The following are implementations of Dataset and other dataset types. Objects of these classes cannot be created directly, you must use open_dataset(), open_dataset_format(), new_dataset(), or create_linked_pix() to create these objects.

This section provides information about some of the common formats (foptions) used in CATALYST products. For more information about the available options of a format, see the supported file formats in the technical reference.

3.3.4.16.1. Supported format types

For a complete list of all supported formats, see the supported file formats in the technical reference.

New in version 2018.

class pci.api.datasource.FileFormat

Bases: Boost.Python.enum

An enum representing the file formats supported by CATALYST.

pci.api.datasource.get_file_format((object)uri) → FileFormat :

Get the FileFormat of a dataset.

..versionadded:: 2018

pci.api.datasource.get_format_extension((int_)file_format) → str :

Get the file extension associated with the FileFormat file_format. If there is no extension associated with file_format then None is returned.

pci.api.datasource.file_format_to_name((int_)file_format) → object :

Get the format name associated with the FileFormat file_format. If there is no name associated with file_format then None is returned.

pci.api.datasource.name_to_file_format((object)format_name) → FileFormat :

Get the FileFormat associated with the string format_name. If there is no format associated with format_name, then FileFormat.FL_UNUSED is returned.

3.3.4.16.2. Format implementations

3.3.4.16.2.2. GDB

GDB is the standard PCI file-format implementation. It can handle all supported PCI formats, including those with specific implementations, such as PIX and TIFF. For more information about the available GDB formats, see the supported file formats in the technical reference.

class pci.api.datasource.GDBALLDataset

Bases: pci.api.datasource.Dataset, pci.api.datasource.RasterDataset, pci.api.datasource.GeocodedDataset, pci.api.datasource.MathmodelDataset, pci.api.datasource.ControlPointDataset, pci.api.datasource.BitmapDataset, pci.api.datasource.LUTDataset, pci.api.datasource.PCTDataset, pci.api.datasource.ArrayDataset, pci.api.datasource.EphemerisDataset, pci.api.datasource.TextDataset, pci.api.datasource.VectorDataset, pci.api.datasource.SignatureDataset

Generic GDB implementation for all supported PCI formats. Create a specific file format by specifying either format='GDBALL' and foptions='file_format' or format='file_format, where file_format is the GDB format that you want to create. For exmaple, if you would want to create a PNG file, you can create it as either format='GDBALL' and foptions='PNG' or format='PNG.