blueprints.utils.geometry module#

Geometry contains primitive functions for geometric operations on MoveableThings position and orientation. Orientations are currently only supported for (improper) Euler angles and angles are currently assumed to be in radian. To convert angles the predefined constants DEGREES_TO_RADIANS and RADIANS_TO_DEGREES can be used.

blueprints.utils.geometry.TAU#

Tau is the circumference of a unit circle. \(\pi \times 2 = \tau\).

Type:

float

blueprints.utils.geometry.PI#

Pi is the half circumference of a unit circle. \(\pi \times 2 = \tau\).

Type:

float

blueprints.utils.geometry.DEGREES_TO_RADIANS#

To convert an angle in degrees to radian it can be multiplied with this constant.

Type:

float

blueprints.utils.geometry.RADIANS_TO_DEGREES#

To convert an angle in radian to degrees it can be multiplied with this constant.

Type:

float

class blueprints.utils.geometry.Rotation[source]#

Bases: object

This class implements multiple functions that operate on a MoveableThings orientation.

X#

The unit vector \(\vec{\text{id}_x}\) representing the X-axis.

Type:

np.ndarray

Y#

The unit vector \(\vec{\text{id}_y}\) representing the Y-axis.

Type:

np.ndarray

Z#

The unit vector \(\vec{\text{id}_z}\) representing the Z-axis.

Type:

np.ndarray

X = array([1, 0, 0])#
Y = array([0, 1, 0])#
Z = array([0, 0, 1])#
classmethod euler(vector, alpha, beta, gamma)[source]#

Rotates a vector according to improper euler angles.

Parameters:

  • vector (np.ndarray) – The vector to be rotated.

  • alpha (float) – The angle along which the vector is rotated on the X-axis.

  • beta (float) – The angle along which the vector is rotated on the Y-axis.

  • gamma (float) – The angle along which the vector is rotated on the Z-axis.

Returns:

The rotated vector.

Return type:

np.ndarray

classmethod rotate_around_axis(vector, axis, angle)[source]#

Rotates a vector around an axis for a given angles.

Parameters:

  • vector (np.ndarray) – The vector to be rotated

  • axis (np.ndarray) – The axis around which the vector is rotated according to the right hand rule.

  • angle (float) – The angle by which the vector is rotated.

Returns:

The rotated vector.

Return type:

np.ndarray

classmethod global_orientation(node)[source]#

This method calculates the global orientation of a Thing (typically a node in a kinematic tree).

Parameters:

node (Thing) – A Thing (typically a node in a kinematic tree) for which the global orientation is calculated w.r.t it’s root.

Returns:

The improper euler angles representing the global orientation.

Return type:

(float, float, float)

classmethod global_rotation_matrix(node)[source]#

This method calculates the rotation matrix for the global orientation of a Thing (typically a node in e kinematic tree) w.r.t. to its root.

Parameters:

node (Thing) – A Thing (typically a node in a kinematic tree) for which the global orientation is calculated w.r.t it’s root.

Returns:

The global orientation matrix for the node.

Return type:

np.ndarray

classmethod euler_to_reference_frame(alpha, beta, gamma)[source]#

This method constructs a reference frame (i. e. the unit vectors for the axis of the local coordinate system) for (improper) euler angles.

Parameters:

  • alpha (float) – The angle by which the X-axis is rotated to reach the reference frame.

  • beta (float) – The angle by which the Y-axis is rotated to reach the reference frame.

  • gamma (float) – The angle by which the Z-axis is rotated to reach the reference frame.

Returns:

A tuple of the three unit vectors for the given orientation representing the reference frame.

Return type:

(np.ndarray, np.ndarray, np.ndarray)

classmethod reference_frame_to_euler(R)[source]#

Computes the (improper) euler angles that lead to the given reference frame.

Parameters:

R (np.ndarray) – A matrix representing the reference frame as a concatenation of the unit coulmn vectors of the orientations coordinate system.

Returns:

The (improper) euler angles for the given reference frame.

Return type:

(float, float, float)

Raises:

ArithmeticError –

:raises If the reference frame does not contain orthogonal vectors that do not adhere` to :py:class:`the right hand rule convention am ArithmeticError is raised.:

classmethod angle(a, b, axis=None)[source]#

Computes the angle between two vectors. If axis is set, the angle is measured according to a rotation around axis from a to b, otherwise the shortest angle is returned.

Parameters:

  • a (np.ndarray) – A vector for which the angle is computed w.r.t. b.

  • b (np.ndarray) – A vector for which the angle is computed w.r.t. a.

  • axis (None|np.ndarray, optional) – The axis of rotation can be specified optionally, if this is not done, the resulting angles will be in the range [0, PI).

Returns:

The resulting angle will be in the range [0, PI) if axis is not specified, otherwise the angle will be in the range [0, TAU).

Return type:

float

classmethod N_rot(node=None)[source]#

This method returns the rotation matrix for a given Thing. If the Thing does not inherit from MoveableThing the identity metrix is returned.

