README.md 7.43 KB
Newer Older
Justin Carpentier's avatar
Justin Carpentier committed
1
Pinocchio: a C++ library for efficient Rigid Multi-body Dynamics computations
Nicolas Mansard's avatar
Nicolas Mansard committed
2
===========
Olivier Stasse's avatar
Olivier Stasse committed
3

4
[![License](https://img.shields.io/badge/License-BSD%202--Clause-green.svg)](https://opensource.org/licenses/BSD-2-Clause)
Justin Carpentier's avatar
Justin Carpentier committed
5
[![Build Status](https://travis-ci.org/stack-of-tasks/pinocchio.svg?branch=master)](https://travis-ci.org/stack-of-tasks/pinocchio)
6
[![Coverage report](https://gepgitlab.laas.fr/stack-of-tasks/pinocchio/badges/master/coverage.svg?job=doc-coverage)](http://projects.laas.fr/gepetto/doc/stack-of-tasks/pinocchio/master/coverage/)
7 8
[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/pinocchio.svg)](https://anaconda.org/conda-forge/pinocchio)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/pinocchio.svg)](https://anaconda.org/conda-forge/pinocchio)
9
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/pinocchio/badges/installer/conda.svg)](https://conda.anaconda.org/conda-forge)
Justin Carpentier's avatar
Justin Carpentier committed
10

Nicolas Mansard's avatar
Nicolas Mansard committed
11

12
**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
13
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
14

Justin Carpentier's avatar
Justin Carpentier committed
15
**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
16
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/).
17

18
**Pinocchio** is now at the heart of various robotics softwares as the [Stack-of-Tasks](http://stack-of-tasks.github.io) or the [Humanoid Path Planner](https://humanoid-path-planner.github.io/hpp-doc).
19

20 21
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).

22 23 24 25 26 27 28 29
## Pinocchio features

**Pinocchio** is fast:

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

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

Justin Carpentier's avatar
Justin Carpentier committed
32 33 34 35 36 37 38
   - forward kinematics and its analytical derivatives,
   - forward/inverse dynamics and their analytical derivatives,
   - centroidal dynamics and its analytical derivatives.

**Pinocchio** is flexible:

   - header only,
Justin Carpentier's avatar
Justin Carpentier committed
39
   - C++11/14/17/20 compliant.
40 41 42

**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
43
**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)).
44

Justin Carpentier's avatar
Justin Carpentier committed
45 46 47 48
## 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
49
## Installation
50

Justin Carpentier's avatar
Justin Carpentier committed
51
**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
52

Justin Carpentier's avatar
Justin Carpentier committed
53 54
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).

55 56
**Pinocchio** is also being 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).

57 58 59 60
## 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
61 62
## Examples

63
We provide some basic examples on how to use **Pinocchio** in Python in the [examples/python](./examples/python) directory.
64
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
65

66
## Tutorials
Justin Carpentier's avatar
Justin Carpentier committed
67

Rohan Budhiraja's avatar
Rohan Budhiraja committed
68
**Pinocchio** is coming with a large bunch of tutorials aiming at introducing the basic tools for robotics control.
Justin Carpentier's avatar
Justin Carpentier committed
69
The content of the tutorials are described [here](http://projects.laas.fr/gepetto/index.php/Teach/Supaero2018) and the source code of these tutorials is located [here](https://github.com/stack-of-tasks/pinocchio-tutorials).
Justin Carpentier's avatar
Justin Carpentier committed
70

Justin Carpentier's avatar
Justin Carpentier committed
71 72
## Citing Pinocchio

Justin Carpentier's avatar
Justin Carpentier committed
73
To cite **Pinocchio** in your academic research, please use the following bibtex lines:
Justin Carpentier's avatar
Justin Carpentier committed
74 75
```
@misc{pinocchioweb,
Justin Carpentier's avatar
Justin Carpentier committed
76 77 78 79 80
   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
81
```
82
and the following one for the reference to the paper introducing **Pinocchio**:
83 84
```
@inproceedings{carpentier2019pinocchio,
Justin Carpentier's avatar
Justin Carpentier committed
85 86 87 88
   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}
89 90
}
```
Justin Carpentier's avatar
Justin Carpentier committed
91

jcarpent's avatar
jcarpent committed
92 93 94
The algorithms for the analytical derivatives of rigid-body dynamics algorithms are detailed here:
```
@inproceedings{carpentier2018analytical,
Justin Carpentier's avatar
Justin Carpentier committed
95 96 97 98
  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
99 100
}
```
Justin Carpentier's avatar
Justin Carpentier committed
101

Justin Carpentier's avatar
Justin Carpentier committed
102 103 104 105 106 107 108 109 110 111 112 113 114
## 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

The following people have been involved in the development of **Pinocchio**:

- [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
115
- [Gabriele Buondono](http://projects.laas.fr/gepetto/index.php/Members/GabrieleBuondonno) (LAAS-CNRS): features extension, bug fixes and Python bindings
116
- [Florian Valenza](https://fr.linkedin.com/in/florian-valenza-1b274082) (Astek): core developments and FCL support
Justin Carpentier's avatar
Justin Carpentier committed
117
- [Wolfgang Merkt](http://www.wolfgangmerkt.com/) (University of Edinburgh): ROS integration and support
118
- [Rohan Budhiraja](https://scholar.google.com/citations?user=NW9Io9AAAAAJ) (LAAS-CNRS): features extension
119
- [Loïc Estève](https://github.com/lesteve) (INRIA): Conda integration and support
120

Justin Carpentier's avatar
Justin Carpentier committed
121
If you have taken part to the development of **Pinocchio**, feel free to add your name and contribution here.
122

Justin Carpentier's avatar
Justin Carpentier committed
123 124
## Acknowledgments

Justin Carpentier's avatar
Justin Carpentier committed
125
The development of **Pinocchio** is 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).