Carmenta Engine Python API
The Carmenta Engine Python API was developed to support scripting of the Carmenta Engine functionality. It is intended to be used with ScriptOperator, in an application written with one of the other APIs. It is also possible to use the API from standalone Python scripts, but is not intended to be used for interactive map applications.
To build and install Python for use on Linux distributions that do not include the required version of Python, do the following:
Download the latest version of Python 3.10.
Run ./configure --enable-shared.
Run make.
As the superuser run: make install and ldconfig.
On Red Hat Enterprise Linux you might need to add the /usr/local/lib directory to the system library path before running ldconfig. It can be done by running echo /usr/local/lib > /etc/ld.so.conf.d/local.conf as the superuser.
The API contains:
A Python® runtime engine (http://www.python.org, version 3)
Python extension modules, one for each module of Carmenta Engine.
Documentation showing how the API should be used (this document), plus reference documentation for all the Python classes.
The Carmenta Engine Python API is available in a separate installation package. To access the Carmenta Engine Python API, this separate package needs to be installed together with the Carmenta Engine SDK base installation.
To use the Python API for Linux on Windows, using WSL, some packages located in the linux folder in the Carmenta Engine SDK directory, typically /mnt/c/Program Files/Carmenta Engine 5 SDK/linux, must also be installed.
apt install ./carmenta-engine_*_amd64.deb ./carmenta-engine-python_*_amd64.deb
Limitations
The Carmenta Engine Python API is written as Python C extension modules. Like the other Carmenta Engine APIs, the Python modules are thin wrappers around the kernel classes. The object model is the same as in the other APIs, but with a few limitations:
There is no GUI support, i.e. no map control classes or interaction tools.
Custom objects (other than ScriptOperator) can not be written in Python.
Events and delegates are not supported.
Using the Python API
Importing Carmenta Engine modules
To access the functions and classes in the Python API, you must first import the proper modules. The modules are called Carmenta.Engine.<module>. For instance, if your script uses the Core, Operators and DataSets modules, you should import the following modules:
from Carmenta.Engine.Core import *
from Carmenta.Engine.Operators import *
from Carmenta.Engine.DataSets import *
Note that if the script is called from a ScriptOperator, the Core and CustomObjects modules will already have been imported.
Object creation and destruction
Objects in Carmenta Engine can be created from the configuration file or using the API. Both reference classes and value classes are created using normal Python syntax, for instance:
drawable = ...
layers = ...
v = View(drawable, layers)
v.width = 10
v.center = Point(20, 20)
Python automatically keeps reference counts of all objects and deletes them automatically when they are no longer referenced.
The constructors (__init__ methods) accept both positional and keyword arguments. The beginning of the argument list must match one of the constructor overloads found in the documentation of a class. After that you can pass keyword arguments matching writable properties of the class. For example, the code above can also be written as:
drawable = ...
layers = ...
v = View(drawable, layers, width = 10, center = Point(20, 20))
Collections
Collections in the Python API hold references to a corresponding kernel collection; modifying the API collection affect the kernel object directly. As an example, the following code will add a layer to the layer collection of a view:
myView.layers.append(aNewLayer)
The collections classes implement the standard Python Sequence protocol, and slicing is fully supported. Also, methods taking collections as input parameters accept both Carmenta Engine and standard Python collections.
Enumerations
Enumerations are implemented as Python classes, with static members for the different enumeration values. The members are themselves instances of the class.
Some enumerations have members called "None". Since None is a reserved keyword in Python, these members can not be accessed the usual way, like AlignX.None. To get around this you can use the Python getattr() function, e.g. getattr(AlignX, 'None').
Error handling
In case of errors, one of the standard Python exceptions is thrown, usually RuntimeError.
Initialization and cleanup
Standalone scripts must explicitly initialize and shutdown the Carmenta Engine runtime. The script should call Runtime.Initialize before calling any other Carmenta Engine code, and Runtime.Shutdown before terminating.
For scripts called from ScriptOperator, this is done automatically.