README.md 8.76 KB
Newer Older
1
<p align="center">
2
  <img src="./doc/images/pinocchio-logo-large.png" width="800" alt="Pinocchio Logo" align="center"/>
3
</p>
Olivier Stasse's avatar
Olivier Stasse committed
4

5 6 7 8 9 10 11 12
<p align="center">
  <a href="https://opensource.org/licenses/BSD-2-Clause"><img src="https://img.shields.io/badge/License-BSD%202--Clause-green.svg" alt="License"/></a>
  <a href="https://travis-ci.org/stack-of-tasks/pinocchio"><img src="https://travis-ci.org/stack-of-tasks/pinocchio.svg?branch=master" alt="Build Status"/></a>
  <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/pinocchio/master/coverage/"><img src="https://gepgitlab.laas.fr/stack-of-tasks/pinocchio/badges/master/coverage.svg?job=doc-coverage" alt="Coverage Report"/></a>
  <a href="https://anaconda.org/conda-forge/pinocchio"><img src="https://img.shields.io/conda/dn/conda-forge/pinocchio.svg" alt="Conda Downloads"/></a>
  <a href="https://anaconda.org/conda-forge/pinocchio"><img src="https://img.shields.io/conda/vn/conda-forge/pinocchio.svg" alt="Conda Version"/></a>
  <a href="https://conda.anaconda.org/conda-forge"><img src="https://anaconda.org/conda-forge/pinocchio/badges/installer/conda.svg" alt="Anaconda-Server Badge"/></a>
</p>
Justin Carpentier's avatar
Justin Carpentier committed
13

14 15 16
<!--Pinocchio: a C++ library for efficient Rigid Multi-body Dynamics computations
===========
-->
Nicolas Mansard's avatar
Nicolas Mansard committed
17

18
**Pinocchio** instantiates the state-of-the-art Rigid Body Algorithms for poly-articulated systems based on revisited Roy Featherstone's algorithms.
Justin Carpentier's avatar
Justin Carpentier committed
19
Besides, **Pinocchio** provides the analytical derivatives of the main Rigid-Body Algorithms like the Recursive Newton-Euler Algorithm or the Articulated-Body Algorithm.
Justin Carpentier's avatar
Justin Carpentier committed
20

