Ctrl+K

Orientations#

Classes:

Orientations([quat, normalize, copy])

This class for Orientations in the three-dimensional space, is a subclass of scipy.spatial.transform.Rotation and equally based on quaternions of shape (N, 4).
class pyfar.classes.orientations.Orientations(quat=None, normalize=True, copy=True)[source]#

Bases: Rotation

This class for Orientations in the three-dimensional space, is a subclass of scipy.spatial.transform.Rotation and equally based on quaternions of shape (N, 4). It inherits all methods of the Rotation class and adds the creation from perpendicular view and up vectors and a convenient plot function.

An orientation can be visualized with the triple of view, up and right vectors and it is tied to the object’s local coordinate system. Alternatively the object’s orientation can be illustrated with help of the right hand: Thumb (view), forefinger (up) and middle finger (right).

Examples

>>> from pyfar import Orientations
>>> views = [[1, 0, 0], [2, 0, 0]]
>>> ups = [[0, 1, 0], [0, -2, 0]]
>>> orientations = Orientations.from_view_up(views, ups)

Visualize orientations at certain positions:

>>> positions = [[0, 0.5, 0], [0, -0.5, 0]]
>>> orientations.show(positions)

Rotate first element of orientations:

>>> from scipy.spatial.transform import Rotation
>>> rot_x45 = Rotation.from_euler('x', 45, degrees=True)
>>> orientations[1] = orientations[1] * rot_x45
>>> orientations.show(positions)

To create Orientations objects use from_... methods. Orientations(...) is not supposed to be instantiated directly.

quat#

Each row is a (possibly non-unit norm) quaternion in scalar-last (x, y, z, w) format. Each quaternion will be normalized to unit norm.

Type:

array_like, shape (N, 4) or (4,)

Methods:

__init__([quat, normalize, copy])

as_view_up_right()

Get Orientations as a view, up, and right vector.

copy()

Return a deep copy of the Orientations object.

from_view_up(views, ups)

Initialize Orientations from a view an up vector.

show([positions, show_views, show_ups, ...])

Visualize Orientations as triples of view (red), up (green) and right (blue) vectors in a quiver plot.
__init__(quat=None, normalize=True, copy=True)[source]#
as_view_up_right()[source]#

Get Orientations as a view, up, and right vector.

Orientations are internally stored as quaternions for better spherical linear interpolation (SLERP) and spherical harmonics operations. More intuitionally, they can be expressed as view and and up of vectors which cannot be collinear. In this case are restricted to be perpendicular to minimize rounding errors.

Returns:

vector_triple –

  • views, see Orientations.from_view_up.__doc__

  • ups, see Orientations.from_view_up.__doc__

  • rights, see Orientations.from_view_up.__doc__

    A single vector or a stack of vectors, pointing to the right of the object, constructed as a cross product of ups and rights.

Return type:

ndarray, shape (N, 3), normalized vectors

copy()[source]#

Return a deep copy of the Orientations object.

classmethod from_view_up(views, ups)[source]#

Initialize Orientations from a view an up vector.

Orientations are internally stored as quaternions for better spherical linear interpolation (SLERP) and spherical harmonics operations. More intuitionally, they can be expressed as view and up vectors which cannot be collinear. In this case, they are restricted to be perpendicular to minimize rounding errors.

Parameters:

  • views (array_like, shape (N, 3) or (3,), Coordinates) – A single vector or a stack of vectors, giving the look-direction of an object in three-dimensional space, e.g. from a listener, or the acoustic axis of a loudspeaker, or the direction of a main lobe. Views can also be passed as a Coordinates object.

  • ups (array_like, shape (N, 3) or (3,), Coordinates) – A single vector or a stack of vectors, giving the up-direction of an object, which is usually the up-direction in world-space. Views can also be passed as a Coordinates object.

Returns:

orientations – Object containing the orientations represented by quaternions.

Return type:

Orientations instance

show(positions=None, show_views=True, show_ups=True, show_rights=True, **kwargs)[source]#

Visualize Orientations as triples of view (red), up (green) and right (blue) vectors in a quiver plot.

Parameters:

  • positions (array_like, shape (O, 3), O is len(self)) – These are the positions of each vector triple. If not provided, all triples are positioned in the origin of the coordinate system.

  • show_views (bool) – select wether to show the view vectors or not. The default is True.

  • show_ups (bool) – select wether to show the up vectors or not. The default is True.

  • show_rights (bool) – select wether to show the right vectors or not. The default is True.

Returns:

ax – The axis used for the plot.

Return type:

matplotlib.axes._subplots.Axes3DSubplot

On this page