`RigidBodyPose`¶

Attributes¶

RigidBodyPose([pos, ori, dtype])

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), dtype=None)[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.
dtype (dtype or str, optional) – Data type for computations can either be ‘float32’ or ‘float64’. Default is None which uses the default data configured by setDefaultPrecision.

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 RigidBodyPose) – 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.

clear()[source]¶: Clear the pose, setting position and orientation to zero.

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

property dtype¶

Data type used for computations and arrays (numpy.dtype).

Cannot be changed after object creation.

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()
glLoadIdentity()
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, out=None)[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.
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

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 (RigidBodyPose) – 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).

property inverseViewMatrix¶: The inverse of the 4x4 view matrix for this pose (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 4x4 normal transformation matrix (read-only).

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 (alias for clear).

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.

property viewMatrix¶: The 4x4 view matrix for this pose (read-only).

RigidBodyPose¶

Attributes¶

Details¶

`RigidBodyPose`¶