Cartesian end-effector control using site transmission.

- Added `refsite` attribute to actuators with `site` transmission.
- Such actuators now have a well defined length and can be used for e.g., Cartesian end-effector control.
- Added example models and documentation describing the new feature.

PiperOrigin-RevId: 471561218
Change-Id: I538f09af9600d5c53992c4a9fed325648aab4fa3

doc/XMLreference.rst

@@ -4302,25 +4302,42 @@ specify them independently.
 :at:`joint`: :at-val:`string, optional`
    This and the next four attributes determine the type of actuator transmission. All of them are optional, and exactly
    one of them must be specified. If this attribute is specified, the actuator acts on the given joint. For **hinge**
-   and **slide** joints, the actuator length equals the joint position/angle times the first element of gear. For
+   and **slide** joints, the actuator length equals the joint position/angle times the first element of :at:`gear`. For
    **ball** joints, the first three elements of gear define a 3d rotation axis in the child frame around which the
    actuator produces torque. The actuator length is defined as the dot-product between this gear axis and the angle-axis
-   representation of the joint quaternion position. For **free** joints, gear defines a 3d translation axis in the world
-   frame followed by a 3d rotation axis in the child frame. The actuator generates force and torque relative to the
-   specified axes. The actuator length for free joints is defined as zero (so it should not be used with position
-   servos).
+   representation of the joint quaternion, and is in units of radian if :at:`gear` is normalized (generally scaled by
+   by the norm of :at:`gear`). Note that after total rotation of more than :math:`\pi`, the length will wrap to :math:`-
+   \pi`, and vice-versa. Therefore :el:`position` servos for ball joints should generally use tighter limits which
+   prevent this wrapping. For **free** joints, gear defines a 3d translation axis in the world frame followed by a 3d
+   rotation axis in the child frame. The actuator generates force and torque relative to the specified axes. The
+   actuator length for free joints is defined as zero (so it should not be used with position servos).
 :at:`jointinparent`: :at-val:`string, optional`
    Identical to joint, except that for ball and free joints, the 3d rotation axis given by gear is defined in the parent
    frame (which is the world frame for free joints) rather than the child frame.
 :at:`site`: :at-val:`string, optional`
-   This transmission can apply force and torque at a site. The gear vector defines a 3d translation axis followed by a 3d
-   rotation axis. Both are defined in the site's frame. This can be used to model jets and propellers. The effect is
-   similar to actuating a free joint, and the actuator length is again defined as zero. One difference from the joint
-   and jointinparent transmissions above is that here the actuator operates on a site rather than a joint, but this
-   difference disappears when the site is defined at the frame origin of the free-floating body. The other difference is
-   that for site transmissions both the translation and rotation axes are defined in local coordinates. In contrast,
-   translation is global and rotation is local for joint, and both translation and rotation are global for
-   jointinparent.
+   This transmission can apply force and torque at a site. The gear vector defines a 3d translation axis followed by a
+   3d rotation axis. Both are defined in the site's frame. This can be used to model jets and propellers. The effect is
+   similar to actuating a free joint, and the actuator length is defined as zero unless a :at:`refsite` is defined (see
+   below). One difference from the :at:`joint` and :at:`jointinparent` transmissions above is that here the actuator
+   operates on a site rather than a joint, but this difference disappears when the site is defined at the frame origin
+   of the free-floating body. The other difference is that for site transmissions both the translation and rotation axes
+   are defined in local coordinates. In contrast, translation is global and rotation is local for :at:`joint`, and both
+   translation and rotation are global for :at:`jointinparent`.
+
+..  youtube:: s-0JHanqV1A
+    :align: right
+    :height: 150px
+
+:at:`refsite`: :at-val:`string, optional`
+   When using a :at:`site` transmission, measure the translation and rotation w.r.t the frame of the :at:`refsite`. In
+   this case the actuator *does* have length and :el:`position` actuators can be used to directly control an end
+   effector, see `refsite.xml <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/refsite.xml>`_ example
+   model. As above, the length is the dot product of the :at:`gear` vector and the frame difference. So ``gear="0 1 0 0
+   0 0"`` means "Y-offset of :at:`site` in the :at:`refsite` frame", while ``gear="0 0 0 0 0 1"`` means rotation "Z-
+   rotation of :at:`site` in the :at:`refsite` frame". It is recommended to use a normalized :at:`gear` vector with
+   nonzeros in only the first 3 *or* the last 3 elements of :at:`gear`, so the actuator length will be in either length
+   units or radians, respectively. As with ball joints (see :at:`joint` above), for rotations which exceed a total angle
+   of :math:`\pi` will wrap around, so tighter limits are recommended.
 :at:`body`: :at-val:`string, optional`
    This transmission can apply linear forces at contact points in the direction of the contact normal. The set of
    contacts is all those belonging to the specified :at:`body`. This can be used to model natural active adhesion

doc/changelog.rst

@@ -21,8 +21,16 @@ General
 - Increased ``mjNEQDATA``, the row length of equality constraint parameters in ``mjModel.eq_data``, from 7 to 11.
 - Added visualisation of anchor points for both :el:`connect` and :el:`weld` constraints (activated by the 'N' key in
   ``simulate``).
