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. Where possible these arrays are flagged as read-only.

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.

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 mechanism 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.

flag_update(): Signal that this transform has updated.

property reference_up: ndarray: The zero-tilt reference vector used for the direction setters.

property matrix: ndarray

Affine matrix describing this transform.

vec_target = matrix @ vec_source.

property scaling_signs: ndarray: Property used to track and preserve the scale factor signs over matrix decomposition operations.

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 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: ndarray: The right direction of source.

property up: ndarray: The up direction of source.

property forward: ndarray: The forward direction of source.