3.6. pci package

The pci package is the root package of all of the PCI Python tools, which includes the CATALYST Python API and other utilities.

The root module of the pci package contains some utilities for working with the CATALYST Python API.

Because the CATALYST Python API is written in C++ and exposed to Python using Boost::Python, several utility classes must be exposed to Python to help interoperate between C++ classes and Python classes.

3.6.1. Utility functions

pci.getHomePath() str :

Get the directory where CATALYST is installed.

pci.make_relative_path((object)base_file, (object)related_file) object :

Relative Path handling function.

Given a basename (for a project file of some type for instance) in base_file this function returns a filename for the file related_file which is either relative to the project file if possible or absolute (from the root) if it is not possible to deduce a relative path from base_file to related_file. If the passed in filenames do not have an absolute path, then they are considered relative to the current directory. The returned filename is normalized.

from pci import make_relative_path


path = make_relative_path(u'/master/pci-local/etc/MYAPP.PRJ',
                          u'/master/pci-local/etc/MYAPP.EAS')
# path is equal to 'MYAPP.EAS'

path = make_relative_path(u'/master/pci-local/etc/MYAPP.PRJ',
                          u'/master/pci-local/etc/data/MYAPP.EAS')
# path is equal to 'data/MYAPP.EAS'

# If the current working directory is "/usr/data/projects", then:
path = make_relative_path(u'../MYAPP.PRJ', u'MYAPP.EAS')
# path is equal to '/usr/data/projects/MYAPP.EAS'
pci.merge_relative_path((object)base_file, (object)related_file) object :

Merge the path to the file name.

This function adds the path from base_file to the filename in pszRelatedFile and returns this new filename. If base_file is None, then related_file will be made relative to the current working directory. If related_file has an absolute path, then it is returned directly. The returned filename is normalized.

from pci import merge_relative_path


# If the project file '/usr/projects/myproj.prj' refers to the file
# 'abc.dat' in the 'data' sub-directory. Then merge_relative_path()
# can return a complete filename for 'abc.dat':

path = merge_relative_path(u'/usr/projects/myproj.prj', u'data/abc.dat')
# path is equal to '/usr/projects/data/abc.dat'.

path = merge_relative_path(u'../works/myproj.prj', u'abc.dat')
# path is equal to '../works/abc.dat'.

path = merge_relative_path(u'../works/myproj.prj', u'/pci/demo/irvine.pix')
# path is equal to '/pci/demo/irvine.pix'.

# If the current working directory is '/usr/projects', then you can
# get an absolute path for a relative filename with:

path = merge_relative_path(None, u'myproj.prj')
# path is equal to '/usr/projects/myproj.prj'.
pci.change_relative_base((object)related_file, (object)original_base_file, (object)new_base_file) object :

Change the relative base of a relative path.

This function changes a path, relative to one file, and makes it relative to another file. This is useful when two files need to refer to the same file via relative paths.

If related_file is absolute then original_base_file is ignored. If related_file is relative then it is merged with original_base_file (using merge_relative_path()) to create an absolute path. That new absolute path is then relativized using new_base_file as the base.

from pci import change_relative_base


path = change_relative_base(u'ottawa_parks.pix',
                            u'/parks/ontario/parks.txt',
                            u'/parks/outaouais/all_parks.txt')
# path is equal to '../ontario/ottawa_parks.pix'

path = change_relative_base(u'extents/gatineau_park.pix',
                            u'/parks/canada/quebec/all/parks.txt',
                            u'/parks/outaouais/parks.txt')
# path is equal to '../canada/quebec/all/extents/gatineau_park.pix'

3.6.2. Version Information

pci.version

The major.minor.micro numerical version of this release.

pci.version_name

The name of the version of the release.

New in version 2019: (Banff)

3.6.3. Basic types

These are some basic C++ types exposed to Python for interoperation with Boost::Python

class pci.string_([(str) s=""])

The C++ std::string class exposed to Python with boost::python (also known as PCI_STRING. string_ in PCI software). It can be converted implicitly by Python to and from a Python str.

Most operations that can be performed on a str, such as indexing or calling len(), can also be performed on string_.

str()

Explicitly convert to a Python str.

class pci.int_

32-bit signed integer. This class cannot be created directly from Python, but boost::python will automatically convert between this type and a Python int.

class pci.uint_

32-bit unsigned integer. This class cannot be created directly from Python, but boost::python will automatically convert between this type and a Python int.

3.6.4. Containers

Several functions in the CATALYST Python API use the C++ std::vector. Several std::vector implementations are included with this module.

The std::vector (or Vec*) classes behave similarly to a Python list, except they can hold only one specific type. Many operations that can be performed on a list can also be performed on one of the Vec* classes, such as indexing, or append and extend.

class pci.VecInt

A vector of int_

append((int_) x)

Append a new int_ with value x to the end of the vector.

extend(iterable)

Append items from iterable to the end of the vector. All items in iterable must be implcitly convertible to type int_

class pci.VecUInt

A vector of uint_

append((uint_) x)

Append a new uint_ with value x to the end of the vector.

extend(iterable)

Append items from iterable to the end of the vector. All items in iterable must be implcitly convertible to type uint_

class pci.VecDouble

A vector of float

append((float) x)

Append a new float with value x to the end of the vector.

extend(iterable)

Append items from iterable to the end of the vector. All items in iterable must be implcitly convertible to type float

3.6.5. CATALYST algorithm utility

pci.algo = <pci._auto_import object>

A special object that can be used to import any CATALYST algorithm. Instead of manually importing each algorithm module, pci.algo can be used to import these modules on the fly.

The following examples demonstrate how using pci.algo can simplify your imports:

Without pci.algo:

 1# import each module separately
 2from pci.fimport import fimport
 3from pci.pciadd2 import pciadd2
 4from pci.fav import fav
 5from pci.fme import fme
 6
 7# call each function
 8fimport(...)
 9pciadd2(...)
10pciadd2(...)
11fav(...)
12fme(...)

With pci.algo:

1# only one import
2from pci import algo
3
4# use pci.algo to call functions
5algo.fimport(...)
6algo.pciadd2(...)
7algo.pciadd2(...)
8algo.fav(...)
9algo.fme(...)