Make tendon sidesite select the homotopy class of the path through the side site.

PiperOrigin-RevId: 1010128817
Change-Id: I27ebdc0c1acac072bc562cf2a14743b28fb3668a

Author: yuvaltassa

doc/XMLreference.rst

@@ -5727,9 +5727,27 @@ constrained to pass through the geom instead of passing around it.
 
 :at:`sidesite`: :at-val:`string, optional`
    To prevent the tendon path from snapping from one side of the geom to the other as the model configuration varies,
-   the user can define a preferred "side" of the geom. At runtime, the wrap that is closer to the specified site is
-   automatically selected. Specifying a side site is often needed in practice. If the side site is inside the geom, the
-   tendon is constrained to pass through the interior of the geom.
+   the user can define a preferred "side" of the geom. The tendon then goes around the geom the same way as the path
+   from the first endpoint :math:`p_1`, through the side site :math:`s` (projected onto the surface of the geom), to the
+   second endpoint :math:`p_2`. If the straight segment between the endpoints already passes the geom that way, the
+   tendon does not wrap. Formally, the tendon is the shortest path from :math:`p_1` to :math:`p_2` that is homotopic to
+   the polyline :math:`p_1 \to s \to p_2` in the wrapping plane with the geom removed, i.e., that has the same winding
+   angle around the geom center. In the images below, the side site is green and the polyline is the thin grey line.
+
+   .. image:: images/XMLreference/sidesite_homotopy_light.svg
+      :align: center
+      :width: 90%
+      :class: only-light
+
+   .. image:: images/XMLreference/sidesite_homotopy_dark.svg
+      :align: center
+      :width: 90%
+      :class: only-dark
+
+   The tendon snaps off the geom when an endpoint crosses the ray opposite the side site, so side sites should be placed
+   such that the endpoints do not cross this ray over the range of motion, typically near the middle of the wrapped
+   arc. Specifying a side site is often needed in practice. If the side site is inside the geom, the tendon is
+   constrained to pass through the interior of the geom.
 
 
 .. _spatial-pulley:

doc/changelog.rst

@@ -79,6 +79,46 @@ General
 
 Engine
 ^^^^^^
+.. admonition:: Breaking changes
+   :class: attention
+
+   - Changed the semantics of :ref:`sidesite<spatial-geom-sidesite>`: the tendon now goes around the geom the same way
+     as the path from the first endpoint, through the side site, to the second endpoint (thin grey line below).
+     Formally, the tendon is the shortest path homotopic to this polyline in the wrapping plane with the geom removed.
+
+     .. image:: images/XMLreference/sidesite_homotopy_light.svg
+        :align: center
+        :width: 90%
+        :class: only-light
+
+     .. image:: images/XMLreference/sidesite_homotopy_dark.svg
+        :align: center
+        :width: 90%
+        :class: only-dark
+
+     Previously, a half-plane test was used, which could make the tendon jump onto the geom, a discontinuity in tendon
+     length, when the segment between the endpoints moved away from the side site while clear of the geom. It could
+     also select the wrong side for wraps longer than 180 degrees. Top row: old rule; bottom row: new rule.
+
+     .. image:: images/changelog/sidesite_old_vs_new_light.svg
+        :align: center
+        :width: 90%
+        :class: only-light
+
+     .. image:: images/changelog/sidesite_old_vs_new_dark.svg
+        :align: center
+        :width: 90%
+        :class: only-dark
+
+     The new rule has a single discontinuity: when an endpoint crosses the ray opposite the side site, the path
+     through the side site changes its winding around the geom and the tendon snaps off. This can change the behavior
+     of existing models.
+
+     **Migration:** Place side sites so that the endpoints do not cross this ray over the range of motion, typically
+     near the middle of the wrapped arc. For example, the side sites of the
+     `two-link arm <https://github.com/google-deepmind/mujoco/blob/main/model/tendon_arm/arm26.xml>`__ were moved from
+     directly below the joints to 45 degrees below the arm, which reproduces the previous tendon lengths exactly.
+
 - Flex improvements:
 
   - Volumetric interpolated flexes (**trilinear** or **quadratic** :ref:`dofs<body-flexcomp-dof>` with ``elastic2d="none"``)