From ec907d99d7586bbd09d604841ff8e405d7929914 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Caron?= Date: Fri, 6 Sep 2024 16:20:42 +0200 Subject: [PATCH] doc: Move content from intro.md to existing Features page --- doc/a-features/a-spatial.md | 11 +- doc/a-features/b-model-data.md | 32 +++- doc/a-features/c-joints.md | 38 +++- doc/a-features/d-model.md | 12 +- doc/a-features/e-lie.md | 3 +- doc/a-features/f-kinematic.md | 16 +- doc/a-features/g-dynamic.md | 32 +++- doc/a-features/h-frames.md | 5 +- doc/a-features/i-geometric-models.md | 3 - doc/a-features/intro.md | 180 ------------------ doc/a-features/j-analytical-derivatives.md | 9 +- doc/a-features/k-automatic-differentiation.md | 18 +- doc/a-features/l-python.md | 4 +- doc/a-features/m-tests.md | 4 +- doc/c-maths/a-rigid-bodies.md | 2 +- doc/treeview.dox | 1 - 16 files changed, 166 insertions(+), 204 deletions(-) delete mode 100644 doc/a-features/i-geometric-models.md delete mode 100644 doc/a-features/intro.md diff --git a/doc/a-features/a-spatial.md b/doc/a-features/a-spatial.md index 5ed59fd740..abacf6b4d8 100644 --- a/doc/a-features/a-spatial.md +++ b/doc/a-features/a-spatial.md @@ -1 +1,10 @@ -# Spatial Algebra module +\page md_doc_a-features_a-spatial Spatial algebra + +Spatial algebra is a mathematical notation commonly employed in rigid body +dynamics to represent and manipulate physical quantities such as velocities, +accelerations and forces. Pinocchio is based on this mathematical notation. +Dedicated classes are provided to represent coordinate transformations in the +3D Euclidean space (named SE3), spatial motion vectors (Motion), spatial force +vectors (Force), and spatial inertias (Inertia). Along with the available +methods, this endows Pinocchio with an efficient software library for spatial +algebra calculations. diff --git a/doc/a-features/b-model-data.md b/doc/a-features/b-model-data.md index a96484162a..2f4385d3ff 100644 --- a/doc/a-features/b-model-data.md +++ b/doc/a-features/b-model-data.md @@ -1,5 +1,29 @@ -# Model and data +\page md_doc_a-features_b-model-data Model and data -TODO: just explain the concept of model and data and what they contain. The explanation on how to build and/or load a -model is delayed to the two following pages (explicitely say so from the start). Just use -buildModels::humanoid(model) in the snippets [pending v2.0] +A fundamental paradigm of Pinocchio is the strict separation between +*model* and *data*. By *model*, we mean the physical description of the +robot, including kinematic and possibly inertial parameters defining its +structure. This information is held by a dedicated class which, once +created, is never modified by the algorithms of Pinocchio. By *data*, we +mean all values which are the result of a computation. *Data* vary +according to the joint configuration, velocity, etc\... of the system. +It contains for instance the velocity and the acceleration of each link. +It also stores intermediate computations and final results of the +algorithms in order to prevent memory allocation. With this splitting, +all the algorithms in Pinocchio follow the signature: + +``` +algorithm(model, data, arg1, arg2, ...) +``` + +where `arg1, arg2, ...` are the arguments of the function (e.g. configuration or +velocity). Keeping model and data separated reduces memory footprint +when performing several different tasks on the same robot, notably when +this involves parallel computation. Each process can employ its own data +object, while sharing the same model object. The fact that a model +object never changes within an algorithm of Pinocchio enhances the +predictability of the code. + +A model can be created using the C++ API or loaded from an external +file, which can be either URDF, Lua (following the RBDL standard) or +Python. diff --git a/doc/a-features/c-joints.md b/doc/a-features/c-joints.md index 834dcb05d6..72e7772ea3 100644 --- a/doc/a-features/c-joints.md +++ b/doc/a-features/c-joints.md @@ -1,4 +1,36 @@ -# Joints +\page md_doc_a-features_c-joints Joints -TODO: Or: Building the model: joints and bodies. Maybe merge this section with previous one? - @nmansard : I prefer this way of separing models of joint models. +Within a model, a robot is represented as a kinematic tree, containing a +collection of all the joints, information about their connectivity, and, +optionally, the inertial quantities associated to each link. In +Pinocchio a joint can have one or several degrees of freedom, and it +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; +- **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 + employed as the basis of kinematic tree of mobile robots (humanoids, automated vehicles, or objects in manipulation + planning). +- More complex joints can be created as a collection of ordinary ones through the concept of **Composite** joint. + +Remark: In the URDF format, a joint of type *fixed* can be defined. However, +a **fixed** joint is not really a joint because it cannot move. +For efficiency reasons, it is therefore treated as operational frame of the model. + +## From joints to Lie-group geometry + +Each type of joints is characterized by its own specific configuration +and tangent spaces. For instance, the configuration and tangent spaces +of a revolute joint are both the real axis line \f$\mathbb{R}\f$, while for +a Spherical joint the configuration space corresponds to the set of +rotation matrices of dimension 3 and its tangent space is the space of +3-dimensional real vectors \f$\mathbb{R}^{3}\f$. Some configuration spaces +might not behave as a vector space, but have to be endowed with the +corresponding integration (exp) and differentiation (log) operators. +Pinocchio implements all these specific integration and differentiation +operators. + +See \ref md_doc_a-features_e-lie to go further on this topic. diff --git a/doc/a-features/d-model.md b/doc/a-features/d-model.md index e4562c289c..9c4e731fd9 100644 --- a/doc/a-features/d-model.md +++ b/doc/a-features/d-model.md @@ -1 +1,11 @@ -# Loading the model +\page md_doc_a-features_d-model Geometric and collision models + +Aside from the kinematic model, Pinocchio defines a geometric model, i.e. the +volumes attached to the kinematic tree. This model can be used for displaying +the robot and computing quantities associated to collisions. Like the kinematic +model, the fixed quantities (placement and shape of the volumes) are stored in +a *GeometricModel* object, while buffers and quantities used by associated +algorithms are defined in an object. The volumes are represented using the FCL +library. Bodies of the robot are attached to each joint, while obstacles of the +environment are defined in the world frame. Collision and distance algorithms +for the kinematic trees are implemented, based on FCL methods. diff --git a/doc/a-features/e-lie.md b/doc/a-features/e-lie.md index 319c65eaed..5b97b3701a 100644 --- a/doc/a-features/e-lie.md +++ b/doc/a-features/e-lie.md @@ -1,5 +1,4 @@ - -# Dealing with Lie group geometry {#e-lie} +\page md_doc_a-features_e-lie Dealing with Lie-group geometry Pinocchio relies heavily on Lie groups and Lie algebras to handle motions and more specifically rotations. For this reason it supports the following special groups \\( SO(2), SO(3), SE(2), SE(3) \\) and implements their associated algebras diff --git a/doc/a-features/f-kinematic.md b/doc/a-features/f-kinematic.md index 3b02d43079..2086f11cd9 100644 --- a/doc/a-features/f-kinematic.md +++ b/doc/a-features/f-kinematic.md @@ -1 +1,15 @@ -# Kinematic algorithms +\page md_doc_a-features_f-kinematic Kinematics algorithms + +## Forward kinematics + +Pinocchio implements direct kinematic computations up to the second +order. When a robot configuration is given, a forward pass is performed +to compute the spatial placements of each joint and to store them as +coordinate transformations. If the velocity is given, it also computes +the spatial velocities of each joint (expressed in local frame), and +similarly for accelerations. + +## Kinematic Jacobian + +The spatial Jacobian of each joint can be easily computed with a single +forward pass, either expressed locally or in the world frame. diff --git a/doc/a-features/g-dynamic.md b/doc/a-features/g-dynamic.md index fdb8809072..a25d46975c 100644 --- a/doc/a-features/g-dynamic.md +++ b/doc/a-features/g-dynamic.md @@ -1 +1,31 @@ -# Dynamic algorithms +\page md_doc_a-features_g-dynamic Dynamics algorithms + +## Inverse dynamics + +The Recursive Newton-Euler Algorithm (RNEA) computes the inverse dynamics: +given a desired robot configuration, velocity and acceleration, the torques +required to execute this motion are computed and stored. The algorithm first +performs a forward pass (equivalent to second-order kinematics). It then +performs a backward pass, computing the wrenches transmitted along the +structure and extracting the joint torques needed to obtain the computed link +motions. With the appropriate inputs, this algorithm can also be employed to +compute specific terms of the dynamic model, such as the gravity effects. + +## Joint-space inertia matrix + +The Composite Rigid Body Algorithm (CRBA) is employed to compute the joint +space inertia matrix of the robot. We have implemented some slight +modifications of the original algorithm that improve the computational +efficiency. + +## Forward dynamics + +The Articulated Body Algorithm (ABA) computes the unconstrained forward +dynamics: given a robot configuration, velocity, torque and external forces, +the resulting joint accelerations are computed. + +## Additional algorithms + +Beside the algorithms above, other methods are provided, most notably for +constrained forward dynamics, impulse dynamics, inverse of the joint space +inertia and centroidal dynamics. diff --git a/doc/a-features/h-frames.md b/doc/a-features/h-frames.md index 1ab8357ae9..0fd4b9fbdc 100644 --- a/doc/a-features/h-frames.md +++ b/doc/a-features/h-frames.md @@ -1,4 +1,5 @@ -# Operational frames +\page md_doc_a-features_h-frames Operational frames -TODO: as frames are not necessary to understand the previous sections, it could be a good idea to treat them +TODO: as frames are not necessary to understand the previous sections, it could +be a good idea to treat them separately. Introduce them here together with the related algorithms. diff --git a/doc/a-features/i-geometric-models.md b/doc/a-features/i-geometric-models.md deleted file mode 100644 index 5bcd2c53b9..0000000000 --- a/doc/a-features/i-geometric-models.md +++ /dev/null @@ -1,3 +0,0 @@ -# Geometric models - -TODO: with related algos diff --git a/doc/a-features/intro.md b/doc/a-features/intro.md deleted file mode 100644 index e866201af4..0000000000 --- a/doc/a-features/intro.md +++ /dev/null @@ -1,180 +0,0 @@ -# Main features of Pinocchio - -Pinocchio has been written in C++ for efficiency reasons and uses the -Eigen library for linear algebra routines. It comes with -Python bindings for easy code prototyping. We describe here the main -features implemented in Pinocchio. - -## Spatial algebra - -Spatial algebra is a mathematical notation -commonly employed in rigid body dynamics to represent and manipulate -physical quantities such as velocities, accelerations and forces. -Pinocchio is based on this mathematical notation. Dedicated classes are -provided to represent coordinate transformations in the 3D Euclidean -space (named SE3), spatial motion vectors (Motion), spatial force -vectors (Force), and spatial inertias (Inertia). Along with the -available methods, this endows Pinocchio with an efficient software -library for spatial algebra calculations. - -## Model and data - -A fundamental paradigm of Pinocchio is the strict separation between -*model* and *data*. By *model*, we mean the physical description of the -robot, including kinematic and possibly inertial parameters defining its -structure. This information is held by a dedicated class which, once -created, is never modified by the algorithms of Pinocchio. By *data*, we -mean all values which are the result of a computation. *Data* vary -according to the joint configuration, velocity, etc\... of the system. -It contains for instance the velocity and the acceleration of each link. -It also stores intermediate computations and final results of the -algorithms in order to prevent memory allocation. With this splitting, -all the algorithms in Pinocchio follow the signature: - -``` -algorithm(model, data, arg1, arg2, ...) -``` - -where `arg1, arg2, ...` are the arguments of the function (e.g. configuration or -velocity). Keeping model and data separated reduces memory footprint -when performing several different tasks on the same robot, notably when -this involves parallel computation. Each process can employ its own data -object, while sharing the same model object. The fact that a model -object never changes within an algorithm of Pinocchio enhances the -predictability of the code. - -A model can be created using the C++ API or loaded from an external -file, which can be either URDF, Lua (following the RBDL standard) or -Python. - -## Supported kinematic models - -Within a model, a robot is represented as a kinematic tree, containing a -collection of all the joints, information about their connectivity, and, -optionally, the inertial quantities associated to each link. In -Pinocchio a joint can have one or several degrees of freedom, and it -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; -- **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 - employed as the basis of kinematic tree of mobile robots (humanoids, automated vehicles, or objects in manipulation - planning). -- More complex joints can be created as a collection of ordinary ones through the concept of **Composite** joint. - -Remark: In the URDF format, a joint of type *fixed* can be defined. However, -a **fixed** joint is not really a joint because it cannot move. -For efficiency reasons, it is therefore treated as operational frame of the model. - -## Dealing with Lie group geometry - -Each type of joints is characterized by its own specific configuration -and tangent spaces. For instance, the configuration and tangent spaces -of a revolute joint are both the real axis line \f$\mathbb{R}\f$, while for -a Spherical joint the configuration space corresponds to the set of -rotation matrices of dimension 3 and its tangent space is the space of -3-dimensional real vectors \f$\mathbb{R}^{3}\f$. Some configuration spaces -might not behave as a vector space, but have to be endowed with the -corresponding integration (exp) and differentiation (log) operators. -Pinocchio implements all these specific integration and differentiation -operators. - -## Geometric models - -Aside from the kinematic model, Pinocchio defines a geometric model, i.e. the -volumes attached to the kinematic tree. This model can be used for -displaying the robot and computing quantities associated to collisions. -Like the kinematic model, the fixed quantities (placement and shape of -the volumes) are stored in a *GeometricModel* object, while buffers and -quantities used by associated algorithms are defined in an object. The -volumes are represented using the FCL library. Bodies -of the robot are attached to each joint, while obstacles of the -environment are defined in the world frame. Collision and distance -algorithms for the kinematic trees are implemented, based on FCL -methods. - -## Main algorithms - -The implementation of the basic algorithms, including all those listed -in this section, is recursive. The recursive formulation allows the -software to avoid repeated computations and to exploit the sparsity -induced by the kinematic tree. For the dynamics algorithms, we largely -drew inspiration from Featherstone algorithms, with slight -improvements. - -### Forward kinematics - -Pinocchio implements direct kinematic computations up to the second -order. When a robot configuration is given, a forward pass is performed -to compute the spatial placements of each joint and to store them as -coordinate transformations. If the velocity is given, it also computes -the spatial velocities of each joint (expressed in local frame), and -similarly for accelerations. - -### Kinematic Jacobian - -the spatial Jacobian of each joint can be easily computed with a single -forward pass, either expressed locally or in the world frame. - -### Inverse dynamics - -the Recursive Newton-Euler Algorithm (RNEA) computes the -inverse dynamics: given a desired robot configuration, velocity and -acceleration, the torques required to execute this motion are computed -and stored. The algorithm first performs a forward pass (equivalent to -second-order kinematics). It then performs a backward pass, computing -the wrenches transmitted along the structure and extracting the joint -torques needed to obtain the computed link motions. With the appropriate -inputs, this algorithm can also be employed to compute specific terms of -the dynamic model, such as the gravity effects. - -### Joint space inertia matrix - -the Composite Rigid Body Algorithm (CRBA) is -employed to compute the joint space inertia matrix of the robot. We have -implemented some slight modifications of the original algorithm that -improve the computational efficiency. - -### Forward dynamics - -the Articulated Body Algorithm (ABA) -computes the unconstrained forward dynamics: given a robot -configuration, velocity, torque and external forces, the resulting joint -accelerations are computed. - -### Additional algorithms - -beside the algorithms above, other methods are provided, most notably -for constrained forward dynamics, impulse dynamics, inverse of the joint -space inertia and centroidal -dynamics. - -## Analytical derivatives - -Beside proposing standard forward and inverse dynamics algorithms, -Pinocchio also provides efficient implementations of their analytical -derivatives. These derivatives are for -instance of primary importance in the context of whole-body trajectory -optimization or more largely, for numerical optimal control. To the best -of our knowledge, Pinocchio is the first rigid body framework which -implements this feature natively. - -## Automatic differentiation and source code generation - -In addition to analytical derivatives, Pinocchio supports automatic -differentiation. This is made possible through the full *scalar* -templatization of the whole C++ code and the use of any external library -that does automatic differentiation: ADOL-C, CasADi, CppAD and others. It is -important to keep in mind that these automatic derivatives are often -much slower than the analytical ones. - -Another unique but central feature of Pinocchio is its ability to -generate code both at compile time and at runtime. This is achieved by -using another external toolbox called CppADCodeGen built on top of -CppAD. From any function using Pinocchio, CppADCodeGen is -able to generate on the fly its code in various languages: C, Latex, -etc. and to make some simplifications of the math expressions. Thanks to -this procedure, a code tailored for a specific robot model can be -generated and used externally to Pinocchio. diff --git a/doc/a-features/j-analytical-derivatives.md b/doc/a-features/j-analytical-derivatives.md index 03f027a31b..58bb7f65f2 100644 --- a/doc/a-features/j-analytical-derivatives.md +++ b/doc/a-features/j-analytical-derivatives.md @@ -1 +1,8 @@ -# Analytical derivatives +\page md_doc_a-features_j-analytical-derivatives Analytical derivatives + +Beside proposing standard forward and inverse dynamics algorithms, Pinocchio +also provides efficient implementations of their analytical derivatives. These +derivatives are for instance of primary importance in the context of whole-body +trajectory optimization or more largely, for numerical optimal control. To the +best of our knowledge, Pinocchio is the first rigid body framework which +implements this feature natively. diff --git a/doc/a-features/k-automatic-differentiation.md b/doc/a-features/k-automatic-differentiation.md index a0a913d5f9..28bd8efd04 100644 --- a/doc/a-features/k-automatic-differentiation.md +++ b/doc/a-features/k-automatic-differentiation.md @@ -1 +1,17 @@ -# Automatic differentiation and source code generation +\page md_doc_a-features_k-automatic-differentiation Automatic differentiation and source code generation + +In addition to analytical derivatives, Pinocchio supports automatic +differentiation. This is made possible through the full *scalar* +templatization of the whole C++ code and the use of any external library +that does automatic differentiation: ADOL-C, CasADi, CppAD and others. It is +important to keep in mind that these automatic derivatives are often +much slower than the analytical ones. + +Another unique but central feature of Pinocchio is its ability to +generate code both at compile time and at runtime. This is achieved by +using another external toolbox called CppADCodeGen built on top of +CppAD. From any function using Pinocchio, CppADCodeGen is +able to generate on the fly its code in various languages: C, Latex, +etc. and to make some simplifications of the math expressions. Thanks to +this procedure, a code tailored for a specific robot model can be +generated and used externally to Pinocchio. diff --git a/doc/a-features/l-python.md b/doc/a-features/l-python.md index e65ba6ef62..1bb71375a3 100644 --- a/doc/a-features/l-python.md +++ b/doc/a-features/l-python.md @@ -1 +1,3 @@ -# Python bindings +\page md_doc_a-features_l-python Python bindings + +TODO: ... diff --git a/doc/a-features/m-tests.md b/doc/a-features/m-tests.md index a0291f0699..4d4a19fb37 100644 --- a/doc/a-features/m-tests.md +++ b/doc/a-features/m-tests.md @@ -1 +1,3 @@ -# Unit tests +\page md_doc_a-features_m-tests Unit tests + +TODO: ... diff --git a/doc/c-maths/a-rigid-bodies.md b/doc/c-maths/a-rigid-bodies.md index 4bf2348b2e..f513380652 100644 --- a/doc/c-maths/a-rigid-bodies.md +++ b/doc/c-maths/a-rigid-bodies.md @@ -10,7 +10,7 @@ The set that brings together all the homogeneous transformations matrices is the ### Using quaternions for an SO(3) object -To use quaternions for a \f$ SO(3) \f$ object we have several methods, we can do as in the \f$ SE(3) \f$ example in the [Dealing with Lie group geometry](@ref e-lie) section by removing the translation vector. +To use quaternions for a \f$ SO(3) \f$ object we have several methods, we can do as in the \f$ SE(3) \f$ example in the [Dealing with Lie group geometry](@ref md_doc_a-features_e-lie) section by removing the translation vector. Or we can just consider one rotation instead of two. For example, in a landmark link to the robot itself, we consider the starting position as the origin of this landmark. diff --git a/doc/treeview.dox b/doc/treeview.dox index c64f8b00af..43b63a370d 100644 --- a/doc/treeview.dox +++ b/doc/treeview.dox @@ -26,7 +26,6 @@ namespace pinocchio { - \subpage md_doc_a-features_f-kinematic - \subpage md_doc_a-features_g-dynamic - \subpage md_doc_a-features_h-frames - - \subpage md_doc_a-features_i-geometric-models - \subpage md_doc_a-features_j-analytical-derivatives - \subpage md_doc_a-features_k-automatic-differentiation - \subpage md_doc_a-features_l-python