Python Bindings of the OPALS Datamanager Library

Table of Contents

• Differences of the DM API in C++ and Python
• Class Naming Schema in C++ and Python
• Performance of the Python Binding
• Notes on the Python Documentation
• Examples

The python binding (pyDM) of the C++ OPALS Datamanager Library exposes its functionality to python. Except of a some minor naming differences and some small differences caused by the language itself (mainly due to the python iterator concept) the python binding nearly completely matches the C++ Interface.

Before using the DM Library you should at least read The C++ OPALS Datamanager Library section, since it describes the central implementation concepts of the library. Then have a look at the examples section, which should give you a good starting point for your development. Each example is given in C++ and python. There the high similarity of the two interfaces is easy visible.

Differences of the DM API in C++ and Python

There are three major differences which are described in details in the following:

• The C++ library makes use of the loose coupling principle. This means that the implementation is fully hidden to the API user. The functionality is exposed through interface (=abstract class) only, which is why all interface classes start with an I. The creation of DM objects is either done through special 'new' functions (DM::IPoint::New, DM::IWindow::New, ...) or through factory objects (DM::IPolygonFactory, DM::IAddInfoLayoutFactory, ..) in case of complex object construction. This means that all DM objects are created on the heap, leaving the destruction of the objects to the developers responsibility. To support the developer and to avoid memory leaks, the C++ library comes with a smart pointer class (DM::Handle), automatically taking care of the object destruction. So for each interface a corresponding smart pointer class exists (e.g. DM::IPoint / DM::PointHandle, DM::IBox / DM::BoxHandle). This effort is not necessary within in python, since the language natively work with smart pointers and garbage collection. Hence, the python classes were named like the C++ class without the leading I. A few examples are listed in a table in the section below.

• The static 'New' functions (construction of objects) in C++ were translated to the native python object constructors 'init'. The following example shows the creation of a DM point (coordinates set to 0/0/0) in C++

  DM::PointHandle pt = DM::IPoint::New(0,0,0)

  and in python

  pt = pyDM.Point(0,0,0)

• Although python and C++ support iterators there are significant differences in there usage. In the following a code snippet is presented, showing the way of iterating over all points of an ODM in C++

  for(auto it = odm->beginPoints(); it != odm->endPoints(); ++it)
  {
    const DM::IPoint &pt = *it; //do something with DM point pt
  }

  and in python

  for pt in odm.points():
    # do something with DM point pt

Class Naming Schema in C++ and Python

C++ class name	python class name	Description
DM::IPoint	pyDM.Point	3d point object
DM::IBox	pyDM.Box	3d box object
DM::IDatamanager	pyDM.Datamanager	ODM object

Performance of the Python Binding

Python is a powerful scripting language and therefore, an efficient tool for prototyping. Due to the huge number of extensions (many optimized C++ libraries provide a python binding. E.g. scipy, numpy, ...), python turned into a programming language for real-life software projects. In terms of performance, however, python cannot compete with C++ or similar languages. This is of minor concern in 'low performance' applications or if time critical section are computed by optimised libraries 'outside' of python. The python bindings of the OPALS modules represent the later case. The python binding of the DM provide low level access to the objects within an ODM, and allow manipulating or processing ODMs in a similar way as existing modules OPALS do. Considering the aforementioned statements, processing of huge point clouds on a point bases within python is not recommended. The bindings are useful for testing new processing strategies on small test sets, but for huge data sets (billon of points) it is recommended to switch to C++ or to use high level functionality (e.g. Datamanager.getHistogramSet, RConverter, etc. ) only. Depending on the task to perform, single point processing in python is between 3 to 10 times slower than in C++ (without any optimisation in C++)

Notes on the Python Documentation

Due to the high similarity of the C++ and the python DM API, the C++ documentation of the DM is 'copied' to python. So it may appear that the python documentation contains links to the C++ documentation. If a function is not documented, it is well worth to have a look at the C++ documentation. Maybe it's described there.
Please note that the python documentation is derived in an external process which is why the python DM module does only partly contain the corresponding doc strings. So always have a look to the external documentation.

Examples

Examples demonstrating the usage of the python DM API can be found here :