Clarisse 4.0 SP3 SDK  4.0.0.0.3
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
The Python wrapped C++ API

Table of Contents

Basic types

Basic types (numeric and string) are automatically converted between C++ and Python ones.

Array/list types

Clarisse API relies on it's own C++ template classes for arrays and lists. A C++ template class is a class operating on generic types while sharing the same implementation. Template specialization for a specified type/class is performed during compilation. This is the reason why, template classes come with their source code. For example, Clarisse API provides CoreArray<T> which defines a generic array. To specify a CoreArray of int in C++ you need to declare:

When the class is specialized in the code for the first time, the compiler will initiate it. This is why it needs to have access to its code.

Unfortunately, template classes have no direct equivalent in Python. Due to the special way they are declared in C++, there's no one-to-one class name translation possible between the C++ API and the Python one.

Indeed, CoreArray of OfObject will be declared, CoreArray<OfObject> in C++. As you know, no equivalent notation is available in Python. To resolve this issue, we chose to prefix Clarisse API template classes by the class name they define. For example:

As a general rule, when you see, in the C++ API, a method expecting a CoreArray or a CoreVector just remember the naming convention described above.

For example, when you want to get the objects of the project, you need to call the method OfObjectFactory::get_objects. However, if you have a look at the documentation, you can see this method expects a CoreArray<OfObject *> as argument. In Python you just need to:

1 objects = ix.api.OfObjectArray() # creates a new CoreArray<OfObject *>
2 ix.application.get_factory().get_objects(objects)

Clarisse Run-time type information (RTTI)

Clarisse API provides its own RTTI system. As soon as an object inherits from CoreBaseObject, you check its type using CoreBaseObject::get_class_info and CoreBaseObject::class_info. CoreBaseObject::class_info is a static method that returns the CoreClassInfo of the specified class.

CoreBaseObject::get_class_info resolves the whole inheritance tree and returns the CoreClassInfo of the current class. For example, calling get_class_info() on a ModuleSceneItem will return ModuleSceneItem::class_info.

To check if an object inherits from a specific class you can use:

1 if (obj.get_module().is_kindof(ix.api.ModuleSceneItem.class_info()): ...

Automatic down-casting

Clarisse RTTI is used to automatically downcast the object to its Python interface. For example, OfObject::get_module returns an abstract ModuleObject *. In C++, you need to manually downcast to the right module whereas in Python the return module is automatically downcast.

Const Correctness Limitation

Const correctness isn't supported by SWIG the library used to expose the C++ API to Python. This has a strong side effect to let you modify things you are not supposed to in Python. This is extremely hazardous in run-time. For example, it's currently possible via Python to directly modify the array of materials of a specific scene object without using the appropriate methods. If you look at the ModuleSceneObject::get_materials the return value is const. Normally, you can't call non-const methods on those instances. However, in the Python API generated by SWIG, nothing prevents you from calling a non-const method. This should be normally automatically prohibited as it leads to massive instabilities. Hopefully this will change, one way or another, in the future. Currently, we try to avoid exposing such methods and replace them with safer ones.