RigidBodyPose¶

Attributes¶

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

Details¶

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


Warning

This class is experimental and may result in undefined behavior.

Parameters
• 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.

alignTo(alignTo)[source]

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.

property at

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

property bounds

Bounding box associated with this pose.

copy()[source]

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

distanceTo(v)[source]

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.

Parameters
• 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.

Returns

4x4 transformation matrix.

Return type

ndarray

Examples

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
glMatrixMode(GL_MODELVIEW)
glPushMatrix()
glMultTransposeMatrixf(mv)

# draw the thing here ...

glPopMatrix()

getNormalMatrix(out=None)[source]

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

getOriAxisAngle(degrees=True)[source]

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

getViewMatrix(inverse=False)[source]

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

getYawPitchRoll(degrees=True)[source]

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.

Parameters
• end (LibOVRPose) – End pose.

• s (float) – Interpolation factor between interval 0.0 and 1.0.

Returns

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

Return type

RigidBodyPose

property inverseModelMatrix

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

invert()[source]

Invert this pose.

inverted()[source]

Get a pose which is the inverse of this one.

Returns

This pose inverted.

Return type

RigidBodyPose

isEqual(other)[source]

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

property modelMatrix

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

property normalMatrix

The normal transformation matrix.

property ori

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

property pos

Position vector (X, Y, Z).

property posOri

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

setIdentity()[source]

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.

Parameters
• 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.

Parameters
• 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.

Returns

Transformed points.

Return type

ndarray

transformNormal(n)[source]

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

property up

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