pygfx.utils.transform.RecursiveTransform

class pygfx.utils.transform.RecursiveTransform(matrix: ndarray | AffineBase, /, *, parent=None, reference_up=None, is_camera_space=False)

Bases: AffineBase

A transform that may be preceded by another transform.

This transform behaves semantically identical to an ordinary AffineTransform (same properties), except that users may define a parent transform which precedes the matrix used by the ordinary AffineTransform. The resulting RecursiveTransform then controls the total transform that results from combinign the two transforms via:

recursive_transform = parent @ matrix

In other words, the source frame of RecursiveTransform is the source frame of matrix and the target frame of RecursiveTransform is the target frame of parent. Implying that RecursiveTransform’s properties are given in the target frame.

The use case for this class is to allow getting and setting of properties of a WorldObjects world transform, i.e., it implements WorldObject.world.

Under the hood, this transform wraps another transform (passed in as matrix), similar to how AffineTransform wraps a numpy array. It can also be initialized from a numpy array, in which case provided matrix is first wrapped into a AffineTransform which is then wrapped by this class. Setting properties of RecursiveTransform will then internally transform the new values into matrix target frame and then set the obtained value on the wrapped transform. This means that the parent transform is not affected by changes made to this transform.

Further, this transform monitors parent for changes (via a callback) and will update (invalidate own caches and trigger callbacks) whenever the parent updates. This allows propagating updates from the parent to its children, e.g., to update a child’s world transform when it’s parent changes position.

Parameters:

matrix (AffineBase, ndarray [4, 4]) – The base transform that will be wrapped by this transform.
parent (AffineBase, optional) – The parent transform that precedes the base transform.
reference_up (ndarray, [3]) – The direction of the reference_up vector expressed in the target frame. It is used by the axis properties (right, up, forward) to maintain a common level of rotation around an axis when it is updated by it’s setter. By default, it points along the positive Y-axis.
is_camera_space (bool) – If True, the transform represents a camera space which means that it’s forward and right directions are inverted.

Notes

Since parent is optional, this transform can also be used to create a synced copy of an existing transform similar to how a view works in numpy.