DOCSEARCHbyAlgolia
Submit Docs

Pinocchio Rigid Multi-body Dynamics Library

repository·devel·Indexed 25 days ago

https://github.com/stack-of-tasks/pinocchio

A high-performance C++ library for efficient Rigid Multi-body Dynamics computations, widely used in robotics for kinematics, dynamics, and optimization. It provides analytical derivatives for gradient-based control, supports URDF, SDF, MJCF, and SRDF formats, and integrates with Automatic Differentiation frameworks like CppAD and CasADi. Pinocchio includes Python bindings and supports various visualizers such as MeshCat, Gepetto Viewer, Panda3d, RViz, and Viser.

Tokens
27.8K
Snippets
57
Records
136
Agent score
84%

What's inside Pinocchio

  1. Overview of Pinocchio features

    devel

    Pinocchio is a high-performance C++ library for Rigid Multi-body Dynamics.

    Key Capabilities:

    • Dynamics Algorithms: Forward/inverse kinematics and dynamics, centroidal dynamics, and kinematic/dynamic regressors. All include analytical derivatives.
    • Advanced Mechanics: Support for closed-loop mechanisms, frictional contact solvers, and sparse constrained dynamics.
    • Supported Formats: URDF, SDF, MJCF, and SRDF, as well as programmatic model construction.
    • Optimization Support: Integration with Automatic Differentiation frameworks like CppAD and CasADi, and automatic code generation via CppADCodeGen.
    • Performance: C++ template library that is cache-friendly and supports custom scalar types.

  2. Understand Pinocchio's spatial algebra notation

    devel
    Pinocchio uses spatial algebra to represent and manipulate physical quantities in rigid body dynamics. This notation is implemented through dedicated classes for 3D Euclidean space transformations and spatial vectors. Use these classes for efficient calculations involving velocities, accelerations, forces, and inertias.

  3. Pinocchio directory structure for joint development

    devel

    When implementing a new joint, you will primarily interact with the following directory structure:

    • include/pinocchio/multibody/joint/: Core joint implementation (C++ headers). Your new joint header (e.g., joint-<name>.hpp) goes here.
    • include/pinocchio/parsers/graph/: Graph integration for URDF support.
    • src/parsers/graph/: Graph visitor implementations (C++ source files).
    • bindings/python/: Python bindings for exposing joints to Python users.
    • unittest/: Unit tests. Create unittest/joint-<name>.cpp for your joint tests.
    • examples/: Usage examples. Create <name>-joint-kinematics.py for your examples.
    pinocchio/
