# Mechanisms

## The Mechanism type

RigidBodyDynamics.MechanismType
mutable struct Mechanism{T}

A Mechanism represents an interconnection of rigid bodies and joints. Mechanisms store the joint layout and inertia parameters, but no state-dependent information.

source

## Creating and modifying Mechanisms

RigidBodyDynamics.MechanismMethod

Create a new Mechanism containing only a root body, to which other bodies can be attached with joints.

The gravity keyword argument can be used to set the gravitational acceleration (a 3-vector expressed in the Mechanism's root frame). Default: [0.0, 0.0, -9.81].

source
RigidBodyDynamics.attach!Method
attach!(mechanism, parentbody, childmechanism; child_root_pose, bodymap, jointmap)


Attach a copy of childmechanism to mechanism.

Essentially replaces the root body of a copy of childmechanism with parentbody (which belongs to mechanism).

Note: gravitational acceleration for childmechanism is ignored.

Keyword arguments:

• child_root_pose: pose of the default frame of the root body of childmechanism relative to that of parentbody. Default: the identity transformation.
• bodymap::AbstractDict{RigidBody{T}, RigidBody{T}}: will be populated with the mapping from input mechanism's bodies to output mechanism's bodies
• jointmap::AbstractDict{<:Joint{T}, <:Joint{T}}: will be populated with the mapping from input mechanism's joints to output mechanism's joints

where T is the element type of mechanism.

source
RigidBodyDynamics.attach!Method
attach!(mechanism, predecessor, successor, joint; joint_pose, successor_pose)


Attach successor to predecessor using joint.

See Joint for definitions of the terms successor and predecessor.

The Transform3Ds joint_pose and successor_pose define where joint is attached to each body. joint_pose should define frame_before(joint) with respect to any frame fixed to predecessor, and likewise successor_pose should define any frame fixed to successor with respect to frame_after(joint).

predecessor is required to already be among the bodies of the Mechanism.

If successor is not yet a part of the Mechanism, it will be added to the Mechanism. Otherwise, the joint will be treated as a non-tree edge in the Mechanism, effectively creating a loop constraint that will be enforced using Lagrange multipliers (as opposed to using recursive algorithms).

source
RigidBodyDynamics.maximal_coordinatesMethod

Return a dynamically equivalent Mechanism, but with a flat tree structure: all bodies are attached to the root body via a floating joint, and the tree joints of the input Mechanism are transformed into non-tree joints (with joint constraints enforced using Lagrange multipliers in dynamics!).

Keyword arguments:

• floating_joint_type::Type{<:JointType{T}}: which floating joint type to use for the joints between each body and the root. Default: QuaternionFloating{T}
• bodymap::AbstractDict{RigidBody{T}, RigidBody{T}}: will be populated with the mapping from input mechanism's bodies to output mechanism's bodies
• jointmap::AbstractDict{<:Joint{T}, <:Joint{T}}: will be populated with the mapping from input mechanism's joints to output mechanism's joints

where T is the element type of mechanism.

source
RigidBodyDynamics.rand_tree_mechanismMethod
rand_tree_mechanism(_, parentselector, jointtypes)


Create a random tree Mechanism with the given joint types. Each new body is attached to a parent selected using the parentselector function.

source
RigidBodyDynamics.rebuild_spanning_tree!Method
rebuild_spanning_tree!(mechanism)
rebuild_spanning_tree!(mechanism, flipped_joint_map; next_edge)


Reconstruct the mechanism's spanning tree.

Optionally, the flipped_joint_map keyword argument can be used to pass in an associative container that will be populated with a mapping from original joints to flipped joints, if the rebuilding process required the polarity of some joints to be flipped.

Also optionally, next_edge can be used to select which joints should become part of the new spanning tree.

source
RigidBodyDynamics.remove_joint!Method
remove_joint!(mechanism, joint; flipped_joint_map, spanning_tree_next_edge)


Remove a joint from the mechanism. Rebuilds the spanning tree if the joint is part of the current spanning tree.

Optionally, the flipped_joint_map keyword argument can be used to pass in an associative container that will be populated with a mapping from original joints to flipped joints, if removing joint requires rebuilding the spanning tree of mechanism and the polarity of some joints needed to be changed in the process.

Also optionally, spanning_tree_next_edge can be used to select which joints should become part of the new spanning tree, if rebuilding the spanning tree is required.

source
RigidBodyDynamics.submechanismMethod
submechanism(mechanism, submechanismroot; bodymap, jointmap)


Create a new Mechanism from the subtree of mechanism rooted at submechanismroot.

Any non-tree joint in mechanism will appear in the returned Mechanism if and only if both its successor and its predecessor are part of the subtree.

Keyword arguments:

• bodymap::AbstractDict{RigidBody{T}, RigidBody{T}}: will be populated with the mapping from input mechanism's bodies to output mechanism's bodies
• jointmap::AbstractDict{<:Joint{T}, <:Joint{T}}: will be populated with the mapping from input mechanism's joints to output mechanism's joints

where T is the element type of mechanism.

source

## Basic functionality

RigidBodyDynamics.body_fixed_frame_definitionMethod
body_fixed_frame_definition(mechanism, frame)


Return the definition of body-fixed frame frame, i.e., the Transform3D from frame to the default frame of the body to which it is attached.

Note: this function is linear in the number of bodies and is not meant to be called in tight loops.

source
RigidBodyDynamics.body_fixed_frame_to_bodyMethod
body_fixed_frame_to_body(mechanism, frame)


Return the RigidBody to which frame is attached.

Note: this function is linear in the number of bodies and is not meant to be called in tight loops.

source
RigidBodyDynamics.findbodyMethod
findbody(mechanism, name)


Return the RigidBody with the given name. Errors if there is no body with the given name, or if there's more than one.

source
RigidBodyDynamics.findjointMethod
findjoint(mechanism, name)


Return the Joint with the given name. Errors if there is no joint with the given name, or if there's more than one.

source
RigidBodyDynamics.fixed_transformMethod
fixed_transform(mechanism, from, to)


Return the transform from CartesianFrame3D from to to, both of which are rigidly attached to the same RigidBody.

Note: this function is linear in the number of bodies and is not meant to be called in tight loops.

source
RigidBodyDynamics.pathMethod
path(mechanism, from, to)


Return the path from rigid body from to to along edges of the Mechanism's kinematic tree.

source