pygfx.utils.transform.AffineBase

class pygfx.utils.transform.AffineBase(*, reference_up=(0, 1, 0), is_camera_space=False)

Bases: object

Base class for affine transformations.

Warning

In-place updates of slices of properties, e.g. transform.position[1] = 42 have no effect due to limitations of the python programming language and our decision to have the properties return pure numpy arrays.

This class implements basic getters and setters for the various properties of an affine transformation used in pygfx. If you are looking for obj.local.<something> or obj.world.<something> it is probably defined here.

The class further implements a basic callback system that will eagerly inform callees whenever the transform’s state changes. Callees register callbacks using the callback_id = transform.on_update(...) method and - if the callee is a class - may optionally choose to decorate the callback method with the @callback descriptor defined above. This will turn the callback into a weakref and allow the callee to be garbage collected more swiftly. After registration callees can remove the callback by calling transform.remove_callback and passing the callback. Callees can also pass the callback_id returned when the callback was first registered (useful e.g. if the callback was a lambda).

It also implements a basic caching mechanism that keeps computed properties around until the underlying transform changes. This makes use of the @cached descriptor defined above. The descriptor expects a last_modified property on the consuming class which is used as a monotonously increasing timestamp/counter to indicate if and when a cached value has become invalid. Once invalid, cached values are updated upon the next read/get meaning that they are updated lazily.

Parameters:

• reference_up (ndarray, [3]) – The direction of the reference_up vector expressed in the target frame. It indicates neutral tilt and 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 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

Subclasses need to define and implement last_modified for the caching machnism to work correctly. Check out existing subclasses for an example of how this might look like.

All properties are expressed in the target frame, i.e., they use the target’s basis, unless otherwise specified.

property matrix

Affine matrix describing this transform.

vec_target = matrix @ vec_source.

flag_update()

Signal that this transform has updated.

on_update(callback) → int

Subscribe to updates of this transform.

The provided callback will be executed after this transform has updated using the signature callback(self), i.e., it is passed a reference to this transform.

Parameters:

callback (Callable) – The callback to be executed after an update.

Returns:

callback_id – A ID to uniquely identify this callback and allow unsubscribing.

Return type:

int

remove_callback(ref) → None

Unsubscribe from updates of this transform.

Parameters:

ref (int, Callable) – The callback (or callback_id) to unsubscribe.

property inverse_matrix: ndarray

Inverse of this transform as affine matrix.

vec_source = inverse_matrix @ vec_target

property position: ndarray

The origin of source.

property rotation: ndarray

The orientation of source as a quaternion.

property euler: ndarray

The orientation of source as XYZ euler angles.

property rotation_matrix: ndarray

The orientation of source as a rotation matrix.

property euler_x: float

The X component of source’s orientation as XYZ euler angles.

property euler_y: float

The Y component of source’s orientation as XYZ euler angles.

property euler_z: float

The Z component of source’s orientation as XYZ euler angles.

property scale: ndarray

The scale of source.

property reference_up: ndarray

The zero-tilt reference vector used for the direction setters.

property x: float

The X component of source’s position.

property y: float

The Y component of source’s position.

property z: float

The Z component of source’s position.

property scale_x: float

The X component of source’s scale.

property scale_y: float

The Y component of source’s scale.

property scale_z: float

The Z component of source’s scale.

property right

The right direction of source.

property up

The up direction of source.

property forward

The forward direction of source.