| CI on ROS |
 |
| CI on Linux via APT |
 |
| CI on macOS and Windows via Pixi |
 |
| CI on Linux via Robotpkg |
 |
## 性能表现
**Pinocchio** 尽最大可能利用了由机器人系统的运动学树所引发的稀疏性。得益于现代编程语言范式，**Pinocchio** 可以在编译时直接展开大部分计算，从而在广泛的机器人类型上实现惊人的性能，如下图所示，该图是在配备 Intel Core i7 CPU @ 2.4 GHz 的标准笔记本电脑上获得的。
对于其他基准测试，特别是 Pinocchio 利用高级代码生成技术以充分发挥你的 CPU 能力的测试，我们参考了相关的技术[论文](https://hal-laas.archives-ouvertes.fr/hal-01866228)。
此外，[内省](https://github.com/rbd-benchmarks/rbd-benchmarks)也可能有助于你理解并比较现代刚体动力学库的性能。
## 正在进行中的开发
如果你想跟进当前的开发进度，可以参考 [devel 分支](https://github.com/stack-of-tasks/pinocchio/tree/devel)。
[devel 分支](https://github.com/stack-of-tasks/pinocchio/tree/devel/)仅包含最新的发布版本。任何新的 Pull Request 都应提交到 [devel 分支](https://github.com/stack-of-tasks/pinocchio/tree/devel/)。
## 安装说明
**Pinocchio** 可以轻松安装在各种 Linux（Ubuntu、Fedora 等）和 Unix 发行版（Mac OS X、BSD 等）上。请参阅[安装指南](http://stack-of-tasks.github.io/pinocchio/download.html)。
### Conda
你只需要这行简单的命令：
```
conda install pinocchio -c conda-forge
```
### Docker
```
docker run --rm -it ghcr.io/stack-of-tasks/pinocchio:devel
```
### ROS
**Pinocchio** 也已部署在 ROS 上。
你可以按照下方的部署状态进行跟进。
如果你有兴趣在与 ROS 生态系统集成的系统或软件包中使用 Pinocchio，我们建议通过 ROS PPA 分发的二进制文件来安装 Pinocchio。
在这里，你可以使用以下命令安装 Pinocchio：
```
sudo apt install ros-$ROS_DISTRO-pinocchio
```
这会安装支持碰撞检测的 Coal 版 Pinocchio，并附带 Python 绑定。
然后，你可以通过以下方式在你的 ROS 软件包中使用 Pinocchio：
* 在你的 `package.xml` 配置中声明依赖 Pinocchio（`
pinocchio`）
* 通过 CMake 包含 Pinocchio（`find_package(pinocchio REQUIRED)`）并链接到 Pinocchio（`target_link_libraries(my_library pinocchio::pinocchio)`）
我们包含了支持和钩子，以便 ROS 构建系统能够发现该软件包。
可以在[此仓库](https://github.com/sea-bass/pinocchio_ros_cpp_example)中找到 ROS 2 的示例。
请注意，我们始终建议首先包含 `pinocchio/fwd.hpp` 头文件，以避免因 Boost 变体大小不同而导致的编译错误。
| ROS 2 发行版 | 构建状态 |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Humble** | [](https://build.ros2.org/job/Hbin_uJ64__pinocchio__ubuntu_jammy_amd64__binary) |
| **Jazzy** | [](https://build.ros2.org/job/Jbin_uN64__pinocchio__ubuntu_noble_amd64__binary) |
| **Kilted** | [](https://build.ros2.org/job/Kbin_uN64__pinocchio__ubuntu_noble_amd64__binary) |
| **Lyrical** | [](https://build.ros2.org/job/Lbin_uR64__pinocchio__ubuntu_resolute_amd64__binary) |
| **Rolling** | [](https://build.ros2.org/job/Rbin_uR64__pinocchio__ubuntu_resolute_amd64__binary) |
## 可视化
**Pinocchio** 为许多开源且免费的可视化工具提供了支持：
- [Gepetto Viewer](https://github.com/Gepetto/gepetto-viewer)：一个基于 [OpenSceneGraph](https://github.com/openscenegraph/OpenSceneGraph) 的 C++ 查看器，具有 Python 绑定和 Blender 导出功能。有关混合使用 **Pinocchio** 和 **Gepetto Viewer** 的 C++ 示例，请参见[此处](https://github.com/stack-of-tasks/pinocchio-gepetto-viewer)。
- [Meshcat](https://github.com/rdeits/meshcat)：支持在 Python 中进行可视化，并且可以嵌入到任何浏览器中。
- [Panda3d](https://github.com/ikalevatykh/panda3d_viewer)：支持在 Python 中进行可视化，并且可以嵌入到任何浏览器中。
- [RViz](https://github.com/ros-visualization/rviz)：支持在 Python 中进行可视化，并且可以与其他 ROS 软件包进行交互。
- [Viser](https://github.com/nerfstudio-project/viser)：支持使用 Python 进行基于浏览器的可视化，并支持诸如滑块和交互式标记等小部件。
许多外部查看器也可以被集成。有关更多信息，请参见[此处](https://github.com/stack-of-tasks/pinocchio/blob/devel/bindings/python/pinocchio/visualize/base_visualizer.py)的示例。
## 引用 Pinocchio
要在你的学术研究中引用 **Pinocchio**，请考虑引用这篇[软件论文](https://laas.hal.science/hal-01866228v2/file/19-sii-pinocchio.pdf)并使用以下 BibTeX 条目：
```
@inproceedings{carpentier2019pinocchio,
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}
}
```
如果需要链接到 GitHub 代码库，请使用以下条目：
```
@misc{pinocchioweb,
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--2021}
}
```
## 引用特定的算法贡献
**Pinocchio** 不仅仅实现了标准的刚体动力学算法，它还是关于仿真、学习和控制的活跃研究的成果。
**Pinocchio** 为处理约束、闭环机构、对正逆动力学进行微分等提供了最先进的算法。
如果你使用了这些算法，请考虑在你的研究论文中引用它们。
- de Mont-Marin, Y. Montaut, L. Ponce, J. Herbet, M. & Carpentier, J. (2026). [On the Conic Complementarity of Planar Contacts](https://arxiv.org/pdf/2509.25999). In 2026 International Conference on Robotics and Automation (ICRA).
- Sathya, A., Montaut, L. de Mont-Marin, Y. & Carpentier, J. (2026). [Matrix-Free Delassus Operations: Scalable and Memory-Efficient Algorithms](https://hal.science/hal-05457476v1/file/RAL___Matrix_free_Delassus_Computation.pdf). Preprint.
- Sathya, A. & Carpentier, J. (2025). [Constrained articulated body algorithms for closed-loop mechanisms](https://hal.science/hal-04895583v2/file/main.pdf). In Transactions on Robotics.
- Sathya, A. & Carpentier, J. (2024). [Constrained Articulated Body Dynamics Algorithms](https://hal.science/hal-04443056v2/file/TRO%20-%20Constrained%20Articulated%20Body%20Dynamics%20Algorithms.pdf). In Transactions on Robotics.
- Carpentier, J., Le Lidec, Q. & Montaut, L. (2024, July). [From Compliant to Rigid Contact Simulation: a Unified and Efficient Approach](https://hal.science/hal-04588906). In RSS 2024-Robotics: Science and Systems (RSS 2024).
- Le Lidec, Q., Jallet, W., Montaut, L., Laptev, I., Schmid, C., & Carpentier, J. (2024). [Contact models in robotics: a comparative analysis](https://hal.science/hal-04067291/). IEEE Transactions on Robotics.
Montaut, L., Le Lidec, Q., Petrik, V., Sivic, J., & Carpentier, J. (2024). [GJK++: Leveraging Acceleration Methods for Faster Collision Detection](https://hal.science/hal-04070039/). IEEE Transactions on Robotics.
- Sathya, A., & Carpentier, J. (2024). [Constrained Articulated Body Dynamics Algorithms](https://hal.science/hal-04443056/). IEEE Transactions on Robotics.
- Montaut, L., Le Lidec, Q., Bambade, A., Petrik, V., Sivic, J., & Carpentier, J. (2023, May). [Differentiable collision detection: a randomized smoothing approach](https://hal.science/hal-03780482/). In 2023 IEEE International Conference on Robotics and Automation (ICRA).
- Montaut, L., Le Lidec, Q., Petrik, V., Sivic, J., & Carpentier, J. (2022, June). [Collision Detection Accelerated: An Optimization Perspective](https://hal.science/hal-03662157/). In Robotics: Science and Systems (RSS 2022).
- Carpentier, J., Budhiraja, R., & Mansard, N. (2021, July). [Proximal and sparse resolution of constrained dynamic equations](https://hal.science/hal-03271811/). In Robotics: Science and Systems (RSS 2021).
- Carpentier, J., & Mansard, N. (2018, June). [Analytical derivatives of rigid body dynamics algorithms](https://hal.science/hal-01790971/). In Robotics: Science and Systems (RSS 2018).
## 问题与议题
你有问题或遇到议题了吗？你可以直接打开一个[新问题](https://github.com/stack-of-tasks/pinocchio/discussions/new?category=q-a)或[新议题](https://github.com/stack-of-tasks/pinocchio/issues)，或者通过邮件列表
直接联系我们。
## 核心开发团队
**Pinocchio** 当前活跃的核心开发人员有：
- [Justin Carpentier](https://jcarpent.github.io) (Inria)：项目的主要开发者和负责人
- [Guilhem Saurel](https://www.laas.fr/fr/annuaire/gsaurel) (LAAS-CNRS)：CI/CD、打包
- [Etienne Arlaud](https://github.com/EtienneAr) (Inria)：核心开发者
- [Wilson Jallet](https://github.com/ManifoldFR) (Inria)：Python 绑定的扩展、C++ 可视化 API
- [Fabian Schramm](https://github.com/fabinsch) (Inria)：核心开发者
- [Joris Vaillant](https://github.com/jorisv) (Inria)：核心开发者和项目管理人
- [Ajay Sathya](https://www.ajaysathya.com/) (Inria)：核心开发者
- [Louis Montaut](https://lmontaut.github.io/) (Inria)：核心开发者
- [Quentin Le Lidec](https://quentinll.github.io/) (NYU/前 Inria)：核心开发者
- [Yann de Mont-Marin](https://ymontmarin.github.io/) (Inria)：核心开发者
- [Jeanne Matheron](https://www.linkedin.com/in/jeanne-matheron/) (Inria)：核心开发者
## 依赖 Pinocchio 的开源项目
- [Crocoddyl](https://github.com/loco-3d/crocoddyl)：用于实现复杂机器人平台模型预测控制的软件。
- [TSID](https://github.com/stack-of-tasks/tsid/)：实现了任务空间逆向动力学 QP 的软件。
- [HPP](https://humanoid-path-planner.github.io/hpp-doc/)：为仿人机器人及其他机器人实现运动规划器的 SDK。
- [Jiminy](https://github.com/duburcqa/jiminy)：基于 Pinocchio 的仿真器。
- [ocs2](https://github.com/leggedrobotics/ocs2)：用于切换系统最优控制 (OCS2) 的工具箱
- [TriFingerSimulation](https://github.com/open-dynamic-robot-initiative/trifinger_simulation)：TriFinger 机器人仿真（用于在操作任务上进行 RL 的机器人）。
- [Casadi_Kin_Dyn](https://github.com/ADVRHumanoids/casadi_kin_dyn)：IIT 软件包，用于生成机器人运动学和动力学的符号 (SX) 表达式。
- [PyRoboPlan](https://github.com/sea-bass/pyroboplan)：一个使用 Pinocchio Python 绑定进行机械臂运动规划的教育性 Python 库。
- [RoboPlan](https://github.com/open-planning/roboplan)：基于 Pinocchio 的现代机器人运动规划库，采用 C++ 编写并带有 Python 绑定（PyRoboPlan 的后继者）。
- [ProxSuite-NLP](https://github.com/Simple-Robotics/proxsuite-nlp)：用于流形上非线性规划的原始-对偶增广拉格朗日求解器。
- [Aligator](https://github.com/Simple-Robotics/aligator)：一个用于受约束轨迹优化的多功能且高效的框架。
- [Simple](https://github.com/Simple-Robotics/Simple)：Simple 仿真器：让仿真变得简单。
- [LoIK](https://github.com/Simple-Robotics/LoIK)：低复杂度逆运动学。
- [PlaCo](https://github.com/Rhoban/placo)：Rhoban 的规划与控制库，具有用于全身控制任务的任务空间逆运动学和动力学高级 API。
- [CRISP controllers](https://github.com/utiasDSL/crisp_controllers)：一系列兼容 `ros2_control` 的实时 C++ 控制器，用于机械臂的柔顺基于力矩的控制。
## 致谢
**Pinocchio** 的开发由 [@INRIA](http://www.inria.fr) 的 [Willow 团队](https://www.di.ens.fr/willow/) 积极主导，并得到了 [@LAAS-CNRS](http://www.laas.fr) [Gepetto 团队](http://projects.laas.fr/gepetto/) 的支持。