pink-kinematics/pink

Pink – Pinocchio 上で構築された Python 逆運動学

何であるか – Pink は、アーティキュレーテッドロボット（アーム、ヒューマノイド、四足歩行ロボット、車輪ベースなど）の微分逆運動学（IK）を計算できる Python ライブラリです。高レベルなタスク仕様（例：「足をこの点に配置する」、「胴体をまっすぐ保つ」）を、関節空間速度を制約しつつ、関節制限とオプションの速度制限を尊重する二次計画問題に変換します。

なぜ重要か – 逆運動学はロボット制御の中心的な要素です。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 は、1ステップで残差を減らす関節空間速度 $v$ を計算します。このステップを繰り返すことで、局所最適な構成に収束します。

Pink でできること

全身制御：ヒューマノイド（例：Draco 3, Upkie） – バランス、足の配置、胴体の向き。
アーム操作：UR5、Panda、ダブルアーム構成、オプションのエンドエフェクタ障壁制約付き。
脚部歩行：四足歩行ロボット Go2 のスクワット、車輪付き二足歩行ロボット Upkie の滑りなしロール。
衝突回避：バリア関数を統合（barriers 例を参照）して、肢体が自己衝突しないようにする。
カスタムロボット：robot_descriptions を通じて任意の URDF を読み込み、すぐにタスクを定義可能。
迅速プロトタイピング：高レベル API により、研究者は低レベルヤコビアンコードに触らずに、新しいタスク定式化やコストスケジュールを実験可能。

ドキュメントとコミュニティ

APIリファレンス – https://pink-kinematics.github.io/pink/
例 – アーム、ダブルアーム、ヒューマノイド、モバイルベース、カスタム URDF 読み込みをカバーする豊富な examples/ フォルダ。
ディスカッション – FAQ と設計ディスカッションは GitHub の Discussions タブに掲載（例：グローバルIK vs. 微分IK）。
貢献 – プロジェクトは CONTRIBUTING.md にガイドラインを記載；ロボット工学経験のある誰でもバグ報告や PR を歓迎。

ライセンスと引用

ライセンス：Apache-2.0（許容性が高く、商用利用に適しています）。
引用：すぐにコピー可能な BibTeX エントリが提供されています；貢献した場合は名前を追加してください。

結論 – Pink は、Pinocchio互換ロボットモデルに対して、数学的に妥当で使いやすいマルチタスク逆運動学を解決するための Python 開発者向けツールを提供し、研究、シミュレーション、プロトタイプ制御コードに役立ちます。