Parameters:

node (None, ThingType) – A Thing, typically a node from a kinematic tree.

Returns:

A rotation matrix from the Things orientation.

Return type:

np.ndarray

static X_rot(alpha)[source]#

Constructs the rotation matrix around the X-axis for a given angle.

Parameters:

alpha (float) – The angle of rotation.

Returns:

The rotation matrix for the given angle.

Return type:

np.ndarray

static Y_rot(beta)[source]#

Constructs the rotation matrix around the Y-axis for a given angle.

Parameters:

beta (float) – The angle of rotation.

Returns:

The rotation matrix for the given angle.

Return type:

np.ndarray

static Z_rot(gamma)[source]#

Constructs the rotation matrix around the Z-axis for a given angle.

Parameters:

gamma (float) – The angle of rotation.

Returns:

The rotation matrix for the given angle.

Return type:

np.ndarray

classmethod E_rot(alpha=None, beta=None, gamma=None)[source]#

Constructs the rotation matrix for improper euler angles.

Parameters:

  • alpha (float) – The angle around which the X-axis is rotated.

  • beta (float) – The angle around which the Y-axis is rotated.

  • gamma (float) – The angle around which the Z-axis is rotated.

Returns:

The rotation matrix for the improper euler angles.

Return type:

np.ndarray

classmethod Axis_rot(R)[source]#
Returns:

The axis of rotation for a given rotation matrix or reference frame

Return type:

np.ndarray

classmethod quat_to_euler(R, I, J, K)[source]#
Parameters:

  • R (float) – The real rotation angle component of the quaternion.

  • I (float) – The X-axis component of the quaternion.

  • J (float) – The Y-axis component of the quaternion.

  • K (float) – The Z-axis component of the quaternion.

Returns:

The improper euler angles for a given quaternion.

Return type:

tuple[float]

classmethod euler_to_quat(alpha, beta, gamma)[source]#
Parameters:

  • alpha (float) – The angle around which the X-axis is rotated.

  • beta (float) – The angle around which the Y-axis is rotated.

  • gamma (float) – The angle around which the Z-axis is rotated.

Returns:

The quaternion components for improper euler angles.

Return type:

tuple[float]

class blueprints.utils.geometry.Vector[source]#

Bases: object

This class implements multiple functions to modify vectors and orientations of MoveableThings.

classmethod get_axis(axis)[source]#

This method returns a vector that represents the axis which is either given as a str or as a 1D array like object.

>>> Vector.get_axis("x")
array([1., 0., 0.])
>>> Vector.get_axis([0., 1., 0.])
array([0., 1., 0.])
>>> Vector.get_axis(np.array([0., 0., 1.]))
array([0., 0., 1.])
Parameters:

axis (str | list[int | float] | np.ndarray) – The axis argument may be either a 1D array like object or a string (‘x’, ‘y’, ‘z’).

Returns:

The specified axis converted to a numpy array.

Return type:

np.ndarray

Raises:

  • ValueError –

  • If the axis argument is a string` and neither 'x', 'y' or 'z' a ValueError is raise –

static equal(a, b, sensitivity=8)[source]#

Compares whether two vectors are equal within a margin of error as given by sensitivity.

>>> a = np.array([3.2, 0., 0.])
>>> b = np.array([3.8, 0., 0.])
>>> c = np.array([3.2, 5., 0.])
>>> Vector.equal(a, b, sensitivity=0)
True
>>> Vector.equal(a, b, sensitivity=1)
False
>>> Vector.equal(a, c, sensitivity=0)
False
>>> Vector.equal(a, c, sensitivity=-1)
True
Parameters:

  • a (np.ndarray) – A vector to be compared.

  • b (np.ndarray) – A vector to be compared.

  • sensitivity (int, optional) – The floating point decimal cutoff.

Returns:

A boolean indicating whether the two vectors are equal within the specified margin of error.

Return type:

bool

classmethod global_position(node, pos=None)[source]#

This method converts the local position of a Thing (typically a node in a kinematic tree) to its global position relative to the nodes root.

Parameters:

  • node (Thing) – A Thing (typically a node in a kinematic tree).

  • pos (None, optional) – An initial position that is assumed to be located relative to the node.

Returns:

The global position relative to root of the given node, or the initial position relative to the node is pos was specified.

Return type:

np.ndarray

static normalize(vector)[source]#

This method normalizes a vector to a unit lenth of 1.

Parameters:

vector (np.ndarray) – A vector to be normalized.

Returns:

The normalized vector.

Return type:

np.ndarray

static distance(a, b)[source]#

This method returns the distance between two vectors or MoveableThings.

Parameters:

  • a (np.ndarray | blue.MoveableThingType) – A vector or MoveableThings global position for which the distance is computed w.r.t. b.

  • b (np.ndarray | blue.MoveableThingType) – A vector or MoveableThings global position for which the distance is computed w.r.t. a.

Returns:

The distance betweent the two vectors or MoveableThings.

Return type:

float