Add geom surfacevel: zero-dof conveyors, treadmills and turntables.

https://www.youtube.com/watch?v=PdSdrqhSiZA

The new geom attribute surfacevel (6 numbers: linear and angular velocity in the geom's local frame, angular about the geom frame origin) specifies the velocity of the geom's surface material relative to the geom frame. The relative surface velocity of the two geoms is added to the tangential contact rows of efc_vel in mj_referenceConstraint, so friction drives touching bodies toward the motion of the surface: objects on a conveyor are transported at belt speed, turntables impart omega x r with torsional spin-up for condim >= 4, and surface velocities compose with each other and with body motion. The component along the contact normal is projected out: probe experiments showed that velocity-space emission chatters mass-independently and ingestion merely deepens penetration; normal-direction effects belong to force-space features.

surfacevel is interpreted in the geom frame as authored: for mesh geoms, whose compiled frame absorbs the mesh centering and principal-axes transform, the compiler re-expresses the authored value in the compiled frame.

No special interaction with sleeping: objects being transported do not fall asleep because they are moving; objects at rest on an active surface may sleep like any other resting object.

Includes showcase models (model/surfacevel/): a luggage carousel whose ring is a spinning square-profile supertorus fed by a cascade of belts with matched spinning end rollers, bags dropping in and circulating indefinitely; and a treadmill with a passive humanoid.

PiperOrigin-RevId: 948647785
Change-Id: I0c6559a91cc7ece1237eb8ac2e51986e7342d962

doc/XMLreference.rst

@@ -2771,6 +2771,32 @@ helps clarify the role of bodies and geoms in MuJoCo.
    actuators which use contacts in the gap zone to generate adhesive forces without producing contact forces.
    See :ref:`margin and gap<coMarginGap>`.
 
+.. _body-geom-surfacevel:
+
+.. youtube:: PdSdrqhSiZA
+   :align: right
+   :width: 35%
+
+:at:`surfacevel`: :at-val:`real(6), "0 0 0 0 0 0"`
+   Velocity of the geom's surface as seen by contacts, given as a velocity field :math:`\sigma(x)` with two components:
+   a constant velocity :math:`v` (first three numbers) and a rotational field with angular velocity :math:`\omega` (last
+   three numbers) about the geom frame origin :math:`p`, both expressed in the geom frame:
+
+   .. math::
+      \sigma(x) = v + \omega \times (x - p)
+
+   A contact with the geom observes the surface moving along this field, with the velocity projected onto the contact's
+   tangent plane: no normal velocity is imparted. When :at:`condim` is 4 or larger, the angular velocity :math:`\omega`
+   also drives torsional friction. :at:`surfacevel` models surfaces that move while the geom itself does not: conveyor
+   belts, treadmills and turntables can be constructed with no degrees of freedom. Friction drives touching bodies along
+   the motion of the surface: objects placed on a conveyor are transported at belt speed, and a turntable (angular
+   surface velocity about the cylinder axis) imparts tangential velocity that grows with radius. Surface velocities of
+   two touching geoms compose as relative velocity, and compose correctly with body motion (a conveyor mounted on a
+   moving vehicle works as expected). Note that this attribute describes the geom's *entire* surface: a box with
+   constant ``surfacevel`` moves all six faces. When contact points are visualized, a contact with a moving surface
+   additionally displays an arrow along the tangential surface velocity at the contact point. This attribute can be
+   modified at runtime.
+
 .. _body-geom-fromto:
 
 :at:`fromto`: :at-val:`real(6), optional`
@@ -3460,10 +3486,12 @@ joints and tendons have different sets of attributes, while all geoms in the com
 
 .. _composite-geom-gap:
 
+.. _composite-geom-surfacevel:
+
 .. |body/composite/geom attrib list| replace::
    :at:`type`, :at:`contype`, :at:`conaffinity`, :at:`condim`, :at:`group`, :at:`priority`, :at:`size`, :at:`material`,
    :at:`rgba`, :at:`friction`, :at:`mass`, :at:`density`, :at:`solmix`, :at:`solref`, :at:`solimp`, :at:`margin`,
-   :at:`gap`
+   :at:`gap`, :at:`surfacevel`
 
 |body/composite/geom attrib list|
    Same meaning as regular :ref:`geom <body-geom>` attributes.
@@ -9540,6 +9568,8 @@ if omitted.
 
 .. _default-geom-gap:
 
+.. _default-geom-surfacevel:
+
 .. _default-geom-fromto:
 
 .. _default-geom-axisangle:

doc/XMLschema.rst

@@ -908,6 +908,9 @@
             .. grid-item::
                :ref:`gap<body-geom-gap>`
 
+            .. grid-item::
+               :ref:`surfacevel<body-geom-surfacevel>`
+
             .. grid-item::
                :ref:`fromto<body-geom-fromto>`
 
@@ -1373,6 +1376,9 @@
                .. grid-item::
                   :ref:`gap<composite-geom-gap>`
 
+               .. grid-item::
+                  :ref:`surfacevel<composite-geom-surfacevel>`
+
 
          .. dropdown:: :ref:`site<composite-site>` :octicon:`dot`
 
@@ -5492,6 +5498,9 @@
             .. grid-item::
                :ref:`gap<default-geom-gap>`
 
+            .. grid-item::
+               :ref:`surfacevel<default-geom-surfacevel>`
+
             .. grid-item::
                :ref:`fromto<default-geom-fromto>`
 

doc/changelog.rst

@@ -7,6 +7,19 @@ Upcoming version (not yet released)
 
 General
 ^^^^^^^
+.. youtube:: PdSdrqhSiZA
+   :align: right
+   :width: 35%
+
+- Added :ref:`geom/surfacevel<body-geom-surfacevel>`: the velocity of a geom's surface as seen by contacts, given as
+  a velocity field with a constant component and a rotational component about the geom frame origin. This allows
+  conveyor belts, treadmills and turntables to be modeled with static geoms and no degrees of freedom: friction
+  drives touching bodies toward the motion of the surface, with the field projected onto each contact's tangent
+  plane. Surface velocities compose correctly with each other and with body motion.
+  Note that the contact rows of ``mjData.efc_vel``, and the constraint-state sensors that read them, report the
+  velocity relative to the moving surface rather than to the geom, since that is the quantity the constraint acts
+  on; for geoms without :at:`surfacevel` the two are identical. Contact-point visualization draws an arrow along the
+  surface velocity at contacts with moving surfaces.
 - Replaced midpoint integration of free bodies with :ref:`gyroscopic derivatives<geFreeBody>` in the ``implicitfast``
   :ref:`integrator<geIntegrators>`: the bias-force derivative of every standalone free body is applied via a local
   unsymmetric solve of its decoupled block, making ``implicitfast`` identical to ``implicit`` for such bodies.

doc/computation/index.rst

@@ -1531,7 +1531,11 @@ Recall that :math:`r` is the position residual, while :math:`J v` is the joint v
 the indexing notation refers to one component of the projected velocity vector. For friction loss and friction
 dimensions of elliptic cones, :math:`r \equiv 0` and therefore :math:`k=0`, so the reference acceleration reduces to
 pure damping: :math:`\ari = -b_i (J v)_i`. More detail is given in the :ref:`Friction<CSolverFriction>` section of the
-Modeling chapter.
+Modeling chapter. For the tangential rows of contacts whose geoms specify a
+:ref:`surface velocity<body-geom-surfacevel>`, the projected velocity :math:`(J v)_i` is biased by the relative
+velocity of the surface material, so that the reference acceleration drives the contact toward moving *with* the
+surface; this is how conveyor belts and turntables are implemented, and it is also the quantity reported in the
+contact rows of ``mjData.efc_vel``.
 
 To summarize, the constraint behavior is determined by three per-constraint quantities: impedance :math:`0<d<1`, damping
 :math:`b > 0`, and stiffness :math:`k \geq 0`. These are computed from the :at:`solimp` and :at:`solref` attributes as

doc/includes/references.h

@@ -661,6 +661,7 @@ typedef struct mjModel_ {
   mjtSize nnames_map;             // number of slots in the names hash map
   mjtSize nJmom;                  // number of non-zeros in sparse actuator_moment matrix
   mjtSize ngravcomp;              // number of bodies with nonzero gravcomp
+  mjtSize nsurfacevel;            // number of geoms with nonzero surfacevel
   mjtSize nemax;                  // number of potential equality-constraint rows
   mjtSize njmax;                  // number of available rows in constraint Jacobian (legacy)
   mjtSize nconmax;                // number of potential contacts in contact list (legacy)
@@ -801,6 +802,7 @@ typedef struct mjModel_ {
   mjtNum*   geom_friction;        // friction for (slide, spin, roll)         (ngeom x 3)
   mjtNum*   geom_margin;          // geometric inflation for contact          (ngeom x 1)
   mjtNum*   geom_gap;             // additional contact detection buffer      (ngeom x 1)
+  mjtNum*   geom_surfacevel;      // surface velocity in local frame: lin,ang (ngeom x 6)
   mjtNum*   geom_fluid;           // fluid interaction parameters             (ngeom x mjNFLUID)
   mjtNum*   geom_user;            // user data                                (ngeom x nuser_geom)
   float*    geom_rgba;            // rgba when material is omitted            (ngeom x 4)
@@ -1895,6 +1897,7 @@ typedef struct mjsGeom_ {          // geom specification
   mjtNum solimp[mjNIMP];           // solver impedance
   double margin;                   // margin for contact detection
   double gap;                      // additional contact detection buffer
+  double surfacevel[6];            // surface velocity in local frame: linear, angular
 
   // inertia inference
   double mass;                     // used to compute density

doc/programming/simulation.rst

@@ -723,6 +723,10 @@ Exceptions to the general rule that **real-valued** types **are safe to change**
    * - ``geom_pos`` |br| ``geom_quat`` |br| ``geom_size`` |br| ``geom_rbound`` |br| ``geom_aabb``
      - Unsafe.
      -
+   * - ``geom_surfacevel``
+     - Safe.
+     - If the number of geoms with nonzero surface velocity is changed from zero to non-zero (or vice versa),
+       :ref:`mj_setConst` must be called.
    * - ``{site,cam,light}_`` |br| ``{pos,quat}``
      - Mostly safe.
      - For cameras and lights with tracking or targeting, :ref:`mj_setConst` is required.