# Spatial vector algebra

## Types

### Coordinate frames

RigidBodyDynamics.Spatial.CartesianFrame3DType
struct CartesianFrame3D

A CartesianFrame3D identifies a three-dimensional Cartesian coordinate system.

CartesianFrame3Ds are typically used to annotate the frame in which certain quantities are expressed.

source

### Points, free vectors

RigidBodyDynamics.Spatial.Point3DType
struct Point3D{V<:(AbstractArray{T,1} where T)}

A Point3D represents a position in a given coordinate system.

A Point3D is a bound vector. Applying a Transform3D to a Point3D both rotates and translates the Point3D.

source
RigidBodyDynamics.Spatial.FreeVector3DType
struct FreeVector3D{V<:(AbstractArray{T,1} where T)}

A FreeVector3D represents a free vector.

Examples of free vectors include displacements and velocities of points.

Applying a Transform3D to a FreeVector3D only rotates the FreeVector3D.

source

### Inertias

RigidBodyDynamics.Spatial.SpatialInertiaType
struct SpatialInertia{T}

A spatial inertia, or inertia matrix, represents the mass distribution of a rigid body.

A spatial inertia expressed in frame $i$ is defined as:

$$$I^i = \int_{B}\rho\left(x\right)\left[\begin{array}{cc} \hat{p}^{T}\left(x\right)\hat{p}\left(x\right) & \hat{p}\left(x\right)\\ \hat{p}^{T}\left(x\right) & I \end{array}\right]dx=\left[\begin{array}{cc} J & \hat{c}\\ \hat{c}^{T} & mI \end{array}\right]$$$

where $\rho(x)$ is the density of point $x$, and $p(x)$ are the coordinates of point $x$ expressed in frame $i$. $J$ is the mass moment of inertia, $m$ is the total mass, and $c$ is the 'cross part', center of mass position scaled by $m$.

Warning

The moment field of a SpatialInertia is the moment of inertia about the origin of its frame, not about the center of mass.

source

### Twists, spatial accelerations

RigidBodyDynamics.Spatial.TwistType
struct Twist{T}

A twist represents the relative angular and linear motion between two bodies.

The twist of frame $j$ with respect to frame $i$, expressed in frame $k$ is defined as

$$$T_{j}^{k,i}=\left(\begin{array}{c} \omega_{j}^{k,i}\\ v_{j}^{k,i} \end{array}\right)\in\mathbb{R}^{6}$$$

such that

$$$\left[\begin{array}{cc} \hat{\omega}_{j}^{k,i} & v_{j}^{k,i}\\ 0 & 0 \end{array}\right]=H_{i}^{k}\dot{H}_{j}^{i}H_{k}^{j}$$$

where $H^{\beta}_{\alpha}$ is the homogeneous transform from frame $\alpha$ to frame $\beta$, and $\hat{x}$ is the $3 \times 3$ skew symmetric matrix that satisfies $\hat{x} y = x \times y$ for all $y \in \mathbb{R}^3$.

Here, $\omega_{j}^{k,i}$ is the angular part and $v_{j}^{k,i}$ is the linear part. Note that the linear part is not in general the same as the linear velocity of the origin of frame $j$.

source

### Momenta, wrenches

RigidBodyDynamics.Spatial.MomentumType
struct Momentum{T}

A Momentum is the product of a SpatialInertia and a Twist, i.e.

$$$h^i = \left(\begin{array}{c} k^{i}\\ l^{i} \end{array}\right) = I^i T^{i, j}_k$$$

where $I^i$ is the spatial inertia of a given body expressed in frame $i$, and $T^{i, j}_k$ is the twist of frame $k$ (attached to the body) with respect to inertial frame $j$, expressed in frame $i$. $k^i$ is the angular momentum and $l^i$ is the linear momentum.

source
RigidBodyDynamics.Spatial.WrenchType
struct Wrench{T}

A wrench represents a system of forces.

The wrench $w^i$ expressed in frame $i$ is defined as

$$$w^{i} = \left(\begin{array}{c} \tau^{i}\\ f^{i} \end{array}\right) = \sum_{j}\left(\begin{array}{c} r_{j}^{i}\times f_{j}^{i}\\ f_{j}^{i} \end{array}\right)$$$

where the $f_{j}^{i}$ are forces expressed in frame $i$, exerted at positions $r_{j}^{i}$. $\tau^i$ is the total torque and $f^i$ is the total force.

source

### Momentum matrices

RigidBodyDynamics.Spatial.MomentumMatrixType
struct MomentumMatrix{A<:(AbstractArray{T,2} where T)}

A momentum matrix maps a joint velocity vector to momentum.

This is a slight generalization of the centroidal momentum matrix (Orin, Goswami, "Centroidal momentum matrix of a humanoid robot: Structure and properties.") in that the matrix (and hence the corresponding total momentum) need not be expressed in a centroidal frame.

source

## The @framecheck macro

RigidBodyDynamics.Spatial.@framecheckMacro

Check that CartesianFrame3D f1 is one of f2s.

Note that if f2s is a CartesianFrame3D, then f1 and f2s are simply checked for equality.

Throws an ArgumentError if f1 is not among f2s when bounds checks are enabled. @framecheck is a no-op when bounds checks are disabled.

source

## Functions

Base.expMethod
exp(twist)


Convert exponential coordinates to a homogeneous transform.

source
Base.logMethod
log(t)


Express a homogeneous transform in exponential coordinates centered around the identity.

source
RigidBodyDynamics.Spatial.log_with_time_derivativeMethod
log_with_time_derivative(t, twist)


Compute exponential coordinates as well as their time derivatives in one shot. This mainly exists because ForwardDiff won't work at the singularity of log. It is also ~50% faster than ForwardDiff in this case.

source
RigidBodyDynamics.Spatial.newton_eulerMethod
newton_euler(inertia, spatial_accel, twist)


Apply the Newton-Euler equations to find the external wrench required to make a body with spatial inertia $I$, which has twist $T$ with respect to an inertial frame, achieve spatial acceleration $\dot{T}$.

This wrench is also equal to the rate of change of momentum of the body.

source
RigidBodyDynamics.Spatial.point_accelerationMethod
point_acceleration(twist, accel, point)


Given the twist $dot{T}_{j}^{k,i}$ of frame $j$ with respect to frame $i$, expressed in frame $k$ and its time derivative (a spatial acceleration), as well as the location of a point fixed in frame $j$, also expressed in frame $k$, compute the acceleration of the point relative to frame $i$.

source
RigidBodyDynamics.Spatial.point_velocityMethod
point_velocity(twist, point)


Given the twist $T_{j}^{k,i}$ of frame $j$ with respect to frame $i$, expressed in frame $k$, and the location of a point fixed in frame $j$, also expressed in frame $k$, compute the velocity of the point relative to frame $i$.

source
RigidBodyDynamics.Spatial.transformMethod
transform(accel, old_to_new, twist_of_current_wrt_new, twist_of_body_wrt_base)


Transform the SpatialAcceleration to a different frame.

The transformation rule is obtained by differentiating the transformation rule for twists.

source