RigidBodyPose([pos, ori]) Class for representing rigid body poses.


class psychopy.visual.RigidBodyPose(pos=(0.0, 0.0, 0.0), ori=(0.0, 0.0, 0.0, 1.0))[source]

Class for representing rigid body poses.

This class is an abstract representation of a rigid body pose, where the position of the body in a scene is represented by a vector/coordinate and the orientation with a quaternion. Pose can be manipulated and interacted with using class methods and attributes. Rigid body poses assume a right-handed coordinate system (-Z is forward and +Y is up).

Poses can be converted to 4x4 transformation matrices with getModelMatrix. One can use these matrices when rendering to transform the vertices of a model associated with the pose by passing them to OpenGL. Matrices are cached internally to avoid recomputing them if pos and ori attributes have not been updated.

Operators * and ~ can be used on RigidBodyPose objects to combine and invert poses. For instance, you can multiply (*) poses to get a new pose which is the combination of both orientations and translations by:

newPose = rb1 * rb2

Likewise, a pose can be inverted by using the ~ operator:

invPose = ~rb

Multiplying a pose by its inverse will result in an identity pose with no translation and default orientation where pos=[0, 0, 0] and ori=[0, 0, 0, 1]:

identityPose = ~rb * rb


This class is experimental and may result in undefined behavior.

  • pos (array_like) – Position vector [x, y, z] for the origin of the rigid body.
  • ori (array_like) – Orientation quaternion [x, y, z, w] where x, y, z are imaginary and w is real.

Align this pose to another point or pose.

This sets the orientation of this pose to one which orients the forward axis towards alignTo.

Parameters:alignTo (array_like or LibOVRPose) – Position vector [x, y, z] or pose to align to.

Vector defining the forward direction (-Z) of this pose.


Bounding box associated with this pose.


Get a new RigidBodyPose object which copies the position and orientation of this one. Copies are independent and do not reference each others data.

Returns:Copy of this pose.
Return type:RigidBodyPose

Get the distance to a pose or point in scene units.

Parameters:v (RigidBodyPose or array_like) – Pose or point [x, y, z] to compute distance to.
Returns:Distance to v from this pose’s origin.
Return type:float
getModelMatrix(inverse=False, out=None)[source]

Get the present rigid body transformation as a 4x4 matrix.

Matrices are computed only if the pos and ori attributes have been updated since the last call to getModelMatrix. The returned matrix is an ndarray and row-major.

  • inverse (bool, optional) – Return the inverse of the model matrix.
  • out (ndarray or None) – Optional 4x4 array to write values to. Values written are computed using 32-bit float precision regardless of the data type of out.

4x4 transformation matrix.

Return type:



Using a rigid body pose to transform something in OpenGL:

rb = RigidBodyPose((0, 0, -2))  # 2 meters away from origin

# Use `array2pointer` from `psychopy.tools.arraytools` to convert
# array to something OpenGL accepts.
mv = array2pointer(rb.modelMatrix)

# use the matrix to transform the scene

# draw the thing here ...


Get the present normal matrix.

Parameters:out (ndarray or None) – Optional 4x4 array to write values to. Values written are computed using 32-bit float precision regardless of the data type of out.
Returns:4x4 normal transformation matrix.
Return type:ndarray

Get the axis and angle of rotation for the rigid body. Converts the orientation defined by the ori quaternion to and axis-angle representation.

Parameters:degrees (bool, optional) – Specify True if angle is in degrees, or else it will be treated as radians. Default is True.
Returns:Axis [rx, ry, rz] and angle.
Return type:tuple

Convert this pose into a view matrix.

Creates a view matrix which transforms points into eye space using the current pose as the eye position in the scene. Furthermore, you can use view matrices for rendering shadows if light positions are defined as RigidBodyPose objects.

Parameters:inverse (bool) – Return the inverse of the view matrix. Default is False.
Returns:4x4 transformation matrix.
Return type:ndarray

Get the yaw, pitch and roll angles for this pose relative to the -Z world axis.

Parameters:degrees (bool, optional) – Specify True if angle is in degrees, or else it will be treated as radians. Default is True.
interp(end, s)[source]

Interpolate between poses.

Linear interpolation is used on position (Lerp) while the orientation has spherical linear interpolation (Slerp) applied taking the shortest arc on the hypersphere.

  • end (LibOVRPose) – End pose.
  • s (float) – Interpolation factor between interval 0.0 and 1.0.

Rigid body pose whose position and orientation is at s between this pose and end.

Return type:



Inverse of the pose as a 4x4 model matrix (read-only).


Invert this pose.


Get a pose which is the inverse of this one.

Returns:This pose inverted.
Return type:RigidBodyPose

Check if poses have similar orientation and position.

Parameters:other (RigidBodyPose) – Other pose to compare.
Returns:Returns True is poses are effectively equal.
Return type:bool

Pose as a 4x4 model matrix (read-only).


The normal transformation matrix.


Orientation quaternion (X, Y, Z, W).


Position vector (X, Y, Z).


The position (x, y, z) and orientation (x, y, z, w).


Clear rigid body transformations.

setOriAxisAngle(axis, angle, degrees=True)[source]

Set the orientation of the rigid body using an axis and angle. This sets the quaternion at ori.

  • axis (array_like) – Axis of rotation [rx, ry, rz].
  • angle (float) – Angle of rotation.
  • degrees (bool, optional) – Specify True if angle is in degrees, or else it will be treated as radians. Default is True.
transform(v, out=None)[source]

Transform a vector using this pose.

  • v (array_like) – Vector to transform [x, y, z].
  • out (ndarray or None, optional) – Optional array to write values to. Must have the same shape as v.

Transformed points.

Return type:



Rotate a normal vector with respect to this pose.

Rotates a normal vector n using the orientation quaternion at ori.

Parameters:n (array_like) – Normal to rotate (1-D with length 3).
Returns:Rotated normal n.
Return type:ndarray

Vector defining the up direction (+Y) of this pose.

Back to top