Welcome to Python-flavored Magnum! Please note that, while already being rather stable, this functionality is still considered experimental and some APIs might get changed without preserving full backwards compatibility.

magnum.scenegraph module

Scene graph library

The Python API for SceneGraph provides, similarly to C++, multiple different transformation implementations. Recommended usage is importing desired implementation akin to typedefing the types in C++:

#include <Magnum/SceneGraph/Object.h>
#include <Magnum/SceneGraph/Scene.h>
#include <Magnum/SceneGraph/MatrixTransformation3D.h>

typedef SceneGraph::Scene<SceneGraph::MatrixTransformation3D> Scene3D;
typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D;

C++

from magnum import scenegraph
from magnum.scenegraph.matrix import Scene3D, Object3D

Python

Scene vs Object

In C++, the Scene is a subclass of Object. However, because the Scene object is not transformable nor it’s possible to attach features to it, most of the inherited API is unusable. This could be considered a wart of the C++ API, so the Python bindings expose Scene and Object as two unrelated types and all APIs that can take either a Scene or an Object have corresponding overloads.

Reference counting

Compared to C++, the following is done with all Object instances created on Python side:

  • the object is additionally referenced by its parent (if there’s any) so objects created in local scope stay alive even after exiting the scope
  • deleting its parent (either due to it going out of scope or using del in Python) will cause it to have no parent instead of being cascade deleted (unless it’s not referenced anymore, in which case it’s deleted as well)
  • in order to actually destroy an object, it has to have no parent

For features it’s slightly different:

  • the feature is additionally referenced by the holder object so features created in local scope stay alive even after exiting the scope
  • deleting the holder object (either due to it going out of scope or using del in Python) will cause it to be without a holder object (unless it’s not referenced anymore, in which case it’s deleted as well) — this makes any further operations on it impossible and likely dangerous
  • in order to actually destroy a feature, it has to have no holder object

Modules

module matrix
General matrix-based scene graph implementation
module trs
Translation/rotation/scaling-based scene graph implementation

Classes

class AbstractFeature2D
Base for two-dimensional float features
class AbstractFeature3D
Base for three-dimensional float features
class AbstractObject2D
Base object for two-dimensional scenes
class AbstractObject3D
Base object for three-dimensional scenes
class Camera2D
Camera for two-dimensional float scenes
class Camera3D
Camera for three-dimensional float scenes
class Drawable2D
Drawable for two-dimensional float scenes
class Drawable3D
Drawable for three-dimensional float scenes
class DrawableGroup2D
Group of drawables for two-dimensional float scenes
class DrawableGroup3D
Group of drawables for three-dimensional float scenes

Enums

class AspectRatioPolicy: NOT_PRESERVED = 0 EXTEND = 1 CLIP = 2
Camera aspect ratio policy