Search documentation of bb

# BB.Robot.Transform (bb v0.8.0)

View Source

Homogeneous transformation matrices for robot kinematics.

All transforms are represented as 4x4 Nx tensors in row-major order:

    | R11 R12 R13 Tx |
    | R21 R22 R23 Ty |
    | R31 R32 R33 Tz |
    |  0   0   0   1 |

Where the upper-left 3x3 is the rotation matrix and the rightmost column is the translation vector.

## Conventions

- All angles are in radians
- All distances are in meters
- Rotations use XYZ Euler angles (roll-pitch-yaw)
- Coordinate frame follows right-hand rule

# Summary

## Functions

apply_to_point(transform, arg)

Apply a transform to a 3D point, returning the transformed point.

compose(transform_a, transform_b)

Compose (multiply) two transformation matrices.

compose_all(list)

Compose a list of transforms in order.

from_origin(arg1)

Create a transformation matrix from position and orientation.

get_rotation(transform)

Get the rotation matrix (3x3) from a transform.

get_translation(transform)

Get the translation component of a transform as {x, y, z}.

identity()

Create a 4x4 identity transformation matrix.

inverse(transform)

Compute the inverse of a transformation matrix.

prismatic_transform(arg, distance)

Create a transform for a prismatic joint translation along an axis.

revolute_transform(arg, angle)

Create a transform for a revolute joint rotation around an axis.

rotation_x(angle)

Create a rotation matrix around the X axis (roll).

rotation_y(angle)

Create a rotation matrix around the Y axis (pitch).

rotation_z(angle)

Create a rotation matrix around the Z axis (yaw).

translation(x, y, z)

Create a pure translation matrix.

# Functions

# apply_to_point(transform, arg)

    @spec apply_to_point(Nx.Tensor.t(), {float(), float(), float()}) ::
      {float(), float(), float()}

Apply a transform to a 3D point, returning the transformed point.

## Examples

    iex> t = BB.Robot.Transform.translation(1.0, 2.0, 3.0)
    iex> BB.Robot.Transform.apply_to_point(t, {0.0, 0.0, 0.0})
    {1.0, 2.0, 3.0}

# compose(transform_a, transform_b)

    @spec compose(Nx.Tensor.t(), Nx.Tensor.t()) :: Nx.Tensor.t()

Compose (multiply) two transformation matrices.

`compose(a, b)` returns the transform that applies `a` first, then `b`.

## Examples

    iex> t1 = BB.Robot.Transform.translation(1.0, 0.0, 0.0)
    iex> t2 = BB.Robot.Transform.translation(0.0, 2.0, 0.0)
    iex> t = BB.Robot.Transform.compose(t1, t2)
    iex> BB.Robot.Transform.get_translation(t)
    {1.0, 2.0, 0.0}

# compose_all(list)

    @spec compose_all([Nx.Tensor.t()]) :: Nx.Tensor.t()

Compose a list of transforms in order.

## Examples

    iex> transforms = [
    ...>   BB.Robot.Transform.translation(1.0, 0.0, 0.0),
    ...>   BB.Robot.Transform.translation(0.0, 1.0, 0.0),
    ...>   BB.Robot.Transform.translation(0.0, 0.0, 1.0)
    ...> ]
    iex> t = BB.Robot.Transform.compose_all(transforms)
    iex> BB.Robot.Transform.get_translation(t)
    {1.0, 1.0, 1.0}

# from_origin(arg1)

    @spec from_origin(%{
      position: {float(), float(), float()},
      orientation: {float(), float(), float()}
    }) ::
      Nx.Tensor.t()

Create a transformation matrix from position and orientation.

The origin map should have:

- `position`: {x, y, z} in meters
- `orientation`: {roll, pitch, yaw} in radians

Rotation is applied in XYZ order (roll around X, then pitch around Y, then yaw around Z).

## Examples

    iex> origin = %{position: {1.0, 2.0, 3.0}, orientation: {0.0, 0.0, 0.0}}
    iex> t = BB.Robot.Transform.from_origin(origin)
    iex> BB.Robot.Transform.get_translation(t)
    {1.0, 2.0, 3.0}

# get_rotation(transform)

    @spec get_rotation(Nx.Tensor.t()) :: Nx.Tensor.t()

Get the rotation matrix (3x3) from a transform.

# get_translation(transform)

    @spec get_translation(Nx.Tensor.t()) :: {float(), float(), float()}

Get the translation component of a transform as {x, y, z}.

# identity()

    @spec identity() :: Nx.Tensor.t()

Create a 4x4 identity transformation matrix.

## Examples

    iex> BB.Robot.Transform.identity() |> Nx.to_list()
    [[1.0, 0.0, 0.0, 0.0],
     [0.0, 1.0, 0.0, 0.0],
     [0.0, 0.0, 1.0, 0.0],
     [0.0, 0.0, 0.0, 1.0]]

# inverse(transform)

    @spec inverse(Nx.Tensor.t()) :: Nx.Tensor.t()

Compute the inverse of a transformation matrix.

For a valid transformation matrix, this computes the inverse transform.

# prismatic_transform(arg, distance)

    @spec prismatic_transform({float(), float(), float()}, float()) :: Nx.Tensor.t()

Create a transform for a prismatic joint translation along an axis.

## Parameters

- `axis`: normalised axis vector {x, y, z}
- `distance`: translation distance in meters

## Examples

    iex> axis = {1.0, 0.0, 0.0}  # X axis
    iex> t = BB.Robot.Transform.prismatic_transform(axis, 2.5)
    iex> BB.Robot.Transform.get_translation(t)
    {2.5, 0.0, 0.0}

# revolute_transform(arg, angle)

    @spec revolute_transform({float(), float(), float()}, float()) :: Nx.Tensor.t()

Create a transform for a revolute joint rotation around an axis.

## Parameters

- `axis`: normalised axis vector {x, y, z}
- `angle`: rotation angle in radians

## Examples

    iex> axis = {0.0, 0.0, 1.0}  # Z axis
    iex> t = BB.Robot.Transform.revolute_transform(axis, :math.pi() / 2)
    iex> {x, y, _z} = BB.Robot.Transform.apply_to_point(t, {1.0, 0.0, 0.0})
    iex> {Float.round(x, 6), Float.round(y, 6)}
    {0.0, 1.0}

# rotation_x(angle)

    @spec rotation_x(float()) :: Nx.Tensor.t()

Create a rotation matrix around the X axis (roll).

## Examples

    iex> t = BB.Robot.Transform.rotation_x(:math.pi() / 2)
    iex> {_, _, z} = BB.Robot.Transform.apply_to_point(t, {0.0, 1.0, 0.0})
    iex> Float.round(z, 6)
    1.0

# rotation_y(angle)

    @spec rotation_y(float()) :: Nx.Tensor.t()

Create a rotation matrix around the Y axis (pitch).

# rotation_z(angle)

    @spec rotation_z(float()) :: Nx.Tensor.t()

Create a rotation matrix around the Z axis (yaw).

# translation(x, y, z)

    @spec translation(float(), float(), float()) :: Nx.Tensor.t()

Create a pure translation matrix.

## Examples

    iex> t = BB.Robot.Transform.translation(1.0, 2.0, 3.0)
    iex> BB.Robot.Transform.get_translation(t)
    {1.0, 2.0, 3.0}