Spatial vector algebra

# Spatial vector algebra

## Types

### Coordinate frames

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
CartesianFrame3D(name)


Create a CartesianFrame3D with the given name.

source
CartesianFrame3D()


Create an anonymous CartesianFrame3D.

source

### Transforms

struct Transform3D{T}

A homogeneous transformation matrix representing the transformation from one three-dimensional Cartesian coordinate system to another.

source

### Points, free vectors

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
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

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

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
struct SpatialAcceleration{T}

A spatial acceleration is the time derivative of a twist.

See Twist.

source

### Momenta, wrenches

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
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

### Geometric Jacobians

struct GeometricJacobian{A<:(AbstractArray{T,2} where T)}

A geometric Jacobian (also known as basic, or spatial Jacobian) maps a vector of joint velocities to a twist.

source

### Momentum matrices

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

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

center_of_mass(inertia)


Return the center of mass of the SpatialInertia as a Point3D.

source
kinetic_energy(inertia, twist)


Compute the kinetic energy of a body with spatial inertia $I$, which has twist $T$ with respect to an inertial frame.

source
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
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
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
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
transform(x, t)


Return x transformed to CartesianFrame3D t.from.

source
transform(jac, tf)


Transform the GeometricJacobian to a different frame.

source
transform(f, tf)


Transform the Momentum to a different frame.

source
transform(x, t)


Return x transformed to CartesianFrame3D t.from.

source
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
transform(inertia, t)


Transform the SpatialInertia to a different frame.

source
transform(twist, tf)


Transform the Twist to a different frame.

source
transform(f, tf)


Transform the Wrench to a different frame.

source
exp(twist)


Convert exponential coordinates to a homogeneous transform.

source
log(t)


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

source
dot(w, t)


Compute the mechanical power associated with a pairing of a wrench and a twist.

source

Equivalent to one of

mapslices(x -> f(a, x), B, dims=1)
mapslices(x -> f(x, b), A, dims=1)

but optimized for statically-sized matrices.

source