Import upstream snapshot 80e710700aac9573a2230f74f7ce9e094833a0bc

Upstream: https://github.com/Rhoban/onshape-to-robot Upstream-Commit: 80e710700aac9573a2230f74f7ce9e094833a0bc Upstream-Branch: master
2026-08-28 15:42:31 +08:00
commit bb87928bce
107 changed files with 16958 additions and 0 deletions
@@ -0,0 +1,87 @@
+.. _kinematic-loops:
+
+Handling kinematic loops
+========================
+
+Some robots have *kinematic loops*, meaning that the kinematic chain is not a tree but a graph.
+
+Introduction
+------------
+
+Here is a 2D planar robot with kinematic loop, we assume the two first joints to be actuated and the others to
+be passive:
+
+.. raw:: html
+
+    <center>
+    <video width="70%" controls>
+    <source src="https://github.com/Rhoban/placo-examples/raw/master/kinematics/videos/planar_2dof_trajectory.mp4" type="video/mp4">
+    </video>
+    </center>
+    <br/>
+
+
+However, robot description are usually **trees**. To model this type of robot, we break it down to a tree. We attach **frames** to this tree, and need to enforce **run-time constraints**.
+
+.. image:: _static/img/opened_chain.png    
+    :width: 300px
+    :align: center
+
+
+Specifying closing constraints
+------------------------------
+
+While you could manually add :ref:`frames <custom-frames>`, ``onshape-to-robot`` provides a more convenient way to handle kinematic loops: **mate connectors**.
+
+To achieve that, add a **mate** with the name ``closing_something``:
+
+.. image:: _static/img/loop.png    
+    :align: center
+    :class: padding
+
+
+Support for ``<equality>`` in MuJoCo
+------------------------------------
+
+When using the :ref:`MuJoCo <exporter-mujoco>` format, ``onshape-to-robot`` will add ``<equality>`` constraints to enforce the kinematic loop.
+
+For example, the above robot can be exported using the following ``config.json``:
+
+.. code-block:: javascript
+
+    {
+        // Document URL, MuJoCo output
+        "url": "https://cad.onshape.com/documents/04b05c47de7576f35c0e99b3/w/68041f3f5c827a258b40039c/e/db543f501b01adf8144064e3",
+        "output_format": "mujoco",
+
+        // Disable the freejoint to fix the robot
+        "freejoint": false,
+
+        // Don't create actuators for passive joints
+        "joint_properties": {
+            "passive1": {"actuated": false},
+            "passive2": {"actuated": false}
+        }
+    }
+
+Here is the result of the export:
+
+.. raw:: html
+
+    <center>
+    <video width="70%" controls>
+    <source src="https://github.com/Rhoban/onshape-to-robot-examples/raw/refs/heads/master/videos/planar_2dof_mujoco.mp4" type="video/mp4">
+    </video>
+    </center>
+    <br/>
+
+
+Ressources
+----------
+
+Here are some ressources on how to handle kinematic loops in software:
+
+* `Onshape assembly <https://cad.onshape.com/documents/04b05c47de7576f35c0e99b3/w/68041f3f5c827a258b40039c/e/db543f501b01adf8144064e3?renderMode=0&uiState=665d8e3a6de6705d2f788204>`_ for the above example robot.
+* MuJoCo `equality <https://mujoco.readthedocs.io/en/stable/computation/index.html#coequality>`_ constraints.
+* In `pyBullet <https://pybullet.org/wordpress/>`_, you can use `createConstraint` method to add the relevant constraint.
+* In the `PlaCo <https://placo.readthedocs.io/>`_ solver, you can create a `RelativePositionTask`. See the `kinematics loop documentation section <https://placo.readthedocs.io/en/latest/kinematics/loop_closures.html>`_ for  more details. Some examples created with onshape-to-robot can be found in the `example gallery <https://placo.readthedocs.io/en/latest/kinematics/examples_gallery.html>`_.