Mechanisms

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.

Mechanism(root_body; gravity)

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

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.

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

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.

Create a random chain Mechanism with the given joint types.

rand_floating_tree_mechanism(_, nonfloatingjointtypes)

Create a random tree Mechanism, with a quaternion floating joint as the first joint (between the root body and the first non-root body).

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.

Create a random tree Mechanism.

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.

Remove any fixed joints present as tree edges in mechanism by merging the rigid bodies that these fixed joints join together into bodies with equivalent inertial properties.

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.

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.

bodies(mechanism)

Return the RigidBodys that are part of the Mechanism as an iterable collection.

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.

See also default_frame, frame_definition.

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.

findbody(mechanism, id)

Return the RigidBody with the given BodyID.

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.

findjoint(mechanism, id)

Return the Joint with the given JointID.

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.

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.

in_joints(body, mechanism)

Return the joints that have body as their successor.

joint_to_parent(body, mechanism)

Return the joint that is part of the mechanism's kinematic tree and has body as its successor.

joints(mechanism)

Return the Joints that are part of the Mechanism as an iterable collection.

joints_to_children(body, mechanism)

Return the joints that are part of the mechanism's kinematic tree and have body as their predecessor.

non_tree_joints(mechanism)

Return the Joints that are not part of the Mechanism's spanning tree as an iterable collection.

num_additional_states(mechanism)

Return the dimension of the vector of additional states $s$ (used for stateful contact models).

num_constraints(mechanism)

Return the number of constraints imposed by the mechanism's non-tree joints (i.e., the number of rows of the constraint Jacobian).

num_positions(mechanism)

Return the dimension of the joint configuration vector $q$.

num_velocities(mechanism)

Return the dimension of the joint velocity vector $v$.

out_joints(body, mechanism)

Return the joints that have body as their predecessor.

path(mechanism, from, to)

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

predecessor(joint, mechanism)

Return the body 'before' the joint, i.e. the 'tail' of the joint interpreted as an arrow in the Mechanism's kinematic graph.

See Joint.

root_body(mechanism)

Return the root (stationary 'world') body of the Mechanism.

root_frame(mechanism)

Return the default frame of the root body.

successor(joint, mechanism)

Return the body 'after' the joint, i.e. the 'head' of the joint interpreted as an arrow in the Mechanism's kinematic graph.

See Joint.

tree_joints(mechanism)

Return the Joints that are part of the Mechanism's spanning tree as an iterable collection.