Merge pull request #2797 from Ipuch/topic-ellipsoid

Adding an ellipsoid joint to the joint collection

Author: jorisv

.github/workflows/macos-linux-windows-pixi.yml

@@ -29,6 +29,12 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  # This is needed on Windows because ellipsoid-joint-kinematics.py output
+  # some utf8 char.
+  # More detail here: https://gist.github.com/NodeJSmith/e7e37f2d3f162456869f015f842bcf15
+  PYTHONIOENCODING: "utf8"
+
 jobs:
   pinocchio-pixi:
     name: Standard - ${{ matrix.os }} - Env ${{ matrix.environment }} ${{ matrix.build_type }} ${{ matrix.compiler }}

CHANGELOG.md

@@ -18,6 +18,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Add names to joints that are inside a composite joint ([#2786](https://github.com/stack-of-tasks/pinocchio/pull/2786))
 - Add color support for robot meshes in Viser ([#2793](https://github.com/stack-of-tasks/pinocchio/pull/2793))
 - Add Realtime Sanitizer (RTSan) uniittest and CI to track dynamic allocations in main API ([#2809](https://github.com/stack-of-tasks/pinocchio/pull/2809))
+- Add Ellipsoid Joint (3-DOF surface constraint), get ready for biomechanics ([#2797](https://github.com/stack-of-tasks/pinocchio/pull/2797))
 
 ### Changed
 - Python version update ([#2802](https://github.com/stack-of-tasks/pinocchio/pull/2802)):
@@ -36,7 +37,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Removed
 - Remove CMake < 3.22 details ([#2790](https://github.com/stack-of-tasks/pinocchio/pull/2790))
 
-
 ## [3.8.0] - 2025-09-17
 
 ### Added

README.md

@@ -288,6 +288,8 @@ In addition to the core dev team, the following people have also been involved i
 -   [Lev Kozlov](https://github.com/lvjonok): Kinetic and potential energy regressors
 -   [Simeon Nedelchev](https://github.com/simeon-ned): Pseudo inertia and Log-Cholesky parametrization
 -   [Alexy Legrand](https://www.linkedin.com/in/alexy-legrand-125889232/): Viser color bug fixes
+-   [Pierre Puchaud](https://github.com/ipuch): Ellipsoid Joint
+-   [Lucas Joseph](https://github.com/LucasJoseph): Ellipsoid Joint
 
 If you have participated in the development of **Pinocchio**, please add your name and contribution to this list.
 

bindings/python/parsers/graph/expose-edges.cpp

@@ -36,6 +36,9 @@ namespace pinocchio
     const int JointSphericalZYX::nq;
     const int JointSphericalZYX::nv;
 
+    const int JointEllipsoid::nq;
+    const int JointEllipsoid::nv;
+
     const int JointTranslation::nq;
     const int JointTranslation::nv;
 
@@ -111,6 +114,20 @@ namespace pinocchio
         .def_readonly("nq", &JointSphericalZYX::nq, "Number of configuration variables.")
         .def_readonly("nv", &JointSphericalZYX::nv, "Number of tangent variables.");
 
+      bp::class_<JointEllipsoid>(
+        "JointEllipsoid", "Represents an ellipsoidal joint.",
+        bp::init<>(bp::args("self"), "Default constructor."))
+        .def(bp::init<double, double, double>(
+          bp::args("self", "radius_x", "radius_y", "radius_z"), "Constructor with radii."))
+        .def_readwrite(
+          "radius_x", &JointEllipsoid::radius_x, "Semi-axis length in the x direction.")
+        .def_readwrite(
+          "radius_y", &JointEllipsoid::radius_y, "Semi-axis length in the y direction.")
+        .def_readwrite(
+          "radius_z", &JointEllipsoid::radius_z, "Semi-axis length in the z direction.")
+        .def_readonly("nq", &JointEllipsoid::nq, "Number of configuration variables.")
+        .def_readonly("nv", &JointEllipsoid::nv, "Number of tangent variables.");
+
       bp::class_<JointTranslation>(
         "JointTranslation", "Represents a translation joint.",
         bp::init<>(bp::args("self"), "Default constructor."))

doc/a-features/c-joints.md

@@ -9,6 +9,12 @@ belongs to one of the following categories:
 - **Revolute** joints, rotating around a fixed axis, either one of \f$X,Y,Z\f$ or a custom one;
 - **Prismatic** joints, translating along any fixed axis, as in the revolute case;
 - **Spherical** joints, free rotations in the 3D space;
+- **Spherical ZYX** joints, free rotations parameterized by ZYX Euler angles;
+- **Ellipsoid** joints, constraining motion to an ellipsoid surface with 3-DOF (2 rotations + 1 spin),
+  useful for biomechanics. The translation follows the ellipsoid surface \f$\left(\frac{x}{a}\right)^2 + \left(\frac{y}{b}\right)^2 + \left(\frac{z}{c}\right)^2 = 1\f$,
+  while the rotational part uses the normal direction of an equivalent sphere.
+  This approximation is exact only when \f$a = b = c\f$ (spherical case).
+  See Seth et al., "Minimal formulation of joint motion for biomechanisms," Nonlinear Dynamics 62(1):291-303, 2010.
 - **Translation** joints, for free translations in the 3D space;
 - **Planar** joints, for free movements in the 2D space;
 - **Free-floating** joints, for free movements in the 3D space. Planar and free-floating joints are meant to be