-- Added `example model <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/weld.xml>`_ showing different
+- Added `weld.xml <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/weld.xml>`_ showing different
   uses of new weld attributes.
+
+  ..  youtube:: s-0JHanqV1A
+      :align: right
+      :height: 150px
+
+- Cartesian 6D end-effector control is now possible by adding a reference site to actuators with :at:`site`
+  transmission. See description of new :at:`refsite` attribute in the :ref:`actuator<general>` documentation and
+  `refsite.xml <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/refsite.xml>`_ example model.
 - Joint and tendon ``limited`` attribute and actuator ``ctrllimited``, ``forcelimited`` and ``actlimited`` attributes
   now default to ``auto`` rather than ``false``. Limits are automatically set to ``true`` if the corresponding range *is
   defined* and ``false`` otherwise.
@@ -49,7 +57,7 @@ General
 - Added ``mjv_defaultFreeCamera`` which sets the default free camera, respecting the above attributes.
 - ``simulate`` now supports taking a screenshot via a button in the File section or via ``Ctrl-P``.
 - Improvements to time synchronisation in `simulate`, in particular report actual real-time factor if different from
-  requested factor.
+  requested factor (if e.g., the timestep is so small that simulation cannot keep up with real-time).
 - Added a disable flag for sensors.
 - :ref:`mju_mulQuat` and :ref:`mju_mulQuatAxis` support in place computation. For example
   |br| ``mju_mulQuat(a, a, b);`` sets the quaternion ``a`` equal to the product of ``a`` and ``b``.

doc/computation.rst

@@ -255,14 +255,20 @@ These three components of an actuator - transmission, activation dynamics, and f
 actuator works. The user can set them independently for maximum flexibility, or use :ref:`Actuator shortcuts
 <CActuator>` which instantiate common actuator types.
 
-Transmission
+.. _geTransmission:
 
-   Each actuator has a scalar length :math:`l_i(q)` defined by the type of transmission and its parameters. The gradient
-   :math:`\nabla l_i` is an :math:`n_V`-dimensional vector of moment arms. It determines the mapping from scalar
-   actuator force to joint force. The transmission properties are determined by the MuJoCo object to which the actuator
-   is attached; the possible attachment object types are :at:`joint`, :at:`tendon`, :at:`jointinparent`,
-   :at:`slider-crank`, :at:`site`, and :at:`body`. The :at:`joint` and :at:`tendon` transmission types act as expected
-   mechanically and correspond to the actuator applying forces or torques to the target object.
+Transmission
+~~~~~~~~~~~~
+
+Each actuator has a scalar length :math:`l_i(q)` defined by the type of transmission and its parameters. The gradient
+:math:`\nabla l_i` is an :math:`n_V`-dimensional vector of moment arms. It determines the mapping from scalar
+actuator force to joint force. The transmission properties are determined by the MuJoCo object to which the actuator
+is attached; the possible attachment object types are :at:`joint`, :at:`tendon`, :at:`jointinparent`,
+:at:`slider-crank`, :at:`site`, and :at:`body`.
+
+   The :at:`joint` and :at:`tendon` transmission types act as expected and correspond to the actuator applying forces or
+   torques to the target object. Ball joints are special, see the :at:`joint` documentation in :ref:`actuator<general>`
+   reference for more details.
 
    The :at:`jointinparent` transmission is unique to ball and free joint and asserts that rotation should be measured
    in the parent rather than child frame.
@@ -273,11 +279,18 @@ Transmission
    also be modeled explicitly by creating MuJoCo bodies and coupling them with equality constraints to the rest of the
    system, but that would be less efficient.
 
-   :at:`site` and :at:`body` are degenerate transmission targets, as their length :math:`l_i(q)` is always 0.
-   They can therefore not be used to maintain a desired length value, as with a position actuator. Site
-   transmissions correspond to applying a Cartsian force/torque at the site, while :el:`body` transmissions correspond
-   to applying forces at contact points belonging to a body. For more information about adhesion, see the
-   :ref:`adhesion<adhesion>` shorcut documentation.
+   :at:`site` transmission (without a :at:`refsite`, see below) and :at:`body` transmission targets have a fixed zero
+   length :math:`l_i(q) = 0`. They can therefore not be used to maintain a desired length, but can be used to apply
+   forces. Site transmissions correspond to applying a Cartsian force/torque at the site, and are useful for modeling
+   jets and propellors. :el:`body` transmissions correspond to applying forces at contact points belonging to a body, in
+   order to model vacuum grippers and biomechanical adhesive appendages. For more information about adhesion, see the
+   :ref:`adhesion<adhesion>` actuator documentation.
+
+   If a :at:`site` transmission target is defined with the optional :at:`refsite` attribute, forces and torques are
+   applied in the frame of the reference site rather than the the site's own frame. If a reference site is defined then
+   the length of the actuator is nonzero and corresponds to the pose difference of the two sites. This length can then
+   be controlled with a :el:`position` actuator, enabling Cartesian end-effector control. See the :at:`refsite`
+   documentation in :ref:`actuator<general>` reference for more details.
 
 Activation dynamics
    Some actuators such as pneumatic and hydraulic cylinders as well as biological muscles have an internal state called