pink-kinematics/pink

Pink – 基于 Pinocchio 的 Python 逆运动学

是什么 – Pink 是一个 Python 库，用于计算关节式机器人（机械臂、人形机器人、四足机器人、轮式底盘等）的微分逆运动学（IK）。它将高层任务描述（例如“将脚放置在此点”、“保持躯干直立”）转换为一个二次规划问题，从而生成满足关节限制和可选速度上限的关节空间速度。

为何重要 – 逆运动学是机器人控制的核心部分。Pink 提供了简洁的任务导向 API、自动的雅可比处理以及快速的 QP 求解器（默认 quadprog）。它复用了经过充分测试的 Pinocchio 刚体动力学引擎，因此无需编写底层数学即可获得精确的运动学。

快速开始

# 推荐：conda（提供编译好的 Pinocchio 绑定）
conda install -c conda-forge pink

# 或通过 PyPI
pip install pin-pink

import pink
from pink.tasks import FrameTask, PostureTask
from pink.limits import FloatingBaseVelocityLimit
from robot_descriptions.loaders.pinocchio import load_robot_description
import numpy as np, time

# 加载机器人模型（URDF）—— 以 "upkie" 人形机器人为例
robot = load_robot_description("upkie_description")
conf = pink.Configuration(robot.model, robot.data, robot.q0)

# 定义任务（位置/姿态成本为可选）
tasks = {
    "base": FrameTask("base", position_cost=1.0, orientation_cost=1.0),
    "left_contact": FrameTask("left_contact", position_cost=[0.1,0,0.1]),
    "right_contact": FrameTask("right_contact", position_cost=[0.1,0,0.1]),
    "posture": PostureTask(cost=1e-3),
}

# 设置目标姿态（示例值）
tasks["posture"].set_target([
    1.0, 0.0, 0.0, 0.0,          # 浮动基座四元数
    0.0, 0.0, 0.0,               # 浮动基座位置
    0.0, 0.2, 0.0, 0.0, -0.2, 0.0  # 关节角度
])

# 从当前机器人姿态初始化帧任务
for name, task in tasks.items():
    if isinstance(task, FrameTask):
        task.set_target(conf.get_transform_frame_to_world(name))

# 可选：限制浮动基座速度
fb_limit = FloatingBaseVelocityLimit(
    conf.model,
    base_frame="base_link",
    max_linear_velocity=[0.3, 0.3, 0.2],
    max_angular_velocity=[1.0, 1.0, 1.0],
)
conf.model.floating_base_velocity_limit = fb_limit

# 运行简单的微分 IK 循环
dt = 6e-3
for _ in np.arange(0.0, 2.0, dt):
    vel = pink.solve_ik(conf, tasks.values(), dt, solver="quadprog")
    conf.integrate_inplace(vel, dt)
    time.sleep(dt)

该循环整合速度输出，使机器人在遵守限制的前提下向定义的任务目标移动。

核心思想

概念	Pink 的实现方式
任务定义	每个任务提供残差函数 $e(q)$ 和雅可比矩阵 $J_e(q)$。成本（权重）将残差转化为归一化的二次目标函数。
加权多任务 IK	所有任务成本相加；冲突由您赋予的相对权重解决（例如，脚放置成本高，姿态成本低）。
二次规划	问题 $\min_v \sum \|J_e v + \alpha e\|^2_{W_e}$ 在速度边界下交由 QP 求解器（默认 `quadprog`）处理。
速度限制	关节级限制来自 Pinocchio 模型；浮动基座限制可通过 `FloatingBaseVelocityLimit` 附加。
微分（一阶）方法	Pink 计算出一个关节空间速度 $v$，该速度可在一步内减少残差。重复此步骤可收敛至局部最优构型。

使用 Pink 可以做什么

全身控制：用于人形机器人（如 Draco 3、Upkie）—— 平衡、脚位放置、躯干朝向。
机械臂操作：UR5、Panda、双臂配置，支持可选的末端执行器障碍约束。
腿式运动：四足机器人 Go2 下蹲、轮式双足机器人 Upkie 无滑移滚动。
碰撞避免：集成障碍函数（参见 barriers 示例）以防止肢体自碰撞。
自定义机器人：通过 robot_descriptions 加载任意 URDF 并立即定义任务。
快速原型开发：高级 API 使研究人员无需接触底层雅可比代码即可实验新的任务公式或成本调度。

文档与社区

API 参考 – https://pink-kinematics.github.io/pink/
示例 – 丰富的 examples/ 文件夹涵盖机械臂、双臂、人形机器人、移动基座及自定义 URDF 加载。
讨论 – 常见问题与设计讨论位于 GitHub 的 Discussions 标签页（例如，全局 IK 与微分 IK 的区别）。
贡献 – 贡献指南在 CONTRIBUTING.md 中；项目欢迎任何机器人经验者提交 bug 报告和 PR。

许可与引用

许可：Apache-2.0（宽松，适合商业用途）。
引用：提供可直接复制的 BibTeX 条目；若贡献，请添加您的姓名。

总结 – Pink 为 Python 开发者提供了一种数学上严谨、易于使用的多任务逆运动学解决方案，适用于任何 Pinocchio 兼容的机器人模型，是研究、仿真和原型控制代码的实用工具。