pygfx.utils.transform.RecursiveTransform

class pygfx.utils.transform.RecursiveTransform(base: AffineTransform, /, *, parent: RecursiveTransform = None, reference_up=(0, 1, 0), 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 combining 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 base), similar to how AffineTransform wraps a numpy array. Setting properties of RecursiveTransform will 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.

Parameters:

base (AffineTransform) – The base transform that will be wrapped by this transform.
parent (RecursiveTransform, 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.