inertialsim.geometry ¶

Coordinates, rotations, rigid transforms, and units of measurement.

The geometry module provides:

methods to convert and validate user supplied inputs (arrays, vectors, matrices)
classes to represent and manipulate geometric quantities (vectors, translations, rotations, rigid transforms, poses, etc.) based on Lie group theory
classes to represent passive coordinate transforms

Input conventions

All inputs are expected to be in SI units.

By inertialsim convention, rotations and translations represent an active transformation (they act to rotate and translate an object relative to a fixed coordinate system). This is a common source of bugs, particularly in rotation logic. Reference [02], Reference [05], and Reference [11] discuss active vs. passive transforms in greater detail.

Because these conventions cannot be automatically validated, users must be aware of them and manage inputs and outputs.

Open-source packages

This module is tested for consistency against the following open source packages:

SciPy Spatial Transforms module: https://docs.scipy.org/doc/scipy/reference/spatial.transform.html
DFKI-RIC pytransform3d package: https://dfki-ric.github.io/pytransform3d/index.html

Classes:

Name	Description
`MatrixLieGroup`	An abstract base class for representing matrix Lie groups.
`ExtendedPose`	Pose plus velocity.
`Pose`	Pose (position and orientation).
`CoordinateTransform`	3-dimensional coordinate frame transforms.
`RigidTransform`	3-dimensional rigid body transforms.
`CoordinateRotation`	3-dimensional coordinate frame rotations.
`Rotation`	3-dimensional rotations of rigid bodies.
`CoordinateTranslation`	3-dimensional coordinate frame translations.
`Translation`	3-dimensional translations.
`Vector`	3-dimensional vectors.

Functions:

Name	Description
`identity_matrix`	Return an identity matrix.
`matrix_array`	Convert input to matrix array.
`ones_vector`	Return a vector array of ones.
`scalar_array`	Convert input to scalar array.
`vector_array`	Convert input to a vector array.
`zero_vector`	Return a vector array of zeros.

Attributes:

Name	Type	Description
`FP_TOLERANCE`		Default tolerance for floating point comparisons.

FP_TOLERANCE `module-attribute` ¶

FP_TOLERANCE = float(100.0 * eps)

Default tolerance for floating point comparisons.

MatrixLieGroup ¶

MatrixLieGroup(time: ArrayLike | None = None)

Bases: ABC

An abstract base class for representing matrix Lie groups.

Derived classes will inherit common Lie group operations such as composition, interpolation, etc.

See Reference [14], Reference [15], Reference [16], Reference [17], and Reference [18] for further details on Lie groups and their application to translations, rotations and rigid body motions.

Methods:

Name	Description
`from_identity`	Return an identity instance of the derived class.
`apply`	Apply the group action.
`compose`	Compose multiple instances of the group.
`inverse`	Return a new instance containing the inverse of the current one.
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

from_identity `abstractmethod` `classmethod` ¶

from_identity(num_elements: int) -> Self

Return an identity instance of the derived class.

Example: A rotation matrix is the group representation of the SO(3) rotations Lie group. So the Rotation subclass must provide a from_identity() constructor which returns an identity Rotation instance.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity elements to store.	required

Returns:

Name	Type	Description
`derived`	`Self`	Instance of the derived class (cls) with identity elements.

apply `abstractmethod` ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Apply the group action.

Apply the action of the Lie group to an input. Actions are rotations, rigid transforms, etc. defined in derived classes.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	Inputs.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	Modified inputs.

Raises:

Type	Description
`TypeError`	If the group action on the input has no physical meaning.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Compose multiple instances of the group.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of instances of the derived class to be composed from first to last. Instances must have compatible dimensions and types.	required

Returns:

Name	Type	Description
`composed`	`Self`	Instance of the class composed from the inputs.

inverse `abstractmethod` ¶

inverse() -> Self

Return a new instance containing the inverse of the current one.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance of the derived class with containing the inverse of the current instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

ExtendedPose ¶

ExtendedPose(
    attitude: Rotation,
    position: Translation,
    velocity: Vector,
    time: ArrayLike | None = None,
)

Bases: MatrixLieGroup

Pose plus velocity.

ExtendedPose behaves similarly to Pose with the addition of velocity.

Methods:

Name	Description
`compose`	Compose multiple instances of the group.
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_identity`	Construct an identity ExtendedPose.
`from_apv`	Construct an ExtendedPose from attitude, position, and velocity.
`from_random`	Construct an ExtendedPose from random data.
`as_apv`	Return the attitude, position, and velocity.
`as_attitude`	Return the attitude component of the ExtendedPose instance.
`as_position`	Return the position component of the ExtendedPose instance.
`as_velocity`	Return the velocity component of the ExtendedPose instance.
`apply`	Compound two extended poses.
`inverse`	Return the inverse.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_poses`	`int`	The number of extended poses stored in the instance.
`attitude`	`Rotation`	The attitude component of the pose.
`position`	`Translation`	The position component of the pose.
`velocity`	`Vector`	The velocity component of the pose.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_poses `property` ¶

num_poses: int

The number of extended poses stored in the instance.

attitude `property` ¶

attitude: Rotation

The attitude component of the pose.

position `property` ¶

position: Translation

The position component of the pose.

velocity `property` ¶

velocity: Vector

The velocity component of the pose.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Compose multiple instances of the group.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of instances of the derived class to be composed from first to last. Instances must have compatible dimensions and types.	required

Returns:

Name	Type	Description
`composed`	`Self`	Instance of the class composed from the inputs.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity ExtendedPose.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity poses to store.	`1`

Returns:

Name	Type	Description
`pose`	`Self`	An ExtendedPose instance.

from_apv `classmethod` ¶

