pink-kinematics/pink

Pink – Python Inverse Kinematics built on Pinocchio

What it is – Pink is a Python library that lets you compute differential inverse kinematics (IK) for articulated robots (arms, humanoids, quadrupeds, wheeled bases, etc.). It translates high‑level task specifications (e.g., “place the foot at this point”, “keep the torso upright”) into a quadratic program that yields joint‑space velocities respecting joint limits and optional velocity caps.

Why it matters – Inverse kinematics is a core piece of robot control. Pink provides a clean, task‑centric API, automatic Jacobian handling, and a fast QP solver (default quadprog). It re‑uses the well‑tested Pinocchio rigid‑body dynamics engine, so you get accurate kinematics without writing low‑level math yourself.

Quick start

# Preferred: conda (gives compiled Pinocchio bindings)
conda install -c conda-forge pink

# Or via 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

# Load a robot model (URDF) – here the "upkie" humanoid
robot = load_robot_description("upkie_description")
conf = pink.Configuration(robot.model, robot.data, robot.q0)

# Define tasks (position/orientation costs are optional)
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),
}

# Set a target posture (example values)
tasks["posture"].set_target([
    1.0, 0.0, 0.0, 0.0,          # floating‑base quaternion
    0.0, 0.0, 0.0,               # floating‑base position
    0.0, 0.2, 0.0, 0.0, -0.2, 0.0  # joint angles
])

# Initialise frame tasks from the current robot pose
for name, task in tasks.items():
    if isinstance(task, FrameTask):
        task.set_target(conf.get_transform_frame_to_world(name))

# Optional: limit floating‑base twist
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

# Run a simple differential‑IK loop
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)

The loop integrates the velocity output, driving the robot toward the defined task targets while respecting limits.

Core ideas

Concept	How Pink implements it
Task definition	Each task supplies a residual function (e(q)) and a Jacobian (J_e(q)). Costs (weights) turn residuals into a normalized quadratic objective.
Weighted multi‑task IK	All task costs are summed; conflicts are resolved by the relative weights you give (e.g., high cost for foot placement, low cost for posture).
Quadratic programming	The problem (\min_v \sum \|J_e v + \alpha e\|^2_{W_e}) with velocity bounds is handed to a QP solver (`quadprog` by default).
Velocity limits	Joint‑wise limits come from the Pinocchio model; floating‑base limits can be attached via `FloatingBaseVelocityLimit`.
Differential (first‑order) approach	Pink computes a joint‑space velocity (v) that would reduce the residuals in one time step. Repeating the step yields convergence to a locally optimal configuration.

What you can do with Pink

Whole‑body control for humanoids (e.g., Draco 3, Upkie) – balance, foot placement, torso orientation.
Arm manipulation – UR5, Panda, dual‑arm setups, with optional end‑effector barrier constraints.
Legged locomotion – quadruped Go2 squatting, wheeled‑biped Upkie rolling without slip.
Collision avoidance – integrate barrier functions (see the barriers examples) to keep limbs from self‑colliding.
Custom robots – load any URDF via robot_descriptions and immediately define tasks.
Rapid prototyping – the high‑level API lets researchers experiment with new task formulations or cost schedules without touching low‑level Jacobian code.

Documentation & community

API reference – https://pink-kinematics.github.io/pink/
Examples – a rich examples/ folder covering arms, dual‑arms, humanoids, mobile bases, and custom URDF loading.
Discussions – FAQs and design discussions live in the GitHub Discussions tab (e.g., global IK vs. differential IK).
Contributing – guidelines are in CONTRIBUTING.md; the project welcomes bug reports and PRs from anyone with robotics experience.

License & citation

License: Apache‑2.0 (permissive, commercial‑friendly).
Citation: A ready‑to‑copy BibTeX entry is provided; add your name if you contribute.

Bottom line – Pink gives Python developers a mathematically sound, easy‑to‑use way to solve multi‑task inverse kinematics for any Pinocchio‑compatible robot model, making it a handy tool for research, simulation, and prototype control code.