Setting Extra Joints¶

Overview ¶

In a Choreonoid body model, links are connected by joints as a tree structure. On the other hand, there are mechanisms with connections that cannot be represented by a tree structure, such as closed-link mechanisms. You may also want to connect objects to each other in simulation.

The “extra joint” is a function for realizing such connections. An extra joint is a constraint added between any two links, and when it is set, the simulator item loads it at the start of the simulation and the corresponding constraint forces act in the simulation.

Constraint Types ¶

The following types of constraints are available for extra joints.

ball

Makes the constraint points set on the two links coincide. The relative rotation around the constraint point remains free; this constraint corresponds to a spherical joint.

hinge

Makes the axis lines of the constraint axes set on the two links coincide, allowing only the relative rotation around the axis. This constraint corresponds to a revolute joint.

piston

Constrains the translation in the directions orthogonal to the constraint axis, allowing the relative translation along the axis and the relative rotation around the axis. This constraint corresponds to a cylindrical joint.

fixed

Completely fixes the relative position and orientation of the two links.

Description in Model Files ¶

Extra joints between links in the same model are described as a list under the top-level extra_joints key in a body-format model file. The following is an example corresponding to the description in the sample model of a closed-link mechanism (share/model/misc/ClosedLinkSample.body).

extra_joints:
  -
    link1_name: J1
    link2_name: J3
    joint_type: hinge
    axis: [ 0, 0, 1 ]
    translation_in_link1: [ 0.2, 0, 0 ]
    translation_in_link2: [ 0, 0.1, 0 ]

The following keys can be set for each entry.

Key	Meaning
`link1_name`	The name of one of the links to be constrained.
`link2_name`	The name of the other link to be constrained.
`joint_type`	The type of the constraint, specified from “ball”, “hinge”, “piston”, and “fixed”.
`axis`	The constraint axis. It is used when joint_type is hinge or piston.
`translation_in_link1` / `translation_in_link2`	The position of the constraint point in the local coordinates of each link.
`rotation_in_link1` / `rotation_in_link2`	The orientation of the constraint frame in the local coordinates of each link, specified in the axis-angle format ([x, y, z, θ]) (optional).

For the details of the description in model files, see also ExtraJoint Node.

Support Status for Each Simulator Item ¶

Extra joints are available in most simulator items, but the supported constraint types differ depending on the simulator item. The support status is as follows.

Constraint type	AIST	PhysX	MuJoCo	Bullet	ODE	AGX
ball	○	○	○	○	○	○
hinge	○	○	○	○	○	○
piston	○	○	×	○	○	○
fixed	×	○	○	○	○	○
Constraints across different bodies	○	○	○	○	○	×

When an unsupported constraint type is set, the constraint is ignored.

Constraints across Different Bodies ¶

Extra joints can also be set between links of different body models (only with the simulators supporting this in the above table). This makes it possible, for example, to connect a robot link and an object in the environment.

Since the extra_joints description in a model file can only describe constraints between links in the same model, constraints across different bodies are set by creating an ExtraJoint object from a Python script or a C++ program and registering it to the target bodies. Refer to the ExtraJointSample described below for a concrete example.

Samples ¶

The following sample projects using extra joints are provided. Each sample contains the simulator items of the physics engines, and you can also compare the behaviors of the engines.

ClosedLinkSample ¶

sample/general/ClosedLinkSample.cnoid is a sample of a closed-link mechanism. In the model file (share/model/misc/ClosedLinkSample.body), extra_joints is described at the top level and the loop of the link mechanism is closed with a hinge-type constraint. This model file is a good reference for describing extra joints in model files.

ExtraJointSample ¶

sample/general/ExtraJointSample.cnoid is a sample of an extra joint across different bodies. The Python script included in the project (ExtraJoint.py) dynamically sets a ball-type constraint between the wrist link of the SR1 robot and the link of a box model, and the simulation runs with the robot hanging the box. This is a good reference for setting extra joints from a script or a program.

In addition, the following models bundled with Choreonoid are examples of real robot models that use extra joints. They are also good references for the description in model files.

Robotiq 2F-85 gripper (share/model/Robotiq/2F-85.body)

The loops of the link mechanisms of the gripper fingers, which consist of parallel link mechanisms, are realized with hinge-type extra joints.

Double-arm construction robot DoubleArmV7 (share/model/DoubleArmV7/; described in DoubleArmV7-Upper.body, which is loaded from DoubleArmV7A.body etc.)

The loops of the link mechanisms of the gripper part are realized with ball-type extra joints. This model is used in the samples of World Robot Summit 2018.

Four-wheel car model FourWheelCar (share/model/misc/FourWheelCar.body)

The closed link of the steering mechanism is realized with hinge-type extra joints.