Introduce mjPreContact, a minimal struct passed into the collision functions.

PiperOrigin-RevId: 918533795
Change-Id: I2b5af05c1479b25d5c2cfdc690321a26fce6ede6

Author: kbayes

doc/APIreference/APItypes.rst

@@ -936,6 +936,15 @@ MJCF element :ref:`statistic <statistic>`. One instance of it is embedded in mjM
 .. mujoco-include:: mjStatistic
 
 
+.. _mjPreContact:
+
+mjPreContact
+~~~~~~~~~~~~
+
+This is the data structure holding information about one contact filled out by a narrowphase collision detector.
+
+.. mujoco-include:: mjPreContact
+
 .. _mjContact:
 
 mjContact
@@ -1780,7 +1789,7 @@ mjfCollision
 .. code-block:: C
 
    typedef int (*mjfCollision)(const mjModel* m, const mjData* d,
-                               mjContact* con, int g1, int g2, mjtNum margin);
+                               mjPreContact* con, int g1, int g2, mjtNum margin);
 
 This is the function type of the callbacks in the collision table :ref:`mjCOLLISIONFUNC`.
 

doc/changelog.rst

@@ -70,6 +70,9 @@ General
      Negative ``margin`` values are now permitted (corresponding to ``gap > margin`` under the old semantics). The
      constraint ``margin + gap >= 0`` should be maintained to ensure valid collision detection.
 
+   - The :ref:`mjfCollision` functions now populate the :ref:`mjPreContact` struct instead of the :ref:`mjContact`
+     struct. The :ref:`mjPreContact` only contains the necessary fields needed for the narrowphase collision detection.
+
    - MJX: Removed the deprecated ``nconmax`` argument from ``mjx.make_data`` and ``mjx.put_data`` in favor of
      ``naconmax``.
 

doc/includes/references.h

@@ -101,8 +101,15 @@ typedef enum mjtSleepState_ {       // sleep state of an object
   mjS_ASLEEP = 0,                   // object is asleep
   mjS_AWAKE  = 1                    // object is awake
 } mjtSleepState;
+struct mjPreContact_ {             // contact parameters set by narrowphase collision functions
+  mjtNum dist;
+  mjtNum pos[3];
+  mjtNum normal[3];                // contact normal of the collision
+  mjtNum tangent[3];               // first tangent direction
+};
+typedef struct mjPreContact_ mjPreContact;
 struct mjContact_ {                // result of collision detection functions
-  // contact parameters set by near-phase collision function
+  // contact parameters set by narrowphase collision function
   mjtNum  dist;                    // distance between nearest points; neg: penetration
   mjtNum  pos[3];                  // position of contact point: midpoint between geoms
   mjtNum  frame[9];                // normal is in [0-2], points from geom[0] to geom[1]

include/mujoco/mjdata.h

@@ -121,10 +121,18 @@ typedef enum mjtSleepState_ {       // sleep state of an object
 } mjtSleepState;
 
 
-//---------------------------------- mjContact -----------------------------------------------------
+//------------------------------------- Contact ----------------------------------------------------
+
+struct mjPreContact_ {             // contact parameters set by narrowphase collision functions
+  mjtNum dist;
+  mjtNum pos[3];
+  mjtNum normal[3];                // contact normal of the collision
+  mjtNum tangent[3];               // first tangent direction
+};
+typedef struct mjPreContact_ mjPreContact;
 
 struct mjContact_ {                // result of collision detection functions
-  // contact parameters set by near-phase collision function
+  // contact parameters set by narrowphase collision function
   mjtNum  dist;                    // distance between nearest points; neg: penetration
   mjtNum  pos[3];                  // position of contact point: midpoint between geoms
   mjtNum  frame[9];                // normal is in [0-2], points from geom[0] to geom[1]
@@ -533,7 +541,7 @@ typedef mjtNum (*mjfTime)(void);
 typedef mjtNum (*mjfAct)(const mjModel* m, const mjData* d, int id);
 
 // collision detection
-typedef int (*mjfCollision)(const mjModel* m, mjData* d, mjContact* con, int g1, int g2,
+typedef int (*mjfCollision)(const mjModel* m, mjData* d, mjPreContact* con, int g1, int g2,
                             mjtNum margin);
 
 #endif  // MUJOCO_MJDATA_H_

python/mujoco/introspect/structs.py

@@ -5140,6 +5140,42 @@
              ),
          ),
      )),
