Coordinate System

HermesPy’s coordinate sytem implementation defines classes for forward and backwards kinematics along a kinematic chain of multiple linked coordinate systems. They can be used to describe the position and orientation of objects in a 3D space depending on the position and orientation of other objects. More precisely, antenna elements within antenna arrays can be described in relation to the antenna array itself, which in turn can be described in relation to the device it is attached to. Devices can be described in relation to the global coordinate system, which is defined by the simulation environment and attached to moving geometric objects in the case of spatial simulations.

class Transformation

Bases: ndarray, Serializable

Coordinate system transformation.

classmethod Deserialize(process)

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:

process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.

Return type:

Transformation

Returns:

The deserialized object.

classmethod From_Quaternion(quaternion, pos, normalize_quaternion=True)

Initialize a transformation from a quaternion.

Parameters:

• quaternion (ndarray) – Quaternion in w, x, y, z representation.

• pos (ndarray) – Cartesian position in m.

• normalize – Normalize the quaternion before computing the rotation matrix. Enabled by default.

Return type:

Transformation

Returns: The initialized transformation.

classmethod From_RPY(rpy, pos)

Initialize a transformation from roll pitch yaw angles.

Parameters:

• rpy (ndarray) – Roll, pitch and yaw angles in radians.

• pos (ndarray) – Cartesian position in m.

Return type:

Transformation

Returns: The initialized transformation.

classmethod From_Translation(translation)

Return type:

Transformation

classmethod No()

Return type:

Transformation

invert()

Invert the transformation.

Returns: The inverted transformation.

Return type:

Transformation

lookat(target=array([0., 0., 0.]), up=array([0., 1., 0.]))

Rotate and loook at the given coordinates. Modifies orientation property.

Parameters:

• target (ndarray) – Cartesean coordinates to look at. Defaults to np.array([0., 0., 0.], float)

• up (ndarray) – Global catesean sky vector. Defines the upward direction of the local viewport. Defaults to np.array([0., 1., 0.], float)

Return type:

Transformation

Returns: This modified Transformation.

rotate_direction(direction)

Rotate a cartesian direction.

Parameters:

direction (ndarray) – A directional vector.

Return type:

Direction

Returns: The transformed direction.

Raises:

ValueError – If direction is invalid.

serialize(process)

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:

process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.

Return type:

None

transform_direction(direction, normalize=False)

Transform a direction.

Parameters:

• direction (ndarray) – Direction to be transformed.

• normalize (bool) – Normalize the resulting transformed direction to a unit norm vector. Disabled by default.

Return type:

Direction

Returns: The transformed direction.

transform_position(position)

Transform a cartesian position.

Parameters:

position (ndarray) – Numpy array representing the cartesian position.

Return type:

ndarray

Returns: The transformed position.

Raises:

ValueError – If position is invalid.

property rotation_quaternion: ndarray

Orientation in Quaternion representation.

A numpy vector representing w, x, y, z.

property rotation_rpy: ndarray

Orientation in Roll, Pitch and Yaw Angles.

Returns: Roll, Pitch and Yaw in Radians.

property translation: ndarray

class Transformable(pose=None)

Bases: Serializable, TransformableLink

Representation of a Coordinate Frame within a Kinematic Chain.

Parameters:

pose (Transformation | None) – Transformation of the transformable with respect to its reference frame. By default, no transformation is considered.

classmethod Deserialize(process)

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:

process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.

Return type:

Transformable

Returns:

The deserialized object.

lookat(target=array([0., 0., 0.]), up=array([0., 1., 0.]))

Rotate and loook at the given coordinates. Modifies orientation property.

Parameters:

• target (ndarray) – Cartesean coordinates to look at. Defaults to numpy.ndarray([0., 0., 0.], float).

• up (ndarray) – Global catesean sky vector. Defines the upward direction of the local viewport. Defaults to numpy.ndarray([0., 1., 0.], float).

Return type:

None

serialize(process)

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:

process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.

Return type:

None

set_base(base)

Set the relative base coordinate frame of this link.

Parameters:

base (TransformableLink | None) – The base to be coordinate frame to be set. None to detach the link.

Return type:

None

to_local_coordinates(arg_0, arg_1=None)

Return type:

Transformation

property backwards_transformation: Transformation

Transformation to convert global coordinates to local coordinates.

Updated every time the kinematic chain’s parameters change.

Returns: The transformation.

property forwards_transformation: Transformation

Transformation to convert local coordinates to global coordinates.

Updated every time the kinematic chain’s parameters change.

Returns: The transformation.

property global_orientation: ndarray

Orientation of the represented object within the global coordinate system.

Three-dimensional numpy vector representing roll, pitch and yaw in radians.

property global_position: ndarray

Position of the represented object within the global coordinate system.

Three-dimensional numpy vector representing the cartesian object coordinates.

property is_base: bool

Is this transformable acting as a base frame?

property orientation: ndarray

Orientation of the Transformable.

The transformation in radians for roll, pitch and yaw.

Raises:

ValueError – If orientation is not a three-dimensional numpy vector.

property pose: Transformation

Pose of the Transformable with respect to its reference link

property position: ndarray

Position of the transformable.

Cartesian x, y, z offset to the reference coordinate frame in m.

Raises:

ValueError – If position is not a valid three-dimensional vector.

property_blacklist = {'pose'}

class TransformableLink

Bases: object

Abstract base class of kinetmatic chain links.

add_link(link)

Establish a new link to a coordinate frame depending on this frame.

Parameters:

link (Transformable) – The transformable frame to be registered.

Return type:

None

remove_link(link, force_removal=True)

Remove an established link to this coordinate frame.

Parameters:

• link (Transformable) – The coordinate frame to be linked to this frame.

• force_removal (bool) – Raise a RuntimeError if the link is not registered

Raises:

RuntimeError – If the link is not currently registerd and force_removal is enabled.

Return type:

None

abstract set_base(base)

Set the relative base coordinate frame of this link.

Parameters:

base (TransformableLink | None) – The base to be coordinate frame to be set. None to detach the link.

Return type:

None

abstract property forwards_transformation: Transformation

Transformation to convert local coordinates to global coordinates.

Updated every time the kinematic chain’s parameters change.

Returns: The transformation.

property linked_frames: Set[TransformableLink]

class TransformableBase

Bases: TransformableLink

Base of kinematic chains.

set_base(base)

Set the relative base coordinate frame of this link.

Parameters:

base (TransformableLink | None) – The base to be coordinate frame to be set. None to detach the link.

Return type:

None

property forwards_transformation: Transformation

Transformation to convert local coordinates to global coordinates.

Updated every time the kinematic chain’s parameters change.

Returns: The transformation.

class Direction

Bases: ndarray

A cartesian unit norm vector pointing towards a direction.

classmethod From_Cartesian(vector, normalize=False)

Initialize a direction from a cartesian vector.

Raises:

ValueError – If vector does not represent a valid cartesian vector.

Returns: The initialized direction.

Return type:

Direction

classmethod From_Spherical(azimuth, zenith)

Initialize a direction from spherical parameters.

Parameters:

• azimuth (float) – Azimuth angle in radians.

• zenith (float) – Zenith angle in radians.

Return type:

Direction

Returns: The initialized direction.

to_spherical()

Represent the direction as spherical coordinates.

Returns: An array representing azimuth and zenith angles in radians.

Return type:

ndarray