Justin Carpentier's avatar
Justin Carpentier committed
21
**Pinocchio** is first tailored for robotics applications, but it can be used in extra contexts (biomechanics, computer graphics, vision, etc.).
Justin Carpentier's avatar
Justin Carpentier committed
22
It is built upon Eigen for linear algebra and FCL for collision detection. **Pinocchio** comes with a Python interface for fast code prototyping, [directly accessible](https://github.com/conda-forge/pinocchio-feedstock#installing-pinocchio) through [Conda](https://docs.conda.io/en/latest/).
23

Justin Carpentier's avatar
Justin Carpentier committed
24
**Pinocchio** is now at the heart of various robotics softwares as [Crocoddyl](https://github.com/loco-3d/crocoddyl/tree/devel), an open-source and efficient Differential Dynamic Programming solver for robotics, the [Stack-of-Tasks](http://stack-of-tasks.github.io), an open-source and versatile hierarchical controller framework or the [Humanoid Path Planner](https://humanoid-path-planner.github.io/hpp-doc), an open-source software for Motion and Manipulation Planning. 
25

26 27
If you want to learn more on **Pinocchio** internal behaviors and main features, we invite you to read the related [paper](https://hal-laas.archives-ouvertes.fr/hal-01866228).

28 29 30 31 32 33 34 35
## Pinocchio features

**Pinocchio** is fast:

   - C++ template library,
   - cache friendly,
   - automatic code generation support.

Justin Carpentier's avatar
Justin Carpentier committed
36
**Pinocchio** is versatile, implementing basic and more advanced rigid body dynamics algorithms:
37

Justin Carpentier's avatar
Justin Carpentier committed
38 39
   - forward kinematics and its analytical derivatives,
   - forward/inverse dynamics and their analytical derivatives,
Justin Carpentier's avatar
Justin Carpentier committed
40
   - centroidal dynamics and its analytical derivatives,
41
   - and much more with the support of modern Automatic Differentiation frameworks like [CppAD](https://github.com/coin-or/CppAD) or [CasADi](https://web.casadi.org/).
Justin Carpentier's avatar
Justin Carpentier committed
42 43 44 45

**Pinocchio** is flexible:

   - header only,
Justin Carpentier's avatar
Justin Carpentier committed
46
   - C++ 98/03/11/14/17/20 compliant.
47

48
**Pinocchio** is extensible.  
49 50
**Pinocchio** is multi-thread friendly.  
**Pinocchio** is reliable and extensively tested (unit-tests, simulations and real robotics applications).  
Justin Carpentier's avatar
Justin Carpentier committed
51
**Pinocchio** is supported on Mac OS X and many Linux distributions ([see build status here](http://robotpkg.openrobots.org/rbulk/robotpkg/math/pinocchio/index.html)).
52

53 54
## Performances

Justin Carpentier's avatar
Justin Carpentier committed
55
**Pinocchio** exploits at best the sparsity induced by the kinematic tree of robotics systems. Thanks to modern programming language paradigms, **Pinocchio** is able to unroll most of the computations directly at compile time, allowing to achieve impressive performances for a large range of robots, as illustrated by the plot below, obtained on a standard laptop equipped with an Intel Core i7 CPU @ 2.4 GHz.
56 57 58 59 60

<p align="center">
  <img src="./doc/images/pinocchio-performances.png" width="600" alt="Pinocchio Logo" align="center"/>
</p>

Justin Carpentier's avatar
Justin Carpentier committed
61 62 63 64
## Ongoing developments

If you want to follow the current developments, you can directly refer to the [devel branch](https://github.com/stack-of-tasks/pinocchio/tree/devel).

Justin Carpentier's avatar
Justin Carpentier committed
65
## Installation
66

Justin Carpentier's avatar
Justin Carpentier committed
67
**Pinocchio** can be easily installed on various Linux (Ubuntu, Fedora, etc.) and Unix distributions (Mac OS X, BSD, etc.). Please refer to the [installation procedure](http://stack-of-tasks.github.io/pinocchio/download.html).
Nicolas Mansard's avatar
Nicolas Mansard committed
68

Justin Carpentier's avatar
Justin Carpentier committed
69 70
If you only need the Python bindings of Pinocchio, you may prefer to install it through [Conda](https://docs.conda.io/en/latest/). Please follow the procedure described [here](https://github.com/conda-forge/pinocchio-feedstock#installing-pinocchio).

71
**Pinocchio** is also deployed on ROS, you may follow its deployment status on [Melodic](https://index.ros.org/r/pinocchio/#melodic) or [Kinetic](https://index.ros.org/r/pinocchio/#kinetic).
72

73 74 75 76
## Documentation

The online **Pinocchio** documentation of the last release is available [here](https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/).

jcarpent's avatar
jcarpent committed
77 78
## Examples

79
We provide some basic examples on how to use **Pinocchio** in Python in the [examples/python](./examples/python) directory.
80
Additional examples introducing **Pinocchio** are also available in the [documentation](https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/md_doc_d-practical-exercises_intro.html)
jcarpent's avatar
jcarpent committed
81

82
## Tutorials
Justin Carpentier's avatar
Justin Carpentier committed
83

84 85
**Pinocchio** comes with a large bunch of tutorials aiming at introducing the basic tools for robotics control.
The content of the tutorials is described [here](https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/md_doc_d-practical-exercises_1-directgeom.html).
Justin Carpentier's avatar
Justin Carpentier committed
86

Justin Carpentier's avatar
Justin Carpentier committed
87 88
## Citing Pinocchio

Justin Carpentier's avatar
Justin Carpentier committed
89
To cite **Pinocchio** in your academic research, please use the following bibtex lines:
Justin Carpentier's avatar
Justin Carpentier committed
90 91
```
@misc{pinocchioweb,
Justin Carpentier's avatar
Justin Carpentier committed
92 93 94 95 96
   author = {Justin Carpentier and Florian Valenza and Nicolas Mansard and others},
   title = {Pinocchio: fast forward and inverse dynamics for poly-articulated systems},
   howpublished = {https://stack-of-tasks.github.io/pinocchio},
   year = {2015--2019}
}
Justin Carpentier's avatar
Justin Carpentier committed
97
```
98
and the following one for the reference to the paper introducing **Pinocchio**:
99 100
```
@inproceedings{carpentier2019pinocchio,
Justin Carpentier's avatar
Justin Carpentier committed
101 102 103 104
   title={The Pinocchio C++ library -- A fast and flexible implementation of rigid body dynamics algorithms and their analytical derivatives},
   author={Carpentier, Justin and Saurel, Guilhem and Buondonno, Gabriele and Mirabel, Joseph and Lamiraux, Florent and Stasse, Olivier and Mansard, Nicolas},
   booktitle={IEEE International Symposium on System Integrations (SII)},
   year={2019}
105 106
}
```
Justin Carpentier's avatar
Justin Carpentier committed
107

jcarpent's avatar
jcarpent committed
108 109 110
The algorithms for the analytical derivatives of rigid-body dynamics algorithms are detailed here:
```
@inproceedings{carpentier2018analytical,
Justin Carpentier's avatar
Justin Carpentier committed
111 112 113 114
  title = {Analytical Derivatives of Rigid Body Dynamics Algorithms},
  author = {Carpentier, Justin and Mansard, Nicolas},
  booktitle = {Robotics: Science and Systems},
  year = {2018}
jcarpent's avatar
jcarpent committed
115 116
}
```
Justin Carpentier's avatar
Justin Carpentier committed
117

Justin Carpentier's avatar
Justin Carpentier committed
118 119 120 121 122 123
## Questions and Issues

You have a question or an issue? You may either directly open a [new issue](https://github.com/stack-of-tasks/pinocchio/issues) or use the mailing list <pinocchio@laas.fr>.

## Credits

124
The following people have been involved in the development of **Pinocchio** and are warmly thanked for their contributions:
Justin Carpentier's avatar
Justin Carpentier committed
125 126 127 128 129 130

- [Justin Carpentier](https://jcarpent.github.io) (INRIA): main developer and manager of the project
- [Nicolas Mansard](http://projects.laas.fr/gepetto/index.php/Members/NicolasMansard) (LAAS-CNRS): project instructor
- [Guilhem Saurel](http://projects.laas.fr/gepetto/index.php/Members/GuilhemSaurel) (LAAS-CNRS): continuous integration and deployment
- [Joseph Mirabel](http://jmirabel.github.io/) (LAAS-CNRS): Lie groups support
- [Antonio El Khoury](https://www.linkedin.com/in/antonioelkhoury) (Wandercraft): bug fixes
131
- [Gabriele Buondono](http://projects.laas.fr/gepetto/index.php/Members/GabrieleBuondonno) (LAAS-CNRS): features extension, bug fixes and Python bindings
132
- [Florian Valenza](https://fr.linkedin.com/in/florian-valenza-1b274082) (Astek): core developments and FCL support
Justin Carpentier's avatar
Justin Carpentier committed
133
- [Wolfgang Merkt](http://www.wolfgangmerkt.com/) (University of Edinburgh): ROS integration and support
134
- [Rohan Budhiraja](https://scholar.google.com/citations?user=NW9Io9AAAAAJ) (LAAS-CNRS): features extension
135
- [Loïc Estève](https://github.com/lesteve) (INRIA): Conda integration and support
136

137
If you have taken part to the development of **Pinocchio**, feel free to add your name and contribution in this list.
138

Justin Carpentier's avatar
Justin Carpentier committed
139 140
## Acknowledgments

141
The development of **Pinocchio** is actively supported by the [Gepetto team](http://projects.laas.fr/gepetto/) [@LAAS-CNRS](http://www.laas.fr) and the [Willow team](https://www.di.ens.fr/willow/) [@INRIA](http://www.inria.fr).