+    ('mjPreContact',
+     StructDecl(
+         name='mjPreContact',
+         declname='struct mjPreContact_',
+         fields=(
+             StructFieldDecl(
+                 name='dist',
+                 type=ValueType(name='mjtNum'),
+                 doc='',
+             ),
+             StructFieldDecl(
+                 name='pos',
+                 type=ArrayType(
+                     inner_type=ValueType(name='mjtNum'),
+                     extents=(3,),
+                 ),
+                 doc='',
+             ),
+             StructFieldDecl(
+                 name='normal',
+                 type=ArrayType(
+                     inner_type=ValueType(name='mjtNum'),
+                     extents=(3,),
+                 ),
+                 doc='contact normal of the collision',
+             ),
+             StructFieldDecl(
+                 name='tangent',
+                 type=ArrayType(
+                     inner_type=ValueType(name='mjtNum'),
+                     extents=(3,),
+                 ),
+                 doc='first tangent direction',
+             ),
+         ),
+     )),
     ('mjContact',
      StructDecl(
          name='mjContact',

python/mujoco/raw.h

@@ -25,6 +25,7 @@
 // to them under the "raw" namespace.
 namespace mujoco::raw {
 
+using MjPreContact = ::mjPreContact;
 using MjContact = ::mjContact;
 using MjData = ::mjData;
 using MjLROpt = ::mjLROpt;

python/mujoco/structs.cc

@@ -615,6 +615,32 @@ This is useful for example when the MJB is not available as a file on disk.)"));
   X(int, nupdate);
 #undef X
 
+  // ==================== MJPRECONTACT ==========================================
+  py::class_<MjPreContactWrapper> mjPreContact(m, "MjPreContact");
+  mjPreContact.def(py::init<>());
+  mjPreContact.def("__copy__", [](const MjPreContactWrapper& self) {
+    return MjPreContactWrapper(self);
+  });
+  mjPreContact.def("__deepcopy__", [](const MjPreContactWrapper& self, py::dict) {
+    return MjPreContactWrapper(self);
+  });
+  DefineStructFunctions(mjPreContact);
+
+#define X(var)                                                           \
+  mjPreContact.def_property(                                             \
+      #var, [](const MjPreContactWrapper& c) { return c.get()->var; },   \
+      [](MjPreContactWrapper& c, decltype(raw::MjPreContact::var) rhs) { \
+        c.get()->var = rhs;                                              \
+      })
+  X(dist);
+#undef X
+
+#define X(var) DefinePyArray(mjPreContact, #var, &MjPreContactWrapper::var)
+  X(pos);
+  X(normal);
+  X(tangent);
+#undef X
+
   // ==================== MJCONTACT ============================================
   py::class_<MjContactWrapper> mjContact(m, "MjContact");
   mjContact.def(py::init<>());

python/mujoco/structs.h

@@ -547,6 +547,27 @@ template <>
 struct enable_if_mj_struct<raw::MjModel> { using type = void; };
 
 // ==================== MJCONTACT ==============================================
+template <>
+class MjWrapper<raw::MjPreContact> : public WrapperBase<raw::MjPreContact> {
+ public:
+  MjWrapper();
+  MjWrapper(const MjWrapper&);
+  MjWrapper(MjWrapper&&) = default;
+  MjWrapper(raw::MjPreContact* ptr, pybind11::handle owner);
+  ~MjWrapper() = default;
+
+  #define X(var)                                                     \
+    py_array_or_tuple_t<                                             \
+        std::remove_all_extents_t<decltype(raw::MjPreContact::var)>> \
+        var
+  X(pos);
+  X(normal);
+  X(tangent);
+  #undef X
+};
+
+using MjPreContactWrapper = MjWrapper<raw::MjPreContact>;
+
 template <>
 class MjWrapper<raw::MjContact> : public WrapperBase<raw::MjContact> {
  public:
@@ -961,6 +982,7 @@ using _impl::MjSolverStatWrapper;
 using _impl::MjModelWrapper;
 using _impl::MjDataWrapper;
 using _impl::MjContactWrapper;
+using _impl::MjPreContactWrapper;
 using _impl::MjvPerturbWrapper;
 using _impl::MjvCameraWrapper;
 using _impl::MjvGLCameraWrapper;

python/mujoco/structs_wrappers.cc

@@ -535,6 +535,26 @@ std::unique_ptr<MjModelWrapper> MjModelWrapper::Deserialize(
   return std::unique_ptr<MjModelWrapper>(new MjModelWrapper(model));
 }
 
+// ==================== MJPRECONTACT ==========================================
+#define X(var) var(InitPyArray(ptr_->var, owner_))
+MjPreContactWrapper::MjWrapper()
+    : WrapperBase(new raw::MjPreContact{}),
+      X(pos),
+      X(normal),
+      X(tangent) {}
+
+MjPreContactWrapper::MjWrapper(raw::MjPreContact* ptr, py::handle owner)
+    : WrapperBase(ptr, owner),
+      X(pos),
+      X(normal),
+      X(tangent) {}
+#undef X
+
+MjPreContactWrapper::MjWrapper(const MjPreContactWrapper& other)
+    : MjPreContactWrapper() {
+  *this->ptr_ = *other.ptr_;
+}
+
 // ==================== MJCONTACT ==============================================
 #define X(var) var(InitPyArray(ptr_->var, owner_))
 MjContactWrapper::MjWrapper()