Skip to content

Commit

Permalink
Proposal for Mimic Constraint Feature (#62)
Browse files Browse the repository at this point in the history 
This proposal suggests a new mimic constraint for
joint axes that is functionally similar to the gearbox
joint type but simpler to express and more flexible.
It is targeted at SDFormat 1.11 / libsdformat14.

Signed-off-by: Steve Peters <[email protected]>
Co-authored-by: Aditya Pande <[email protected]>
  • Loading branch information
@scpeters @adityapande-1995
scpeters and adityapande-1995 authored Aug 28, 2023
1 parent f0a72ce commit ff5a051
Show file tree
Hide file tree
Showing 2 changed files with 327 additions and 0 deletions.
12 changes: 12 additions & 0 deletions manifest.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,17 @@
<skill>advanced</skill>
</tutorial>

<tutorial title="Mimic constraint to replace the Gearbox joint type" ref='mimic_proposal' type='proposal'>
<markdown version="1.10">mimic_constraint/proposal.md</markdown>
<description>
Proposal for a mimic constraint between joint axes to replace the Gearbox joint type.
</description>
<tags>
<tag>joint</tag>
</tags>
<skill>advanced</skill>
</tutorial>

</tutorials>

<!-- *************************************** -->
Expand Down Expand Up @@ -325,6 +336,7 @@
<tutorial>composition_merge_proposal</tutorial>
<tutorial>better_pose_proposal</tutorial>
<tutorial>added_mass_proposal</tutorial>
<tutorial>mimic_proposal</tutorial>
</tutorials>
</category>

Expand Down
315 changes: 315 additions & 0 deletions mimic_constraint/proposal.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,315 @@
# Proposal for Mimic Joint Actuation Constraint

* **Authors**:
Steve Peters`<[email protected]>`,
Aditya Pande `<[email protected]>`
* **Status**: *Draft*
* **SDFormat Version**: *1.11+*
* **`libsdformat` Version**: *14*

## Introduction

This proposal suggests adding a new joint actuation constraint called the Mimic
constraint that enforces a linear relationship between the output position
of two joint axes.

Currently, the Gearbox joint type provides equivalent functionality for
three specified links along specified axis directions if the three links are
also connected by two revolute joints with matching axis directions.
This is an issue because it requires duplication of axis definitions, and it is
nonintuitive to specify three links instead of two joints.

The Mimic constraint will simplify the definition of this constraint by
specifying the joint axes to which it applies instead of links so
that the joint axis information does not need to be duplicated.
It will be more flexible than the Gearbox joint by
allowing constraints on the output of prismatic joints and other
joints with translational outputs.

## Document summary

* *Syntax*: description of XPath syntax used in this proposal.
* *Motivation*:
* *Proposed changes*:
* *Examples*:

## Syntax

The proposal uses [XPath syntax](https://www.w3schools.com/xml/xpath_syntax.asp)
to describe elements and attributes concisely.
For example, `<model>` tags are referred to as `//model` using XPath.
XPath is even more concise for referring to nested tags and attributes.
In the following example, `<link>` elements inside `<model>` tags are
referenced as `//model/link` and model `name` attributes as `//model/@name`:

<model name="model_name">
<link/>
</model>

## Motivation

Currently, a Gearbox joint is specified by the following SDFormat parameters:

* 3 links
* `//joint/gearbox_reference_body`
* `//joint/parent`
* `//joint/child`
* 2 axis directions
* `//joint/axis/xyz`
* `//joint/axis2/xyz`
* 1 scalar
* `//joint/gearbox_ratio`

The relative rotation of the `child` link with respect to the
`gearbox_reference_body` about the `//joint/axis/xyz` direction is defined as
`angle_C`, and similarly for the `parent` link with respect to the
`gearbox_reference_body` about the `//joint/axis2/xyz` direction as `angle_P`.
The Gearbox joint creates a proportional equality constraint:

`angle_C = -gearbox_ratio * angle_P`

The Gearbox joint is typically used in conjunction with a pair of
revolute joints with identical axes, so the axis definitions must be duplicated
between the revolute joints and the gearbox joint.
The Gearbox joint only constrains the rotational motion of revolute joints,
so it cannot model constraints involving translational motion,
such as a rack and pinion mechanism.

The proposed Mimic constraint will simplify the specification of joint output
constraints by eliminating the need for redundant information.
This simplification is achieved by specifying the pair of joint axes to which
a Mimic constraint applies instead of specifying a group of three links,
a pair of axis directions, and a separate pair of revolute joints with
redundant axis information.
The Mimic constraint will also be more flexible than the gearbox joints
expanding the number of joint types that are supported, such as prismatic
joints and other joints with translational outputs.

## Proposed changes

This section defines the Mimic constraint mathematically and then explains
how to specify it in an SDFormat `//joint` element.

### Definition of Mimic constraint

A Mimic constraint encodes a linear equality constraint on the position of
two joint axes. One joint axis is labelled as the *leader* and the other as the
*follower*. The `multiplier`, `offset`, and `reference` parameters determine
the linear relationship according to the equation below.

`follower_position = multiplier * (leader_position - reference) + offset`

The `multiplier` parameter represents the ratio between changes in the
*follower* joint axis position relative to changes in the *leader* joint axis
position.

`multiplier = (follower_position - offset) / (leader_position - reference)`

Note that the `multiplier` and `offset` parameters match the parameters of the
[URDF mimic](https://wiki.ros.org/urdf/XML/joint#Elements)
tag if the `reference` parameter is `0`.

### New SDFormat tags: `//axis/mimic` and `//axis2/mimic`

To specify the Mimic constraint between two joint axes, an optional `//mimic`
tag is added to the `//joint/axis` and `//joint/axis2` elements.
The `//mimic` tag should be added to the *follower* joint axis, and
the *leader* joint axis is specified using the `//mimic/@joint` and
`//mimic/@axis` attributes. The `multiplier`, `offset`, and `reference`
parameters are specified as child elements of `//mimic`.

An alternative was to add a new joint type called a Mimic joint,
but since URDF already supports the `//joint/mimic` tag (see
[URDF documentation](https://wiki.ros.org/urdf/XML/joint) and
[ros/robot\_state\_publisher#1](https://github.com/ros/robot_state_publisher/issues/1))
it would be more consistent to add a new sdf tag called ``<mimic>`` inside
the ``//joint/axis/`` tag.

### Details of `//mimic`

When added to a `//joint/axis` or `//joint/axis2` element, the `//mimic` tag
causes that joint axis to be treated as the *follower* in a Mimic constraint.
The `//mimic` tag must have a `@joint` attribute that specifies the name of a
joint accessible from the current scope and may optionally specify an `@axis`
attribute as well. The `@axis` attribute has a default value of `axis`, and
its only valid values are `axis` and `axis2`. Together, the `@joint` and
`@axis` attributes specify the *leader* joint axis for the mimic constraint.
Note that the `@axis` attribute may only take a value of `axis2` if `@joint`
refers to a multi-axis joint.
The `multiplier`, `offset`, and `reference` parameters are specified in the
`//mimic/multiplier`, `/mimic/offset`, and `/mimic/reference` child elements,
respectively.

~~~
<mimic joint="leader_joint_name" axis="axis">
<multiplier>1.0</multiplier>
<offset>0.0</offset>
<reference>0.0</reference>
</mimic>
~~~

### Deprecation of `gearbox` joint type

Since the `mimic` joint provides equivalent functionality to the gearbox joint
but with more flexibility and less repeated information, the `gearbox` joint
type and the associated `//joint/gearbox_reference_body` and
`//joint/gearbox_ratio` elements are deprecated.

## Examples

### Alternative to gearbox joint type

There is an example `gearbox` joint in the
[demo\_joint\_types](https://github.com/osrf/gazebo_models/blob/master/demo_joint_types/model.sdf#L156-L328)
model, consisting of three links,

~~~
<link name="gearbox_base">
<pose >-.49 0 0.35 0 0 0</pose>
<!-- ... -->
</link>
<link name="gearbox_input">
<pose >-.38 -0.075 0.55 0 0 0</pose>
<!-- ... -->
<visual name="gearbox_input_visual">
<geometry>
<box>
<size>0.1 0.25 0.1</size>
</box>
</geometry>
</visual>
</link>
<link name="gearbox_output">
<pose >-.3 0.0 0.55 0 1.5708 0</pose>
<visual name="gearbox_output_visual">
<geometry>
<cylinder>
<radius>0.1</radius>
<length>0.05</length>
</cylinder>
</geometry>
</visual>
</link>
~~~

two `revolute` joints,

~~~
<!-- Gearbox links revolute joints, so create a couple revolute joints -->
<joint name="gearbox_input_joint" type="revolute">
<parent>gearbox_base</parent>
<child>gearbox_input</child>
<axis>
<xyz>1 0 0</xyz>
</axis>
<pose>0 0.075 0 0 0 0</pose>
</joint>
<joint name="gearbox_output_joint" type="revolute">
<parent>gearbox_base</parent>
<child>gearbox_output</child>
<axis>
<xyz>0 0 1</xyz>
</axis>
<pose>0 0 0 0 0 0</pose>
</joint>
~~~

and one `gearbox` joint.

~~~
<joint name="gearbox_demo" type="gearbox">
<parent>gearbox_input</parent>
<child>gearbox_output</child>
<gearbox_reference_body>gearbox_base</gearbox_reference_body>
<gearbox_ratio>5</gearbox_ratio>
<!-- input axis (relative to child) -->
<axis>
<xyz>0 0 1</xyz>
</axis>
<!-- output axis (relative to child) -->
<axis2>
<xyz>0 0 1</xyz>
</axis2>
</joint>
~~~

The `gearbox` joint could be replaced equivalently by adding the `<mimic>`
tag to joint axes :

~~~
<!-- Gearbox links revolute joints, so create a couple revolute joints -->
<joint name="gearbox_input_joint" type="revolute">
<parent>gearbox_base</parent>
<child>gearbox_input</child>
<axis>
<xyz>1 0 0</xyz>
</axis>
<pose>0 0.075 0 0 0 0</pose>
</joint>
<joint name="gearbox_output_joint" type="revolute">
<parent>gearbox_base</parent>
<child>gearbox_output</child>
<axis>
<xyz>1 0 0</xyz>
<mimic joint="gearbox_input_joint">
<multiplier>5</multiplier>
<offset>0</offset>
<reference>0</reference>
</mimic>
</axis>
</joint>
~~~

### Example of rack and pinion constraint

Another advantage of the Mimic constraint compared to the Gearbox joint is
support for translational joints. The following example shows a rack and
pinion mechanism with the translation of a prismatic "rack" joint coupled
to the rotation of the revolute "pinion" joint.

~~~
<sdf version="1.10">
<model name="mimic_rack_and_pinion">
<link name="rack">
<pose >0 0 -0.03 0 0 0</pose>
<visual name="box_visual">
<geometry>
<box>
<size>0.4 0.03 0.03</size>
</box>
</geometry>
</visual>
</link>
<link name="pinion">
<pose degrees='true'>0 0 0.02 90 0 0</pose>
<visual name="cylinder_visual">
<geometry>
<cylinder>
<length>0.03</length>
<radius>0.02</radius>
</cylinder>
</geometry>
</visual>
</link>
<joint name="pinion_joint" type="revolute">
<parent>world</parent>
<child>pinion</child>
<axis>
<xyz>0 1 0</xyz>
</axis>
</joint>
<joint name="rack_joint" type="prismatic">
<parent>world</parent>
<child>rack</child>
<axis>
<xyz>1 0 0</xyz>
<mimic joint="pinion_joint">
<multiplier>0.02</multiplier>
<offset>0.0</offset>
<reference>0.0</reference>
</mimic>
</axis>
</joint>
</model>
</sdf>
~~~

0 comments on commit ff5a051

Please sign in to comment.