from_apv(
    attitude: Rotation | ArrayLike,
    position: Translation | ArrayLike,
    velocity: Vector | ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct an ExtendedPose from attitude, position, and velocity.

Attitude is also known as orientation. The inputs must be compatible (dimension, time, etc.) or a ValueError is raised.

Parameters:

Name	Type	Description	Default
`attitude`	`Rotation \| ArrayLike`	A Rotation instance or array of rotation matrices.	required
`position`	`Translation \| ArrayLike`	A Translation instance or array of position vectors.	required
`velocity`	`Vector \| ArrayLike`	A Vector instance or array of velocity vectors.	required
`time`	`ArrayLike \| None`	If attitude, position, or velocity inputs are arrays, an array of unique, strictly increasing times corresponding to each input. Ignored otherwise.	`None`
`orthonormalize`	`bool`	If the attitude input is an array, whether to enforce orthonormality. Ignored otherwise.	`False`

Returns:

Name	Type	Description
`pose`	`Self`	An ExtendedPose instance.

from_random `classmethod` ¶

from_random(
    num_poses: int = 1, rng: Generator | int | None = None
) -> Self

Construct an ExtendedPose from random data.

Rotation components are uniformly distributed on the unit sphere. Position and velocity components are uniformly distributed between 0 and 1.

Parameters:

Name	Type	Description	Default
`num_poses`	`int`	The number of random poses to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`pose`	`Self`	An ExtendedPose instance.

as_apv ¶

as_apv() -> tuple[Rotation, Translation, Vector]

Return the attitude, position, and velocity.

See additional documentation at: from_apv.

Returns:

Name	Type	Description
`attitude`	`Rotation`	A Rotation instance.
`position`	`Translation`	A Translation instance.
`velocity`	`Vector`	A Vector instance.

as_attitude ¶

as_attitude() -> Rotation

Return the attitude component of the ExtendedPose instance.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.

as_position ¶

as_position() -> Translation

Return the position component of the ExtendedPose instance.

Returns:

Name	Type	Description
`position`	`Translation`	A Translation instance.

as_velocity ¶

as_velocity() -> Vector

Return the velocity component of the ExtendedPose instance.

Returns:

Name	Type	Description
`velocity`	`Vector`	A Vector instance.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Compound two extended poses.

A TypeError will be raised if the input is not another ExtendedPose object.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	An ExtendedPose instance.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	A new ExtendedPose instance compounded from the inputs.

inverse ¶

inverse() -> Self

Return the inverse.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse of the current instance.

Pose ¶

Pose(
    rotation: Rotation,
    translation: Translation,
    time_: ArrayLike | None = None,
)

Bases: RigidTransform

Pose (position and orientation).

Pose is an alias for RigidTransform and inherits all its functionality. It adds additional convenience attributes and methods.

Poses can be constructed from a rotation and translation R, t or from a homogeneous transform matrix: [[R, t],[0, 1]] using the from methods. Do not initialize an instance directly.

Methods:

Name	Description
`from_identity`	Construct an identity RigidTransform.
`apply`	Apply rigid transform to a vector input.
`compose`	Compose multiple rigid transforms.
`inverse`	Return the inverse representation.
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_homogeneous_matrix`	Construct a RigidTransform from homogeneous transform matrices.
`from_rotation_translation`	Construct a RigidTransform from rotations and translations.
`from_random`	Construct a RigidTransform from random data.
`as_homogeneous_matrix`	Return the homogeneous transform matrix representation.
`as_rotation_translation`	Return the rotation and translation.
`as_rotation`	Return the rotation component of the RigidTransform instance.
`as_translation`	Return the translation component of the RigidTransform instance.
`from_attitude_position`	Construct a Pose from attitude and position.
`as_attitude`	Return the rotation component of the Pose instance.
`as_position`	Return the position component of the Pose instance.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_transforms`	`int`	The number of transforms stored in the instance.
`rotation`	`Rotation`	The rotation component of the transform.
`translation`	`Translation`	The translation component of the transform.
`num_poses`	`int`	The number of poses stored in the instance.
`attitude`	`Rotation`	The attitude component of the pose.
`position`	`Translation`	The position component of the pose.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_transforms `property` ¶

num_transforms: int

The number of transforms stored in the instance.

rotation `property` ¶

rotation: Rotation

The rotation component of the transform.

translation `property` ¶

translation: Translation

The translation component of the transform.

num_poses `property` ¶

num_poses: int

The number of poses stored in the instance.

attitude `property` ¶

attitude: Rotation

The attitude component of the pose.

position `property` ¶

position: Translation

The position component of the pose.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity RigidTransform.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity transforms to store.	`1`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Apply rigid transform to a vector input.

Vector instance inputs result in Vector instance outputs. Array inputs result in array outputs.

A TypeError will be raised if the input is derived from MatrixLieGroup but is not derived from Vector.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	A Vector instance or array of cartesian vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	A new Vector instance or array of vectors with transformed inputs.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Compose multiple rigid transforms.

Transforms must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of RigidTransform instances to be composed from first to last.	required

Returns:

Name	Type	Description
`composed`	`Self`	RigidTransform instance composed from the inputs.

inverse ¶

inverse() -> Self

Return the inverse representation.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse of the current instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_homogeneous_matrix `classmethod` ¶

from_homogeneous_matrix(
    matrix: ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a RigidTransform from homogeneous transform matrices.

The input matrices must have 4x4 block structure [[R, t],[0, 1]] where R is a valid rotation matrix and t is a translation vector.

See Rotation.from_matrix for additional details regarding the rotation matrix block.

Parameters:

Name	Type	Description	Default
`matrix`	`ArrayLike`	Array of homogeneous transform matrices.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each matrix input.	`None`
`orthonormalize`	`bool`	Enforce orthonormality of the rotation component of the input.	`False`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

from_rotation_translation `classmethod` ¶

from_rotation_translation(
    rotation: Rotation | ArrayLike,
    translation: Translation | ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a RigidTransform from rotations and translations.

The inputs must be compatible (dimension, time, etc.) or a ValueError is raised.

Parameters:

Name	Type	Description	Default
`rotation`	`Rotation \| ArrayLike`	A Rotation instance or array of rotation matrices.	required
`translation`	`Translation \| ArrayLike`	A Translation instance or array of translation vectors.	required
`time`	`ArrayLike \| None`	If rotation or translation inputs are arrays, an array of unique, strictly increasing times corresponding to each input. Ignored otherwise.	`None`
`orthonormalize`	`bool`	If the rotation input is an array, whether to enforce orthonormality. Ignored otherwise.	`False`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

from_random `classmethod` ¶

from_random(
    num_transforms: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a RigidTransform from random data.

Rotation components are uniformly distributed on the unit sphere. Translation components are uniformly distributed between 0 and 1.

Parameters:

Name	Type	Description	Default
`num_transforms`	`int`	The number of random transforms to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

as_homogeneous_matrix ¶

as_homogeneous_matrix() -> NDArray

Return the homogeneous transform matrix representation.

See additional documentation regarding matrix conventions at: from_homogeneous_matrix.

Returns:

Name	Type	Description
`matrix`	`NDArray`	Array of homogeneous transform matrices.

as_rotation_translation ¶

as_rotation_translation() -> tuple[Rotation, Translation]

Return the rotation and translation.

See additional documentation at: from_rotation_translation.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.
`translation`	`Translation`	A Translation instance.

as_rotation ¶

as_rotation() -> Rotation

Return the rotation component of the RigidTransform instance.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.

as_translation ¶

as_translation() -> Translation

Return the translation component of the RigidTransform instance.

Returns:

Name	Type	Description
`translation`	`Translation`	A Translation instance.

from_attitude_position `classmethod` ¶

from_attitude_position(
    attitude: Rotation | ArrayLike,
    position: Translation | ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a Pose from attitude and position.

Attitude is also known as orientation. The inputs must be compatible (dimension, time, etc.) or a ValueError is raised.

Parameters:

Name	Type	Description	Default
`attitude`	`Rotation \| ArrayLike`	A Rotation instance or array of rotation matrices.	required
`position`	`Translation \| ArrayLike`	A Translation instance or array of position vectors.	required
`time`	`ArrayLike \| None`	If attitude or position inputs are arrays, an array of unique, strictly increasing times corresponding to each input. Ignored otherwise.	`None`
`orthonormalize`	`bool`	If the attitude input is an array, whether to enforce orthonormality. Ignored otherwise.	`False`

Returns:

Name	Type	Description
`pose`	`Self`	A Pose instance.

as_attitude ¶

as_attitude() -> Rotation

Return the rotation component of the Pose instance.

See additional documentation regarding matrix conventions at: from_matrix.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.

as_position ¶

as_position() -> Translation

Return the position component of the Pose instance.

Returns:

Name	Type	Description
`position`	`Translation`	A Translation instance.

CoordinateTransform ¶

CoordinateTransform(
    rotation: CoordinateRotation,
    translation: CoordinateTranslation,
    time: ArrayLike | None = None,
)

Bases: RigidTransform

3-dimensional coordinate frame transforms.

CoordinateTransform is a subclass of RigidTransform and supports the same methods and attributes.

Coordinate transforms can be constructed from a rotation and translation R, t or from a homogeneous transform matrix: [[R, t],[0, 1]] using the from methods. Do not initialize an instance directly.

Transform conventions

There are a large variety of rotation and transform conventions and they are a common source of errors. Because many of these conventions cannot be automatically validated, users must be aware of them and manage interfaces with other software accordingly. InertialSim conventions are documented in info boxes in class and method documentation.

Active vs passive transform convention

Transforms stored in this class represent a passive transformation. In the passive convention, transforms act to convert the description of physical vectors between different coordinate systems.

The alternative active convention is supported in the RigidTransform class. In the active convention, transforms act to rotate and translate an object relative to a fixed coordinate system. The active convention is the standard mathematical description of a rigid body transform. In general, the two should not be mixed.

Some references use the terminology alibi (active) and alias (passive). Reference [02], Reference [05], and Reference [11] discuss active vs. passive transforms in greater detail.

Methods:

Name	Description
`from_identity`	Construct an identity RigidTransform.
`compose`	Compose multiple rigid transforms.
`inverse`	Return the inverse representation.
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_rotation_translation`	Construct a RigidTransform from rotations and translations.
`from_random`	Construct a RigidTransform from random data.
`as_rotation_translation`	Return the rotation and translation.
`as_rotation`	Return the rotation component of the RigidTransform instance.
`as_translation`	Return the translation component of the RigidTransform instance.
`from_homogeneous_matrix`	Construct a CoordinateTransform from homogeneous transform matrices.
`as_homogeneous_matrix`	Return the homogeneous transform matrix representation.
`apply`	Apply a coordinate transform to a vector input.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_transforms`	`int`	The number of transforms stored in the instance.
`rotation`	`Rotation`	The rotation component of the transform.
`translation`	`Translation`	The translation component of the transform.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_transforms `property` ¶

num_transforms: int

The number of transforms stored in the instance.

rotation `property` ¶

rotation: Rotation

The rotation component of the transform.

translation `property` ¶

translation: Translation

The translation component of the transform.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity RigidTransform.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity transforms to store.	`1`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Compose multiple rigid transforms.

Transforms must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of RigidTransform instances to be composed from first to last.	required

Returns:

Name	Type	Description
`composed`	`Self`	RigidTransform instance composed from the inputs.

inverse ¶

inverse() -> Self

Return the inverse representation.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse of the current instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_rotation_translation `classmethod` ¶

from_rotation_translation(
    rotation: Rotation | ArrayLike,
    translation: Translation | ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a RigidTransform from rotations and translations.

The inputs must be compatible (dimension, time, etc.) or a ValueError is raised.

Parameters:

Name	Type	Description	Default
`rotation`	`Rotation \| ArrayLike`	A Rotation instance or array of rotation matrices.	required
`translation`	`Translation \| ArrayLike`	A Translation instance or array of translation vectors.	required
`time`	`ArrayLike \| None`	If rotation or translation inputs are arrays, an array of unique, strictly increasing times corresponding to each input. Ignored otherwise.	`None`
`orthonormalize`	`bool`	If the rotation input is an array, whether to enforce orthonormality. Ignored otherwise.	`False`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

from_random `classmethod` ¶

from_random(
    num_transforms: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a RigidTransform from random data.

Rotation components are uniformly distributed on the unit sphere. Translation components are uniformly distributed between 0 and 1.

Parameters:

Name	Type	Description	Default
`num_transforms`	`int`	The number of random transforms to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

as_rotation_translation ¶

as_rotation_translation() -> tuple[Rotation, Translation]

Return the rotation and translation.

See additional documentation at: from_rotation_translation.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.
`translation`	`Translation`	A Translation instance.

as_rotation ¶

as_rotation() -> Rotation

Return the rotation component of the RigidTransform instance.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.

as_translation ¶

as_translation() -> Translation

Return the translation component of the RigidTransform instance.

Returns:

Name	Type	Description
`translation`	`Translation`	A Translation instance.

from_homogeneous_matrix `classmethod` ¶

from_homogeneous_matrix(
    matrix: ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a CoordinateTransform from homogeneous transform matrices.

The input matrices must have 4x4 block structure [[C, t],[0, 1]] where C is a valid coordinate rotation matrix and t is a coordinate translation vector.

See CoordinateRotation.from_matrix for additional details regarding the coordinate rotation matrix block.

Parameters:

Name	Type	Description	Default
`matrix`	`ArrayLike`	Array of homogeneous transform matrices.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each matrix input.	`None`
`orthonormalize`	`bool`	Enforce orthonormality of the rotation component of the input.	`False`

Returns:

Name	Type	Description
`transform`	`Self`	A CoordinateTransform instance.

as_homogeneous_matrix ¶

as_homogeneous_matrix() -> NDArray

Return the homogeneous transform matrix representation.

See additional documentation regarding matrix conventions at: from_homogeneous_matrix.

Returns:

Name	Type	Description
`matrix`	`NDArray`	Array of homogeneous transform matrices.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Apply a coordinate transform to a vector input.

Vector object inputs result in Vector instance outputs. Array inputs result in array outputs.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	A Vector instance or array of cartesian vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	A new Vector instance or array of transformed inputs.

RigidTransform ¶

RigidTransform(
    rotation: Rotation,
    translation: Translation,
    time_: ArrayLike | None = None,
)

Bases: MatrixLieGroup

3-dimensional rigid body transforms.

Rigid transforms can be constructed from a rotation and translation R, t or from a homogeneous transform matrix: [[R, t],[0, 1]] using the from methods. Do not initialize an instance directly.

Transform conventions

There are a large variety of rotation and transform conventions and they are a common source of errors. Because many of these conventions cannot be automatically validated, users must be aware of them and manage interfaces with other software accordingly. InertialSim conventions are documented in info boxes in class and method documentation.

Active vs passive transform convention

Transforms stored in this class represent an active transformation. In the active convention, transforms act to rotate and translate an object relative to a fixed coordinate system. The active convention is the standard mathematical description of a rigid body transform.

The alternative passive convention is supported in the CoordinateTransform class. In the passive convention, transforms act to convert the description of physical vectors between different coordinate systems. In general, the two should not be mixed.

Some references use the terminology alibi (active) and alias (passive). [Reference [02], Reference [05], and Reference [11] discuss active vs. passive transforms in greater detail.

Methods:

Name	Description
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_identity`	Construct an identity RigidTransform.
`from_homogeneous_matrix`	Construct a RigidTransform from homogeneous transform matrices.
`from_rotation_translation`	Construct a RigidTransform from rotations and translations.
`from_random`	Construct a RigidTransform from random data.
`as_homogeneous_matrix`	Return the homogeneous transform matrix representation.
`as_rotation_translation`	Return the rotation and translation.
`as_rotation`	Return the rotation component of the RigidTransform instance.
`as_translation`	Return the translation component of the RigidTransform instance.
`inverse`	Return the inverse representation.
`apply`	Apply rigid transform to a vector input.
`compose`	Compose multiple rigid transforms.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_transforms`	`int`	The number of transforms stored in the instance.
`rotation`	`Rotation`	The rotation component of the transform.
`translation`	`Translation`	The translation component of the transform.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_transforms `property` ¶

num_transforms: int

The number of transforms stored in the instance.

rotation `property` ¶

rotation: Rotation

The rotation component of the transform.

translation `property` ¶

translation: Translation

The translation component of the transform.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity RigidTransform.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity transforms to store.	`1`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

from_homogeneous_matrix `classmethod` ¶

from_homogeneous_matrix(
    matrix: ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a RigidTransform from homogeneous transform matrices.

The input matrices must have 4x4 block structure [[R, t],[0, 1]] where R is a valid rotation matrix and t is a translation vector.

See Rotation.from_matrix for additional details regarding the rotation matrix block.

Parameters:

Name	Type	Description	Default
`matrix`	`ArrayLike`	Array of homogeneous transform matrices.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each matrix input.	`None`
`orthonormalize`	`bool`	Enforce orthonormality of the rotation component of the input.	`False`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

from_rotation_translation `classmethod` ¶

from_rotation_translation(
    rotation: Rotation | ArrayLike,
    translation: Translation | ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a RigidTransform from rotations and translations.

The inputs must be compatible (dimension, time, etc.) or a ValueError is raised.

Parameters:

Name	Type	Description	Default
`rotation`	`Rotation \| ArrayLike`	A Rotation instance or array of rotation matrices.	required
`translation`	`Translation \| ArrayLike`	A Translation instance or array of translation vectors.	required
`time`	`ArrayLike \| None`	If rotation or translation inputs are arrays, an array of unique, strictly increasing times corresponding to each input. Ignored otherwise.	`None`
`orthonormalize`	`bool`	If the rotation input is an array, whether to enforce orthonormality. Ignored otherwise.	`False`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

from_random `classmethod` ¶

from_random(
    num_transforms: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a RigidTransform from random data.

Rotation components are uniformly distributed on the unit sphere. Translation components are uniformly distributed between 0 and 1.

Parameters:

Name	Type	Description	Default
`num_transforms`	`int`	The number of random transforms to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`transform`	`Self`	A RigidTransform instance.

as_homogeneous_matrix ¶

as_homogeneous_matrix() -> NDArray

Return the homogeneous transform matrix representation.

See additional documentation regarding matrix conventions at: from_homogeneous_matrix.

Returns:

Name	Type	Description
`matrix`	`NDArray`	Array of homogeneous transform matrices.

as_rotation_translation ¶

as_rotation_translation() -> tuple[Rotation, Translation]

Return the rotation and translation.

See additional documentation at: from_rotation_translation.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.
`translation`	`Translation`	A Translation instance.

as_rotation ¶

as_rotation() -> Rotation

Return the rotation component of the RigidTransform instance.

Returns:

Name	Type	Description
`rotation`	`Rotation`	A Rotation instance.

as_translation ¶

as_translation() -> Translation

Return the translation component of the RigidTransform instance.

Returns:

Name	Type	Description
`translation`	`Translation`	A Translation instance.

inverse ¶

inverse() -> Self

Return the inverse representation.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse of the current instance.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Apply rigid transform to a vector input.

Vector instance inputs result in Vector instance outputs. Array inputs result in array outputs.

A TypeError will be raised if the input is derived from MatrixLieGroup but is not derived from Vector.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	A Vector instance or array of cartesian vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	A new Vector instance or array of vectors with transformed inputs.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Compose multiple rigid transforms.

Transforms must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of RigidTransform instances to be composed from first to last.	required

Returns:

Name	Type	Description
`composed`	`Self`	RigidTransform instance composed from the inputs.

CoordinateRotation ¶

CoordinateRotation(
    matrix: ArrayLike, time: ArrayLike | None = None
)

Bases: Rotation

3-dimensional coordinate frame rotations.

CoordinateRotation is a subclass of Rotation and supports the same methods and attributes.

CoordinateRotations can be constructed from any of the following representations: rotation matrix, Euler angles, quaternion, rotation vector, and axis angle. Use the from methods to construct an instance. Do not initialize an instance directly.

Current state can be returned in any of the representations listed above using the as methods.

Internally coordinate transforms are stored in matrix format.

Rotation conventions

There are a large variety of rotation conventions and they are a common source of errors. Because many of these conventions cannot be automatically validated, users must be aware of them and manage interfaces with other software accordingly. InertialSim conventions are documented in info boxes in class and method documentation.

Active vs passive rotation convention

Rotations stored in this class act to convert the description of physical vectors to different coordinate systems. They are also known as passive rotations or direction cosine matrices.

The alternative active convention is supported in the Rotation class. Active rotations rotate an object relative to a fixed coordinate system. The active convention is the standard mathematical description of rotations.

Some references use the terminology alibi (active) and alias (passive). [Reference [02], Reference [05], and Reference [11] discuss active vs. passive transforms in greater detail.

Methods:

Name	Description
`from_identity`	Construct an identity Rotation.
`apply`	Apply rotation to a vector input.
`compose`	Compose multiple rotations.
`inverse`	Return the inverse of the current instance.
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_matrix`	Construct a Rotation from rotation matrices.
`from_quaternion`	Construct a Rotation from quaternions.
`from_random`	Construct a Rotation from random data.
`as_matrix`	Return the rotation matrix representation.
`as_quaternion`	Return the quaternion representation.
`integral_factor`	Returns the first integral matrix factor.
`double_integral_factor`	Returns the double integral matrix factor.
`from_euler`	Construct a CoordinateRotation from a sequence of Euler angles.
`from_rotation_vector`	Construct a CoordinateRotation from rotation vectors.
`from_axis_angle`	Construct a CoordinateRotation from an axis and angle.
`as_euler`	Return the Euler angle representation.
`as_rotation_vector`	Return the rotation vector representation.
`as_axis_angle`	Return the axis, angle representation.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_rotations`	`int`	The number of rotations stored in the instance.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_rotations `property` ¶

num_rotations: int

The number of rotations stored in the instance.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity Rotation.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity rotations to store.	`1`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Apply rotation to a vector input.

Vector instance inputs result in Vector instance outputs. Array inputs result in array outputs.

A TypeError will be raised if the input is derived from MatrixLieGroup but is not derived from Vector.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	A Vector instance or array of cartesian vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	A new Vector instance or array of vectors with rotated inputs.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Compose multiple rotations.

Inputs must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of Rotation instances to be composed from first to last.	required

Returns:

Name	Type	Description
`composed`	`Self`	Rotation instance composed from the inputs.

inverse ¶

inverse() -> Self

Return the inverse of the current instance.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse of the current instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_matrix `classmethod` ¶

from_matrix(
    matrix: ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a Rotation from rotation matrices.

A rotation matrix is an orthonormal 3x3 matrix that represents a rigid body rotation.

Active vs passive rotation matrices

See the class documentation regarding passive and active conventions. Passive rotation matrices are also commonly known as a coordinate transform matrices, or direction cosine matrices. An active rotation matrix is the transpose of the equivalent passive coordinate transform matrix \(R_{i \rightarrow b} = C_{i}^{bT} = C_{b}^{i}\).

SciPy equivalent:

scipy.spatial.transform.Rotation.from_matrix(matrix)

Parameters:

Name	Type	Description	Default
`matrix`	`ArrayLike`	Array of rotation matrices.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each matrix input.	`None`
`orthonormalize`	`bool`	Enforce orthonormality of the matrix input.	`False`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_quaternion `classmethod` ¶

from_quaternion(
    quaternion: ArrayLike,
    time: ArrayLike | None = None,
    *,
    scalar_last: bool = False,
) -> Self

Construct a Rotation from quaternions.

Quaternions are 4-parameter arrays, a subset of which can be used to represent rotation. They are the minimum dimension representation that is free from singularities. Quaternions of rotation are also known as Euler-Rodrigues symmetric parameters.

The input quaternions must be normalized.

Ordering conventions

There are two conventions for ordering the elements of a quaternion. Scalar element first or scalar element last (fourth). InertialSim uses the scalar first convention. The alternative is supported by setting scalar_last = True.

Sign conventions

The physical rotation represented by a quaternion and its negative are the same, q == -q. To standardize, the input quaternion will be adjusted such that the scalar element is always positive.

Composition conventions

There are multiple conventions for composing quaternions (including some which redefine the quaternion elements). InertialSim uses the traditional Hamilton convention. See Reference [02] and Reference [05] for further details.

Naming conventions

There are three dominant conventions for naming the four quaternion elements. Equivalent terms for scalar first ordering are:

q[0] = a = w
q[1] = b = x
q[2] = c = y
q[3] = d = z

SciPy equivalent (scalar element last):

quaternion = quaternion[:,[1,2,3,0]]
scipy.spatial.transform.Rotation.from_quat(quaternion)

Parameters:

Name	Type	Description	Default
`quaternion`	`ArrayLike`	Array of quaternions.	required
`scalar_last`	`bool`	Indicates whether the scalar element of the input quaternion is in the last element of the array instead of the first.	`False`
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each quaternion input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_random `classmethod` ¶

from_random(
    num_rotations: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a Rotation from random data.

Rotations are uniformly distributed on the unit sphere.

Parameters:

Name	Type	Description	Default
`num_rotations`	`int`	The number of random rotations to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

as_matrix ¶

as_matrix() -> NDArray

Return the rotation matrix representation.

See additional documentation regarding rotation matrix conventions at: from_matrix.

SciPy equivalent:

scipy.spatial.transform.Rotation.as_matrix()

Returns:

Name	Type	Description
`matrix`	`NDArray`	Array of rotation matrices.

as_quaternion ¶

as_quaternion() -> NDArray

Return the quaternion representation.

See additional documentation regarding quaternion conventions at: from_quaternion.

SciPy equivalent:

scipy.spatial.transform.Rotation.as_quat()

Returns:

Name	Type	Description
`quaternion`	`NDArray`	Array of quaternions.

integral_factor `classmethod` ¶

integral_factor(rotation_vector: NDArray) -> NDArray

Returns the first integral matrix factor.

Return the matrix factor, \(\mathbf{F}_{1}(\mathbf{\theta})\), that converts the integral of a vector, \(\mathbf{v}\), that is constant in a rotating (body/sensor) frame to the integral of \(\mathbf{v}\) in a fixed (world) frame. The moving frame rotates through rotation vector, \(\mathbf{\theta}\), relative to the fixed frame.

\[ \int_{t}^{t+\Delta t} \mathbf{v}^{w} dt = \mathbf{F}_{1}(\mathbf{\theta}) \mathbf{v}^{b} \Delta t \]

See Reference [01], Equation 19.1.3.4 and Reference [18], Equation 8.40.

Parameters:

Name	Type	Description	Default
`rotation_vector`	`NDArray`	Array of rotation vectors.	required

Returns:

Name	Type	Description
`integral_factor`	`NDArray`	Integral matrix factor.

double_integral_factor `classmethod` ¶

double_integral_factor(rotation_vector: NDArray) -> NDArray

Returns the double integral matrix factor.

Return the matrix factor, \(\mathbf{F}_{2}(\mathbf{\theta})\), that converts the double integral of a vector, \(\mathbf{v}\), that is constant in a rotating (body/sensor) frame to the double integral of \(\mathbf{v}\) in a fixed (world) frame. The moving frame rotates through rotation vector, \(\mathbf{\theta}\), relative to the fixed frame.

\[ \int_{t}^{t+\Delta t}\int_{t}^{t+\Delta t} \mathbf{v}^{w} dt = \frac{1}{2}\mathbf{F}_{2}(\mathbf{\theta}) \mathbf{v}^{b} \Delta t^{2} \]

See Reference [01], Equation 19.1.3.5 and Reference [18], Equation 9.2.1.1.

Parameters:

Name	Type	Description	Default
`rotation_vector`	`NDArray`	Array of rotation vectors.	required

Returns:

Name	Type	Description
`integral_factor`	`NDArray`	Integral matrix factor.

from_euler `classmethod` ¶

from_euler(
    euler: ArrayLike,
    sequence: str,
    time: ArrayLike | None = None,
) -> Self

Construct a CoordinateRotation from a sequence of Euler angles.

Euler angles are a sequence of three rotations applied around the axes of a coordinate system.

The input Euler angles must represent a valid sequence of Euler angles.

Sequence conventions

Euler angles act as a sequence of three independent rotations. The order of these rotations matter. Sequences are specified with a string, e.g. "XYZ" or "YZY". The first letter is the first rotation applied (rightmost position in the equivalent matrix multiplication). Two consecutive letters cannot be the same. When the first and third rotations are around the same axis (e.g. "ZYZ") the sequence is referred to as symmetric. When the first and third rotations are around different axes (e.g. "YZX") the sequence is referred to as asymmetric. InertialSim supports all valid sequences. See Reference [02] for further details.

Rotation axis conventions

Because Euler angle rotations are applied consecutively, the second and third rotations can be conceived as rotating around the set of original (or fixed) coordinate axes; or of rotating around a moving set of coordinate axes (where the second rotation is around an axis shifted by the first rotation and the third rotation is around an axis shifted by both first and second rotations respectively). The first of these conventions is known as the extrinsic (or space fixed) convention. The alternative is known as the intrinsic (or body fixed) convention. The intrinsic convention is used in this class whereas the extrinsic convention is used in the Rotation class. See Reference [02] for further details.

Angle range conventions

Euler angle values are not unique. In addition to a modulo \(2\pi\) ambiguity, there are more subtle ways that the same physical rotation can arise from different numerical values. To standardize this, the first and third angles will be adjusted such that:

-pi < euler[0] <= pi
-pi < euler[2] <= pi

The second angle will be adjusted depending on whether the sequence is symmetric or asymmetric such that:

0 <= euler[1] <= pi        # For symmetric sequences.
-pi/2 <= euler[1] <= pi/2  # For asymmetric sequences.

See Reference [02] and Reference [04] for further details.

Parameters:

Name	Type	Description	Default
`euler`	`ArrayLike`	Array of Euler angles. The first element in the array represents the angle around the first axis in the sequence.	required
`sequence`	`str`	Euler angle rotation sequence. 3 letters representing the axes of rotation "X", "Y", and "Z". The first letter is the first rotation applied (rightmost position in matrix multiplication). Two consecutive letters cannot be the same.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each Euler angle input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A CoordinateRotation instance.

from_rotation_vector `classmethod` ¶

from_rotation_vector(
    rotation_vector: ArrayLike,
    time: ArrayLike | None = None,
) -> Self

Construct a CoordinateRotation from rotation vectors.

The rotation vector is a vector whose magnitude is the angle of rotation and whose direction is the axis of rotation (in the right handed sense). It is closely related to the axis-angle representation.

The input rotation vectors must be non-zero.

Angle range conventions

To avoid modulo \(2\pi\) ambiguities, the magnitude of the rotation vectors will be adjusted such that:

0 < norm(rotation_vector) <= 2*pi

Parameters:

Name	Type	Description	Default
`rotation_vector`	`ArrayLike`	Array of rotation vectors.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each rotation vector input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A CoordinateRotation instance.

from_axis_angle `classmethod` ¶

from_axis_angle(
    axis: ArrayLike,
    angle: ArrayLike,
    time: ArrayLike | None = None,
) -> Self

Construct a CoordinateRotation from an axis and angle.

Euler's rotation theorem states that any rotation of a rigid body can be represented by an axis of rotation and an angle of rotation about that axis.

The input axes and angles must be consistent in dimension. The input axes must be unit norm.

Range and sign conventions

A rotation of \(\theta\) degrees around a given axis is equivalent to a rotation of \(2\pi - \theta\) about the opposite (negative) axis. To standardize, input angles and axes will be adjusted such that:

0 <= angle <= pi

Parameters:

Name	Type	Description	Default
`axis`	`ArrayLike`	Array of axes of rotation.	required
`angle`	`ArrayLike`	Array of angles. Each angle corresponds to each axis input.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each axis and angle input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A CoordinateRotation instance.

as_euler ¶

as_euler(
    sequence: str, *, output_gimbal_lock: bool = False
) -> NDArray | tuple[NDArray, NDArray[bool_]]

Return the Euler angle representation.

Singularities

The first and third Euler angles cannot be uniquely determined in the following scenarios:

euler[1] == 0 or pi        # For symmetric sequences.
euler[1] == -pi/2 or pi/2  # For asymmetric sequences.

This is sometimes referred to as "gimbal lock". The third angle is arbitrarily set to zero in this case, as per the convention in Reference [02] and Reference [04]. Note that the output still represents a correct, valid rotation but independent tracking of the first and third angles is lost.

See additional documentation regarding Euler angle conventions at: from_euler.

Parameters:

Name	Type	Description	Default
`sequence`	`str`	Euler angle rotation sequence. 3 letters representing the axes of rotation "X", "Y", and "Z". The first letter is the first rotation applied (rightmost position in matrix multiplication). Two consecutive letters cannot be the same.	required
`output_gimbal_lock`	`bool`	Output an array of booleans indicating whether each sequence of Euler angles output was calculated from a gimbal lock condition.	`False`

Returns:

Name	Type	Description
`euler`	`NDArray \| tuple[NDArray, NDArray[bool_]]`	Array of Euler angles. The first element in the array represents the angle around the first axis in the sequence.
`gimbal_lock`	`NDArray \| tuple[NDArray, NDArray[bool_]]`	Array of booleans indicating whether each Euler angle output was calculated from a gimbal lock condition.

as_rotation_vector ¶

as_rotation_vector() -> NDArray

Return the rotation vector representation.

See additional documentation regarding rotation vector conventions at: from_rotation_vector.

Returns:

Name	Type	Description
`rotation_vector`	`NDArray`	Array of rotation vectors.

as_axis_angle ¶

as_axis_angle() -> tuple[NDArray, NDArray]

Return the axis, angle representation.

See additional documentation regarding axis angle conventions at: from_axis_angle.

Returns:

Name	Type	Description
`axis`	`NDArray`	Array of axes of rotation.
`angle`	`NDArray`	Array of angles. Each angle corresponds to each axis.

Rotation ¶

Rotation(matrix: ArrayLike, time: ArrayLike | None = None)

Bases: MatrixLieGroup

3-dimensional rotations of rigid bodies.

Rotations can be constructed from any of the following representations: rotation matrix, Euler angles, quaternion, rotation vector, and axis angle. Use the from methods to construct an instance. Do not initialize an instance directly.

Current state can be returned in any of the representations listed above using the as methods.

Internally rotations are stored in rotation matrix format.

Rotation conventions

There are a large variety of rotation conventions and they are a common source of errors. Because many of these conventions cannot be automatically validated, users must be aware of them and manage interfaces with other software accordingly. InertialSim conventions are documented in info boxes in class and method documentation.

Active vs passive rotation convention

Rotations stored in this class represent an active transformation. In the active convention, rotations act to rotate an object relative to a fixed coordinate system. The active convention is the standard mathematical description of rotations.

The alternative passive convention is supported in the CoordinateRotation subclass. In the passive convention, rotations act to transform the components of physical vectors to different coordinate systems. The passive convention is the standard for describing orientation in inertial navigation and aerospace applications.

Some references use the terminology alibi (active) and alias (passive). [Reference [02], Reference [05], and Reference [11] discuss active vs. passive transforms in greater detail.

Methods:

Name	Description
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_identity`	Construct an identity Rotation.
`from_matrix`	Construct a Rotation from rotation matrices.
`from_euler`	Construct a Rotation from a sequence of Euler angles.
`from_quaternion`	Construct a Rotation from quaternions.
`from_rotation_vector`	Construct a Rotation from rotation vectors.
`from_axis_angle`	Construct a Rotation from an axis and angle.
`from_random`	Construct a Rotation from random data.
`apply`	Apply rotation to a vector input.
`as_matrix`	Return the rotation matrix representation.
`as_euler`	Return the Euler angle representation.
`as_quaternion`	Return the quaternion representation.
`as_rotation_vector`	Return the rotation vector representation.
`as_axis_angle`	Return the axis, angle representation.
`inverse`	Return the inverse of the current instance.
`compose`	Compose multiple rotations.
`integral_factor`	Returns the first integral matrix factor.
`double_integral_factor`	Returns the double integral matrix factor.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_rotations`	`int`	The number of rotations stored in the instance.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_rotations `property` ¶

num_rotations: int

The number of rotations stored in the instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity Rotation.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity rotations to store.	`1`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_matrix `classmethod` ¶

from_matrix(
    matrix: ArrayLike,
    time: ArrayLike | None = None,
    *,
    orthonormalize: bool = False,
) -> Self

Construct a Rotation from rotation matrices.

A rotation matrix is an orthonormal 3x3 matrix that represents a rigid body rotation.

Active vs passive rotation matrices

See the class documentation regarding passive and active conventions. Passive rotation matrices are also commonly known as a coordinate transform matrices, or direction cosine matrices. An active rotation matrix is the transpose of the equivalent passive coordinate transform matrix \(R_{i \rightarrow b} = C_{i}^{bT} = C_{b}^{i}\).

SciPy equivalent:

scipy.spatial.transform.Rotation.from_matrix(matrix)

Parameters:

Name	Type	Description	Default
`matrix`	`ArrayLike`	Array of rotation matrices.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each matrix input.	`None`
`orthonormalize`	`bool`	Enforce orthonormality of the matrix input.	`False`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_euler `classmethod` ¶

from_euler(
    euler: ArrayLike,
    sequence: str,
    time: ArrayLike | None = None,
) -> Self

Construct a Rotation from a sequence of Euler angles.

Euler angles are a sequence of three rotations applied around the axes of a coordinate system.

The input Euler angles must represent a valid sequence of Euler angles.

Sequence conventions

Euler angles act as a sequence of three independent rotations. The order of these rotations matter. Sequences are specified with a string, e.g. "XYZ" or "YZY". The first letter is the first rotation applied (rightmost position in the equivalent matrix multiplication). Two consecutive letters cannot be the same. When the first and third rotations are around the same axis (e.g. "ZYZ") the sequence is referred to as symmetric. When the first and third rotations are around different axes (e.g. "YZX") the sequence is referred to as asymmetric. InertialSim supports all valid sequences. See Reference [02] for further details.

Rotation axis conventions

Because Euler angle rotations are applied consecutively, the second and third rotations can be conceived as rotating around the set of original (or fixed) coordinate axes; or of rotating around a moving set of coordinate axes (where the second rotation is around an axis shifted by the first rotation and the third rotation is around an axis shifted by both first and second rotations respectively). The first of these conventions is known as the extrinsic (or space fixed) convention. The alternative is known as the intrinsic (or body fixed) convention. InertialSim uses the extrinsic conventions in this class. See Reference [02] for further details.

Angle range conventions

Euler angle values are not unique. In addition to a modulo \(2\pi\) ambiguity, there are more subtle ways that the same physical rotation can arise from different numerical values. To standardize this, the first and third angles will be adjusted such that:

-pi < euler[0] <= pi
-pi < euler[2] <= pi

The second angle will be adjusted depending on whether the sequence is symmetric or asymmetric such that:

0 <= euler[1] <= pi        # For symmetric sequences.
-pi/2 <= euler[1] <= pi/2  # For asymmetric sequences.

See Reference [02] and Reference [04]for further details.

SciPy equivalent:

sequence = sequence.lower()
scipy.spatial.transform.Rotation.from_euler(sequence, euler)

Parameters:

Name	Type	Description	Default
`euler`	`ArrayLike`	Array of Euler angles. The first element in the array represents the angle around the first axis in the sequence.	required
`sequence`	`str`	Euler angle rotation sequence. 3 letters representing the axes of rotation "X", "Y", and "Z". The first letter is the first rotation applied (rightmost position in matrix multiplication). Two consecutive letters cannot be the same.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each Euler angle input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_quaternion `classmethod` ¶

from_quaternion(
    quaternion: ArrayLike,
    time: ArrayLike | None = None,
    *,
    scalar_last: bool = False,
) -> Self

Construct a Rotation from quaternions.

Quaternions are 4-parameter arrays, a subset of which can be used to represent rotation. They are the minimum dimension representation that is free from singularities. Quaternions of rotation are also known as Euler-Rodrigues symmetric parameters.

The input quaternions must be normalized.

Ordering conventions

There are two conventions for ordering the elements of a quaternion. Scalar element first or scalar element last (fourth). InertialSim uses the scalar first convention. The alternative is supported by setting scalar_last = True.

Sign conventions

The physical rotation represented by a quaternion and its negative are the same, q == -q. To standardize, the input quaternion will be adjusted such that the scalar element is always positive.

Composition conventions

There are multiple conventions for composing quaternions (including some which redefine the quaternion elements). InertialSim uses the traditional Hamilton convention. See Reference [02] and Reference [05] for further details.

Naming conventions

There are three dominant conventions for naming the four quaternion elements. Equivalent terms for scalar first ordering are:

q[0] = a = w
q[1] = b = x
q[2] = c = y
q[3] = d = z

SciPy equivalent (scalar element last):

quaternion = quaternion[:,[1,2,3,0]]
scipy.spatial.transform.Rotation.from_quat(quaternion)

Parameters:

Name	Type	Description	Default
`quaternion`	`ArrayLike`	Array of quaternions.	required
`scalar_last`	`bool`	Indicates whether the scalar element of the input quaternion is in the last element of the array instead of the first.	`False`
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each quaternion input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_rotation_vector `classmethod` ¶

from_rotation_vector(
    rotation_vector: ArrayLike,
    time: ArrayLike | None = None,
) -> Self

Construct a Rotation from rotation vectors.

The rotation vector is a vector whose magnitude is the angle of rotation and whose direction is the axis of rotation (in the right handed sense). It is closely related to the axis-angle representation.

The input rotation vectors must be non-zero.

Angle range conventions

To avoid modulo \(2\pi\) ambiguities, the magnitude of the rotation vectors will be adjusted such that:

0 < norm(rotation_vector) <= 2*pi

SciPy equivalent:

scipy.spatial.transform.Rotation.from_rotvec(rv).as_rotvec()

Parameters:

Name	Type	Description	Default
`rotation_vector`	`ArrayLike`	Array of rotation vectors.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each rotation vector input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_axis_angle `classmethod` ¶

from_axis_angle(
    axis: ArrayLike,
    angle: ArrayLike,
    time: ArrayLike | None = None,
) -> Self

Construct a Rotation from an axis and angle.

Euler's rotation theorem states that any rotation of a rigid body can be represented by an axis of rotation and an angle of rotation about that axis.

The input axes and angles must be consistent in dimension. The input axes must be unit norm.

Range and sign conventions

A rotation of \(\theta\) degrees around a given axis is equivalent to a rotation of \(2\pi - \theta\) about the opposite (negative) axis. To standardize, input angles and axes will be adjusted such that:

0 <= angle <= pi

Parameters:

Name	Type	Description	Default
`axis`	`ArrayLike`	Array of axes of rotation.	required
`angle`	`ArrayLike`	Array of angles. Each angle corresponds to each axis input.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each axis and angle input.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

from_random `classmethod` ¶

from_random(
    num_rotations: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a Rotation from random data.

Rotations are uniformly distributed on the unit sphere.

Parameters:

Name	Type	Description	Default
`num_rotations`	`int`	The number of random rotations to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`rotation`	`Self`	A Rotation instance.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Apply rotation to a vector input.

Vector instance inputs result in Vector instance outputs. Array inputs result in array outputs.

A TypeError will be raised if the input is derived from MatrixLieGroup but is not derived from Vector.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	A Vector instance or array of cartesian vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	A new Vector instance or array of vectors with rotated inputs.

as_matrix ¶

as_matrix() -> NDArray

Return the rotation matrix representation.

See additional documentation regarding rotation matrix conventions at: from_matrix.

SciPy equivalent:

scipy.spatial.transform.Rotation.as_matrix()

Returns:

Name	Type	Description
`matrix`	`NDArray`	Array of rotation matrices.

as_euler ¶

as_euler(
    sequence: str, *, output_gimbal_lock: bool = False
) -> NDArray | tuple[NDArray, NDArray[bool_]]

Return the Euler angle representation.

Singularities

The first and third Euler angles cannot be uniquely determined in the following scenarios:

euler[1] == 0 or pi        # For symmetric sequences.
euler[1] == -pi/2 or pi/2  # For asymmetric sequences.

This is sometimes referred to as "gimbal lock". The third angle is arbitrarily set to zero in this case, as per the convention in Reference [02] and Reference [04]. Note that the output still represents a correct, valid rotation but independent tracking of the first and third angles is lost.

See additional documentation regarding Euler angle conventions at: from_euler.

SciPy equivalent:

sequence = sequence.lower()
scipy.spatial.transform.Rotation.as_euler(sequence)

Parameters:

Name	Type	Description	Default
`sequence`	`str`	Euler angle rotation sequence. 3 letters representing the axes of rotation "X", "Y", and "Z". The first letter is the first rotation applied (rightmost position in matrix multiplication). Two consecutive letters cannot be the same.	required
`output_gimbal_lock`	`bool`	Output an array of booleans indicating whether each sequence of Euler angles output was calculated from a gimbal lock condition.	`False`

Returns:

Name	Type	Description
`euler`	`NDArray \| tuple[NDArray, NDArray[bool_]]`	Array of Euler angles. The first element in the array represents the angle around the first axis in the sequence.
`gimbal_lock`	`NDArray \| tuple[NDArray, NDArray[bool_]]`	Array of booleans indicating whether each Euler angle output was calculated from a gimbal lock condition.

as_quaternion ¶

as_quaternion() -> NDArray

Return the quaternion representation.

See additional documentation regarding quaternion conventions at: from_quaternion.

SciPy equivalent:

scipy.spatial.transform.Rotation.as_quat()

Returns:

Name	Type	Description
`quaternion`	`NDArray`	Array of quaternions.

as_rotation_vector ¶

as_rotation_vector() -> NDArray

Return the rotation vector representation.

See additional documentation regarding rotation vector conventions at: from_rotation_vector.

SciPy equivalent:

scipy.spatial.transform.Rotation.as_rotvec()

Returns:

Name	Type	Description
`rotation_vector`	`NDArray`	Array of rotation vectors.

as_axis_angle ¶

as_axis_angle() -> tuple[NDArray, NDArray]

Return the axis, angle representation.

See additional documentation regarding axis angle conventions at: from_axis_angle.

Returns:

Name	Type	Description
`axis`	`NDArray`	Array of axes of rotation.
`angle`	`NDArray`	Array of angles. Each angle corresponds to each axis.

inverse ¶

inverse() -> Self

Return the inverse of the current instance.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse of the current instance.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Compose multiple rotations.

Inputs must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of Rotation instances to be composed from first to last.	required

Returns:

Name	Type	Description
`composed`	`Self`	Rotation instance composed from the inputs.

integral_factor `classmethod` ¶

integral_factor(rotation_vector: NDArray) -> NDArray

Returns the first integral matrix factor.

Return the matrix factor, \(\mathbf{F}_{1}(\mathbf{\theta})\), that converts the integral of a vector, \(\mathbf{v}\), that is constant in a rotating (body/sensor) frame to the integral of \(\mathbf{v}\) in a fixed (world) frame. The moving frame rotates through rotation vector, \(\mathbf{\theta}\), relative to the fixed frame.

\[ \int_{t}^{t+\Delta t} \mathbf{v}^{w} dt = \mathbf{F}_{1}(\mathbf{\theta}) \mathbf{v}^{b} \Delta t \]

See Reference [01], Equation 19.1.3.4 and Reference [18], Equation 8.40.

Parameters:

Name	Type	Description	Default
`rotation_vector`	`NDArray`	Array of rotation vectors.	required

Returns:

Name	Type	Description
`integral_factor`	`NDArray`	Integral matrix factor.

double_integral_factor `classmethod` ¶

double_integral_factor(rotation_vector: NDArray) -> NDArray

Returns the double integral matrix factor.

Return the matrix factor, \(\mathbf{F}_{2}(\mathbf{\theta})\), that converts the double integral of a vector, \(\mathbf{v}\), that is constant in a rotating (body/sensor) frame to the double integral of \(\mathbf{v}\) in a fixed (world) frame. The moving frame rotates through rotation vector, \(\mathbf{\theta}\), relative to the fixed frame.

\[ \int_{t}^{t+\Delta t}\int_{t}^{t+\Delta t} \mathbf{v}^{w} dt = \frac{1}{2}\mathbf{F}_{2}(\mathbf{\theta}) \mathbf{v}^{b} \Delta t^{2} \]

See Reference [01], Equation 19.1.3.5 and Reference [18], Equation 9.2.1.1.

Parameters:

Name	Type	Description	Default
`rotation_vector`	`NDArray`	Array of rotation vectors.	required

Returns:

Name	Type	Description
`integral_factor`	`NDArray`	Integral matrix factor.

CoordinateTranslation ¶

CoordinateTranslation(
    xyz: ArrayLike, time: ArrayLike | None = None
)

Bases: Translation

3-dimensional coordinate frame translations.

CoordinateTranslation is a subclass of Translation and supports the same methods and attributes.

Methods:

Name	Description
`from_identity`	Construct an identity Vector.
`compose`	Add multiple vectors.
`inverse`	Return the inverse (negative) of the current instance.
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_xyz`	Construct a vector from Cartesian coordinates.
`from_spherical`	Construct a Vector from spherical coordinates.
`from_random`	Construct a Vector from random data.
`as_xyz`	Return the Cartesian representation.
`as_spherical`	Return the spherical representation.
`apply`	Apply coordinate translation to a vector input.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_vectors`	`int`	The number of vectors stored in the instance.
`num_translations`	`int`	The number of translations stored in the instance.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_vectors `property` ¶

num_vectors: int

The number of vectors stored in the instance.

num_translations `property` ¶

num_translations: int

The number of translations stored in the instance.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity Vector.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity vectors to store.	`1`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Add multiple vectors.

Inputs must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of Vector instances to add.	required

Returns:

Name	Type	Description
`composed`	`Self`	Vector instance composed from the inputs.

inverse ¶

inverse() -> Self

Return the inverse (negative) of the current instance.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse (negative) of the current instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_xyz `classmethod` ¶

from_xyz(
    xyz: ArrayLike, time: ArrayLike | None = None
) -> Self

Construct a vector from Cartesian coordinates.

Parameters:

Name	Type	Description	Default
`xyz`	`ArrayLike`	Array of Cartesian coordinates.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each vector input.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

from_spherical `classmethod` ¶

from_spherical(
    rpa: ArrayLike, time: ArrayLike | None = None
) -> Self

Construct a Vector from spherical coordinates.

Order and direction conventions

InertialSim uses the radius, polar angle, and azimuth angle convention (reflected in the "rpa" input variable name). The radius is the distance from the origin of the coordinate system to the point of interest. The polar angle is the angle between the z-axis and the radial line (in radians). The polar angle is also known as the inclination. The azimuth angle is the angle between the x-axis and the projection of the radial line on the x-y plane (in radians).

Angle range conventions

To be valid, the spherical coordinates must meet the following requirements:

0 <= range
0 <= polar_angle <= pi
-pi < azimuth <= pi or 0 <= azimuth < 2*pi

To standardize, the azimuth will be adjusted such that:

-pi < azimuth <= pi

Parameters:

Name	Type	Description	Default
`rpa`	`ArrayLike`	Array of spherical coordinates.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each vector input.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

from_random `classmethod` ¶

from_random(
    num_elements: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a Vector from random data.

Vector components will be uniformly distributed between 0 and 1.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of random vectors to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

as_xyz ¶

as_xyz() -> NDArray

Return the Cartesian representation.

Returns:

Name	Type	Description
`xyz`	`NDArray`	Array of Cartesian coordinates.

as_spherical ¶

as_spherical() -> NDArray

Return the spherical representation.

See additional documentation regarding spherical coordinate conventions at: from_spherical.

Returns:

Name	Type	Description
`rpa`	`NDArray`	Array of spherical coordinates.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Apply coordinate translation to a vector input.

A TypeError will be raised if the input is not an array.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	Array of cartesian vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	Array of vectors with translated inputs.

Translation ¶

Translation(xyz: ArrayLike, time: ArrayLike | None = None)

Bases: Vector

3-dimensional translations.

Translations represent the location of points relative to an origin in a generic geometric sense.

Translation is an alias for Vector and inherits all its functionality. It adds additional convenience attributes and methods.

See also geodesy.Coordinates which describe the location of points relative to the Earth.

Prefer the from methods to construct an instance.

Coordinate conventions

There are a variety of coordinate conventions and they are a common source of errors. Because many of these conventions cannot be automatically validated, users must be aware of them and manage interfaces with other software accordingly. InertialSim conventions are documented in info boxes in class and method documentation.

Internally translations are stored in Cartesian form.

Methods:

Name	Description
`from_identity`	Construct an identity Vector.
`apply`	Add vector to an input.
`compose`	Add multiple vectors.
`inverse`	Return the inverse (negative) of the current instance.
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_xyz`	Construct a vector from Cartesian coordinates.
`from_spherical`	Construct a Vector from spherical coordinates.
`from_random`	Construct a Vector from random data.
`as_xyz`	Return the Cartesian representation.
`as_spherical`	Return the spherical representation.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_vectors`	`int`	The number of vectors stored in the instance.
`num_translations`	`int`	The number of translations stored in the instance.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_vectors `property` ¶

num_vectors: int

The number of vectors stored in the instance.

num_translations `property` ¶

num_translations: int

The number of translations stored in the instance.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity Vector.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity vectors to store.	`1`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Add vector to an input.

A NotImplementedError will be raised if the input is not an array.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	Array of vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	Array of summed vectors.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Add multiple vectors.

Inputs must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of Vector instances to add.	required

Returns:

Name	Type	Description
`composed`	`Self`	Vector instance composed from the inputs.

inverse ¶

inverse() -> Self

Return the inverse (negative) of the current instance.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse (negative) of the current instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_xyz `classmethod` ¶

from_xyz(
    xyz: ArrayLike, time: ArrayLike | None = None
) -> Self

Construct a vector from Cartesian coordinates.

Parameters:

Name	Type	Description	Default
`xyz`	`ArrayLike`	Array of Cartesian coordinates.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each vector input.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

from_spherical `classmethod` ¶

from_spherical(
    rpa: ArrayLike, time: ArrayLike | None = None
) -> Self

Construct a Vector from spherical coordinates.

Order and direction conventions

InertialSim uses the radius, polar angle, and azimuth angle convention (reflected in the "rpa" input variable name). The radius is the distance from the origin of the coordinate system to the point of interest. The polar angle is the angle between the z-axis and the radial line (in radians). The polar angle is also known as the inclination. The azimuth angle is the angle between the x-axis and the projection of the radial line on the x-y plane (in radians).

Angle range conventions

To be valid, the spherical coordinates must meet the following requirements:

0 <= range
0 <= polar_angle <= pi
-pi < azimuth <= pi or 0 <= azimuth < 2*pi

To standardize, the azimuth will be adjusted such that:

-pi < azimuth <= pi

Parameters:

Name	Type	Description	Default
`rpa`	`ArrayLike`	Array of spherical coordinates.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each vector input.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

from_random `classmethod` ¶

from_random(
    num_elements: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a Vector from random data.

Vector components will be uniformly distributed between 0 and 1.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of random vectors to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

as_xyz ¶

as_xyz() -> NDArray

Return the Cartesian representation.

Returns:

Name	Type	Description
`xyz`	`NDArray`	Array of Cartesian coordinates.

as_spherical ¶

as_spherical() -> NDArray

Return the spherical representation.

See additional documentation regarding spherical coordinate conventions at: from_spherical.

Returns:

Name	Type	Description
`rpa`	`NDArray`	Array of spherical coordinates.

Vector ¶

Vector(xyz: ArrayLike, time: ArrayLike | None = None)

Bases: MatrixLieGroup

3-dimensional vectors.

Vectors can represent physical points, translations, accelerations, velocities or other arbitrary tuples in R3.

Prefer the from methods to construct an instance.

Internally vectors are stored in Cartesian form.

Methods:

Name	Description
`time_derivative`	Return a numerical derivative with respect to time.
`interpolate`	Interpolate values at the input times.
`from_identity`	Construct an identity Vector.
`from_xyz`	Construct a vector from Cartesian coordinates.
`from_spherical`	Construct a Vector from spherical coordinates.
`from_random`	Construct a Vector from random data.
`as_xyz`	Return the Cartesian representation.
`as_spherical`	Return the spherical representation.
`apply`	Add vector to an input.
`compose`	Add multiple vectors.
`inverse`	Return the inverse (negative) of the current instance.

Attributes:

Name	Type	Description
`num_elements`	`int`	The number of elements stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each element.
`num_vectors`	`int`	The number of vectors stored in the instance.

num_elements `property` ¶

num_elements: int

The number of elements stored in the instance.

time `property` ¶

time: NDArray | None

Array of times corresponding to each element.

Times are unique and strictly increasing.

num_vectors `property` ¶

num_vectors: int

The number of vectors stored in the instance.

time_derivative ¶

time_derivative(side: str = 'right') -> NDArray

Return a numerical derivative with respect to time.

Time derivatives on a Lie group have a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The result is calculated with first order forward differences. The instance must have at least two elements and timestamps or a ValueError is raised. The result has the same dimension as the Lie algebra and the length of the returned array will be one less than the number of elements in the instance.

Returns:

Name	Type	Description
`derivative`	`NDArray`	Time derivative array.

interpolate ¶

interpolate(time: ArrayLike, side: str = 'left') -> Self

Interpolate values at the input times.

Interpolation on a Lie group has a common structure. Derived classes that implement the abstract interfaces of MatrixLieGroup can call this method directly.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of the range of the original data will not be extrapolated but will return the end-points instead.

Example

A Rotation instance constructed with 2 rotation values at time indices [0 1] can be interpolated for any set of values in [0, 1], e.g. [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of unique, strictly increasing times (or indices) corresponding to each desired output.	required
`side`	`str`	Take the left or right difference in the interpolation.	`'left'`

Returns:

Name	Type	Description
`derived`	`Self`	New class instance constructed from the input times and interpolated group elements.

from_identity `classmethod` ¶

from_identity(num_elements: int = 1) -> Self

Construct an identity Vector.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of identity vectors to store.	`1`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

from_xyz `classmethod` ¶

from_xyz(
    xyz: ArrayLike, time: ArrayLike | None = None
) -> Self

Construct a vector from Cartesian coordinates.

Parameters:

Name	Type	Description	Default
`xyz`	`ArrayLike`	Array of Cartesian coordinates.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each vector input.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

from_spherical `classmethod` ¶

from_spherical(
    rpa: ArrayLike, time: ArrayLike | None = None
) -> Self

Construct a Vector from spherical coordinates.

Order and direction conventions

InertialSim uses the radius, polar angle, and azimuth angle convention (reflected in the "rpa" input variable name). The radius is the distance from the origin of the coordinate system to the point of interest. The polar angle is the angle between the z-axis and the radial line (in radians). The polar angle is also known as the inclination. The azimuth angle is the angle between the x-axis and the projection of the radial line on the x-y plane (in radians).

Angle range conventions

To be valid, the spherical coordinates must meet the following requirements:

0 <= range
0 <= polar_angle <= pi
-pi < azimuth <= pi or 0 <= azimuth < 2*pi

To standardize, the azimuth will be adjusted such that:

-pi < azimuth <= pi

Parameters:

Name	Type	Description	Default
`rpa`	`ArrayLike`	Array of spherical coordinates.	required
`time`	`ArrayLike \| None`	Array of unique, strictly increasing times corresponding to each vector input.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

from_random `classmethod` ¶

from_random(
    num_elements: int = 1,
    rng: Generator | int | None = None,
) -> Self

Construct a Vector from random data.

Vector components will be uniformly distributed between 0 and 1.

Parameters:

Name	Type	Description	Default
`num_elements`	`int`	The number of random vectors to create.	`1`
`rng`	`Generator \| int \| None`	Random number generator or seed. See numpy.random.default_rng.	`None`

Returns:

Name	Type	Description
`vector`	`Self`	A Vector instance.

as_xyz ¶

as_xyz() -> NDArray

Return the Cartesian representation.

Returns:

Name	Type	Description
`xyz`	`NDArray`	Array of Cartesian coordinates.

as_spherical ¶

as_spherical() -> NDArray

Return the spherical representation.

See additional documentation regarding spherical coordinate conventions at: from_spherical.

Returns:

Name	Type	Description
`rpa`	`NDArray`	Array of spherical coordinates.

apply ¶

apply(rhs: MatrixLieGroup) -> MatrixLieGroup

apply(rhs: ArrayLike) -> NDArray

apply(
    rhs: MatrixLieGroup | ArrayLike,
) -> MatrixLieGroup | NDArray

Add vector to an input.

A NotImplementedError will be raised if the input is not an array.

Parameters:

Name	Type	Description	Default
`rhs`	`MatrixLieGroup \| ArrayLike`	Array of vectors.	required

Returns:

Name	Type	Description
`result`	`MatrixLieGroup \| NDArray`	Array of summed vectors.

compose `classmethod` ¶

compose(instances: tuple[Self, ...]) -> Self

Add multiple vectors.

Inputs must have compatible dimensions and times.

Parameters:

Name	Type	Description	Default
`instances`	`tuple[Self, ...]`	Tuple of Vector instances to add.	required

Returns:

Name	Type	Description
`composed`	`Self`	Vector instance composed from the inputs.

inverse ¶

inverse() -> Self

Return the inverse (negative) of the current instance.

Returns:

Name	Type	Description
`inverse`	`Self`	A new instance containing the inverse (negative) of the current instance.

identity_matrix ¶

identity_matrix(
    rows: int = NUM_CARTESIAN_AXES,
    columns: int | None = None,
) -> NDArray

Return an identity matrix.

The output will have shape=(1,rows,columns). If rows and columns are not the same, the matrix has ones on the leading diagonal.

Parameters:

Name	Type	Description	Default
`rows`	`int`	The number of rows in the matrix.	`NUM_CARTESIAN_AXES`
`columns`	`int \| None`	The number of columns in the matrix. If None,	`None`

Returns:

Name	Type	Description
`matrix`	`NDArray`	Identity matrix.

matrix_array ¶

matrix_array(
    matrix: ArrayLike,
    rows: int,
    columns: int,
    *,
    copy: bool = False,
) -> NDArray

Convert input to matrix array.

Inputs are converted to numpy array format (if they are not already) and shape, size, and type conventions are enforced. Inputs can be 2-D or 3-D numpy array-like objects (shape in ((rows,columns), (N,rows,columns))) with each N representing a unique matrix. The input cannot be an empty array (size=0).

Outputs are 3-D numpy arrays with shape=(N,rows,columns) and 64-bit floating point data type.

Raises a ValueError if the input cannot be converted.

Parameters:

Name	Type	Description	Default
`matrix`	`ArrayLike`	Array of matrices.	required
`rows`	`int`	The number of rows in the matrix.	required
`columns`	`int`	The number of columns in the matrix.	required
`copy`	`bool`	If True, then the object is copied. If False, a copy will only be made if needed.	`False`

Returns:

Name	Type	Description
`matrix`	`NDArray`	The input modified to conform to InertialSim conventions.

ones_vector ¶

ones_vector(dimension: int = NUM_CARTESIAN_AXES) -> NDArray

Return a vector array of ones.

The output will have shape=(1,dimension,1).

Parameters:

Name	Type	Description	Default
`dimension`	`int`	The number of rows in the vector.	`NUM_CARTESIAN_AXES`

Returns:

Name	Type	Description
`vector`	`NDArray`	Ones vector.

scalar_array ¶

scalar_array(
    array: ArrayLike, *, copy: bool = False
) -> NDArray

Convert input to scalar array.

Inputs are converted to numpy array format (if they are not already) and shape, size, and type conventions are enforced. Inputs can be scalars, or 1-D, 2-D, or 3-D numpy array-like objects (shape in ((N,), (N,1), (N,1,1))) with each N representing a unique input element. The input cannot be an empty array (size=0).

Outputs are 3-D numpy arrays with shape=(N,1,1) and 64-bit floating point data type.

Raises a ValueError if the input cannot be converted.

Parameters:

Name	Type	Description	Default
`array`	`ArrayLike`	An array-like input (numpy array, list, tuple, etc.).	required
`copy`	`bool`	If True, then the object is copied. If False, a copy will only be made if needed.	`False`

Returns:

Name	Type	Description
`array`	`NDArray`	The input modified to conform to InertialSim conventions.

vector_array ¶

vector_array(
    vector: ArrayLike,
    dimension: int,
    *,
    unit_vector: bool = False,
    copy: bool = False,
) -> NDArray

Convert input to a vector array.

Inputs are converted to numpy array format (if they are not already) and shape, size, and type conventions are enforced. Inputs can be 1-D, 2-D, or 3-D numpy array-like objects (shape in ((dimension,), (dimension,1), (N,dimension), (N,dimension,1))) with each N representing a unique vector. The input cannot be an empty array (size=0).

Outputs are 3-D numpy arrays with shape=(N,dimension,1) and 64-bit floating point data type.

As an option, each input can be checked for unit length (2-norm = 1.0).

Raises a ValueError if the input cannot be converted or if the optional unit vector check fails.

Note: This function can be used even if the input is not mathematically a vector, e.g. an array of Euler angle values.

Parameters:

Name	Type	Description	Default
`vector`	`ArrayLike`	Array of vectors.	required
`dimension`	`int`	Dimension of the vector space (e.g. 3 for Cartesian space).	required
`unit_vector`	`bool`	If True, checks that each input is a unit vector (2-norm = 1.0).	`False`
`copy`	`bool`	If True, then the object is copied. If False, a copy will only be made if needed.	`False`

Returns:

Name	Type	Description
`vector`	`NDArray`	The input modified to conform to InertialSim conventions.

zero_vector ¶

zero_vector(dimension: int = NUM_CARTESIAN_AXES) -> NDArray

Return a vector array of zeros.

The output will have shape=(1,dimension,1).

Parameters:

Name	Type	Description	Default
`dimension`	`int`	The number of rows in the vector.	`NUM_CARTESIAN_AXES`

Returns:

Name	Type	Description
`vector`	`NDArray`	Zero vector.

inertialsim.geometry ¶

FP_TOLERANCE module-attribute ¶

MatrixLieGroup ¶

num_elements property ¶

time property ¶

from_identity abstractmethod classmethod ¶

apply abstractmethod ¶

compose classmethod ¶

inverse abstractmethod ¶

time_derivative ¶

interpolate ¶

ExtendedPose ¶

num_elements property ¶

time property ¶

num_poses property ¶

attitude property ¶

position property ¶

velocity property ¶

compose classmethod ¶

time_derivative ¶

interpolate ¶

from_identity classmethod ¶

from_apv classmethod ¶

from_random classmethod ¶

as_apv ¶

as_attitude ¶

as_position ¶

as_velocity ¶

apply ¶

inverse ¶

Pose ¶

num_elements property ¶

time property ¶

num_transforms property ¶

rotation property ¶

translation property ¶

num_poses property ¶

attitude property ¶

position property ¶

from_identity classmethod ¶

apply ¶

compose classmethod ¶

inverse ¶

time_derivative ¶

interpolate ¶

from_homogeneous_matrix classmethod ¶

from_rotation_translation classmethod ¶

from_random classmethod ¶

as_homogeneous_matrix ¶

as_rotation_translation ¶

as_rotation ¶

as_translation ¶

from_attitude_position classmethod ¶

as_attitude ¶

as_position ¶

CoordinateTransform ¶

num_elements property ¶

time property ¶

num_transforms property ¶

rotation property ¶

translation property ¶

from_identity classmethod ¶

compose classmethod ¶

inverse ¶

time_derivative ¶

interpolate ¶

from_rotation_translation classmethod ¶

from_random classmethod ¶

as_rotation_translation ¶

as_rotation ¶

as_translation ¶

from_homogeneous_matrix classmethod ¶

as_homogeneous_matrix ¶

apply ¶

RigidTransform ¶

num_elements property ¶

time property ¶

num_transforms property ¶

rotation property ¶

translation property ¶

FP_TOLERANCE `module-attribute` ¶

num_elements `property` ¶

time `property` ¶

from_identity `abstractmethod` `classmethod` ¶

apply `abstractmethod` ¶

compose `classmethod` ¶

inverse `abstractmethod` ¶

num_elements `property` ¶

time `property` ¶

num_poses `property` ¶

attitude `property` ¶

position `property` ¶

velocity `property` ¶

compose `classmethod` ¶

from_identity `classmethod` ¶

from_apv `classmethod` ¶

from_random `classmethod` ¶

num_elements `property` ¶

time `property` ¶

num_transforms `property` ¶

rotation `property` ¶

translation `property` ¶

num_poses `property` ¶

attitude `property` ¶

position `property` ¶

from_identity `classmethod` ¶

compose `classmethod` ¶

from_homogeneous_matrix `classmethod` ¶

from_rotation_translation `classmethod` ¶

from_random `classmethod` ¶

from_attitude_position `classmethod` ¶

num_elements `property` ¶

time `property` ¶

num_transforms `property` ¶

rotation `property` ¶

translation `property` ¶

from_identity `classmethod` ¶

compose `classmethod` ¶

from_rotation_translation `classmethod` ¶

from_random `classmethod` ¶

from_homogeneous_matrix `classmethod` ¶

num_elements `property` ¶

time `property` ¶

num_transforms `property` ¶

rotation `property` ¶

translation `property` ¶

from_identity `classmethod` ¶

from_homogeneous_matrix `classmethod` ¶

from_rotation_translation `classmethod` ¶

from_random `classmethod` ¶

compose `classmethod` ¶

num_elements `property` ¶

time `property` ¶

num_rotations `property` ¶

from_identity `classmethod` ¶

compose `classmethod` ¶

from_matrix `classmethod` ¶

from_quaternion `classmethod` ¶

from_random `classmethod` ¶

integral_factor `classmethod` ¶

double_integral_factor `classmethod` ¶

from_euler `classmethod` ¶

from_rotation_vector `classmethod` ¶

from_axis_angle `classmethod` ¶

num_elements `property` ¶

time `property` ¶

num_rotations `property` ¶

from_identity `classmethod` ¶

from_matrix `classmethod` ¶

from_euler `classmethod` ¶

from_quaternion `classmethod` ¶

from_rotation_vector `classmethod` ¶

from_axis_angle `classmethod` ¶

from_random `classmethod` ¶

compose `classmethod` ¶

integral_factor `classmethod` ¶

double_integral_factor `classmethod` ¶

num_elements `property` ¶

time `property` ¶

num_vectors `property` ¶