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 兼容的機器人模型，是研究、模擬與原型控制程式碼的實用工具。