├── include/pinocchio/
│   ├── multibody/
│   │   ├── joint/
│   │   │   ├── fwd.hpp
│   │   │   ├── joints.hpp
│   │   │   ├── joint-collection.hpp
│   │   │   ├── joint-revolute.hpp
│   │   │   ├── joint-spherical-ZYX.hpp
│   │   │   └── joint-<name>.hpp         # Your new joint goes here
│   │   ├── model.hpp
│   │   └── data.hpp
│   ├── parsers/
│   │   └── graph/
│   │       ├── joints.hpp
│   │       ├── graph-visitor.hpp
│   │       └── model-configuration-converter.hxx
│   └── serialization/
│       ├── joints-model.hpp
│       └── joints-data.hpp
├── src/
│   └── parsers/
│       └── graph/
│           ├── model-graph.cpp
│           └── model-graph-algo.cpp
├── bindings/python/
│   ├── multibody/joint/
│   │   ├── joints-models.hpp
│   │   └── joints-datas.hpp
│   └── parsers/graph/
│       └── expose-edges.cpp
├── unittest/
│   ├── joint-<name>.cpp                 # Your joint tests go here
│   ├── model-graph.cpp
│   ├── model-configuration-converter.cpp
│   └── CMakeLists.txt
└── examples/
    └── <name>-joint-kinematics.py       # Your example goes here

  4. Understand the Model and Data separation paradigm

    devel

    Pinocchio enforces a strict separation between the physical description of a robot (model) and the results of computations (data).

    • Model: Contains the physical description (kinematic and inertial parameters). Once created, the model object is immutable and is never modified by Pinocchio algorithms.
    • Data: Contains values resulting from computations (e.g., link velocities, accelerations) and intermediate results used to prevent memory allocation during algorithm execution. Data varies depending on the system's state (configuration, velocity, etc.).

    This separation allows for efficient parallel computation: multiple processes can share a single model object while each maintains its own unique data object.

  5. Understand Joint Geometry and Lie Algebra representations

    devel

    Pinocchio uses Lie algebra to describe joint geometry, facilitating the handling of different joint types. Each joint type is characterized by a movement matrix (Mat_{move}) and a constraint matrix (Mat_{cons}) in a landmark related to the joint itself.

    Supported joint geometries include:

    • Revolute: $SO(2)$ object.
    • Cylindrical: 2 degrees of freedom (rotation and translation).
    • Spherical: $SO(3)$ object (3 rotations).
    • Planar: $SE(2)$ object (2 translations, 1 rotation).
    • Free-floating: $SE(3)$ object (6 degrees of freedom).
    • Prismatic: 1 degree of freedom (translation only).
    • Translation: 3 degrees of freedom (3D translation only).

  6. Understand the geometric groups $SO(n)$ and $SE(n)$

    devel

    Pinocchio models rigid body systems using specific mathematical groups:

    • $SO(n)$ (Special Orthogonal group): Represents rotations.
      • $SO(3)$: Rotations in 3D space (3x3 matrices).
      • $SO(2)$: Rotations in 2D space (2x2 matrices), useful for planar problems.
    • $SE(n)$ (Special Euclidean group): Represents homogeneous transformations (rotations combined with translations).
      • $SE(3)$: 3D transformations.
      • $SE(2)$: 2D transformations in a plane.

    A rigid body system is composed of joints (which define kinematic relations/displacements), rigid bodies, and forces.

  8. Define geometric and collision models

    devel

    Pinocchio allows you to define a geometric model consisting of volumes attached to the kinematic tree. This model is used for robot visualization and computing collision-related quantities.

    Key components include:

    • GeometricModel: An object that stores fixed quantities, such as the placement and shape of the volumes.
    • Coal library: Pinocchio uses the coal library to represent volumes.
    • Attachment points: Robot bodies are attached to each joint, while environmental obstacles are defined in the world frame.
    • Collision/Distance algorithms: Pinocchio implements collision and distance algorithms for kinematic trees by leveraging coal methods.

  9. Supported Visualizers for Pinocchio

    devel

    Pinocchio supports several open-source visualizers for different workflows:

    • Gepetto Viewer: A C++ viewer based on OpenSceneGraph with Python bindings and Blender export.
    • Meshcat: Browser-based visualization supporting Python.
    • Panda3d: Browser-based visualization supporting Python.
    • RViz: ROS-integrated visualization supporting Python.
    • Viser: Browser-based visualization in Python with support for interactive widgets like sliders and markers.

    Custom external viewers can also be integrated by following the base_visualizer.py pattern.

  10. Understand supported joint types in Pinocchio

    devel

    Pinocchio represents robots as kinematic trees composed of joints. A joint can have one or several degrees of freedom (DOF) and falls into one of the following categories:

    • Revolute: Rotates around a fixed axis (X, Y, Z, or custom).
    • Prismatic: Translates along a fixed axis.
    • Spherical: Free rotations in 3D space.
    • Spherical ZYX: Free rotations parameterized by ZYX Euler angles.
    • Ellipsoid: Constrains motion to an ellipsoid surface (3-DOF: 2 rotations + 1 spin), primarily used in biomechanics.
    • Translation: Free translations in 3D space.
    • Planar: Free movements in 2D space.
    • Free-floating: Free movements in 3D space (used as the basis for mobile robots like humanoids or automated vehicles).
    • Composite: A collection of ordinary joints used to create more complex joint behaviors.

    Note on Fixed Joints: While URDF files may define fixed joints, Pinocchio treats them as operational frames rather than actual joints to improve computational efficiency.

  11. Understand Pinocchio Header Structure

    devel

    Pinocchio uses two types of headers to prevent include cycles:

    1. Public headers (.hpp): Located in include/pinocchio. These are standalone and include all necessary dependencies. They are used to expose private headers and functionality.
    2. Private headers (.hxx): Located in include/pinocchio/src. Private headers must not include any other headers to avoid dependency cycles. They rely on public headers to include their dependencies.

    To ensure Language Server Protocol (LSP) support works correctly on private headers, use the PINOCCHIO_LSP guard pattern.

  12. Overview of Policy Learning algorithms in Pinocchio

    devel

    The tutorial covers several methods for solving optimal control problems (OCP) via policy learning:

    1. Optimal Trajectory Optimization: Optimizes a single trajectory (initial state $x_0$ and piecewise-constant control vector $U$) to minimize the integral cost.
    2. Q-table (Discrete): Uses a table of $NX imes NU$ values to store the likelihood of reward for state-action pairs, optimized via back-propagation (e.g., Dijkstra) along random roll-outs.
    3. Q-table with Linear Net: Approximates the Q-value for continuous models using a deep neural network to represent the Q-table coefficients.
    4. Actor-Critic Network: Uses two networks (Actor for policy $\Pi(x)$ and Critic for Q-function $Q(x, u)$) optimized to minimize the HJB equation residual using batch sampling and target network regularization.
    5. OCP-Guided Training: Uses trajectories computed by an OCP solver to initialize the replay memory for neural network training.