pink

This major release adds Control Barrier Functions developed by @domrachev03 and @simeon-ned 👍 Examples of what we can do with barriers include:

• Arm: UR5: with joints and end effector limits
• Humanoid: G1: G1 humanoid squatting via a CoM task
• Quadruped: Go2: Go 2 squatting with floating base position limits
• Dual Arms: Yumi: self-collision avoidance with spheres
• Dual Arms: Iiwa: whole-body self-collision avoidance

https://github.com/domrachev03/pink/assets/28687492/d64163b6-399f-4bbf-ac50-1135fa69c2da

Another API-breaking change to the library is that limits are now optional and can be extended (for instance with the new acceleration limit) or disabled. New limits and tasks include:

• Limit: AccelerationLimit
• Task: ComTask for center-of-mass tracking (thanks to @simeon-ned)
• Task: LowAccelerationTask for smoother velocities.

Check out the full changelog below for other changes and fixes. May the Motion be with you!

Added

• Breaking: Updated the logic for handling the joint limits:
  • Add a limits argument to build_ik and solve_ik
  • The check_limits method now includes an optional safety_break argument to control whether execution should stop on exception.
  • The solve_ik function now includes the safety_break that is forwarded to check_limits.
• Control Barrier Functions, namely: (thanks to @domrachev03 and @simeon-ned)
  • Abstract Barrier Barrier
  • Frame Position Barrier PositionBarrier
  • Body Spherical Barrier BodySphericalBarrier
  • Whole-body Self-Collision Avoidance Barrier SelfCollisionBarrier
• Example: UR5 manipulator and GO2 quadruped robot with PositionBarrier
• Example: YUMI two-armed manipulator with BodySphericalBarrier
• Example: G1 humanoid squatting through regulating CoM.
• Limit: AccelerationLimit
• Task: ComTask for center-of-mass tracking (thanks to @simeon-ned)
• Task: LowAccelerationTask for smoother velocities.

Changed

• Breaking: remove lm_damping parameter from DampingTask where it wasn't used
• CICD: Update ruff to 0.4.3
• Configuration accepts list of Control Barrier Functions
• DampingTask: Simplify implementation
• Update to Pinocchio 3 with 2.7 backward compatibility

Fixed

• PostureTask: Match implementation and documentation formula
• Fix broken documentation links

Removed

• CICD: Disable macOS checks until upstream PyPI package is fixed

This release adds the RelativeFrameTask developed with @ymontmarin 👍 This new task is a generalization of the frame task that accepts targets with respect to any robot frame. For example:

https://github.com/stephane-caron/pink/assets/1189580/f349bb55-c7f6-4074-a8bf-0b86a5693098

• Left: relative frame task (stretch_relative_target.py example)
• Right: frame task (stretch_world_target.py example)

This release also brings a few quality-of-use improvements to configurations and costs.

Added

• Function get_transform in the Configuration class
• Task: relative frame task, where target is w.r.t another robot frame

Changed

• Configuration: update function now accepts a configuration vector argument
• Costs: setting cost in relative frame task now accepts plain float

This release brings a number of fixes and completes the renaming of the BodyTask to FrameTask (details below). It also distributes Pink on conda-forge, which is now the recommended way to install for best performance:

conda install -c conda-forge pink

Added

• Add gain keyword argument to all task constructors where is makes sense
• Damping task that minimizes joint velocities
• Distribute package on conda-forge
• Example on how differential IK may converge to a local constrained optimum
• Expose all tasks from the top-level pink module
• Handle unbounded joints in custom configuration vectors
• Unit test for posture task Jacobian

Changed

• Breaking: Define task Jacobian as derivative of the task error
• Breaking: Rename BodyNotFound exception to FrameNotFound
• Breaking: Rename FrameTask.body to FrameTask.frame

Removed

• Body-minus utility function
• Spatial-minus utility function

This release fixes a bug when handling configuration limits for models that contain unbounded revolute joints.

Changed

• Don't check configuration limits when building IK matrices

Fixed

• Configuration limits when model has unbounded revolute joints

This is the first major release of Pink, Python inverse kinematics for articulated robot models, based on Pinocchio. The main update since v0.11.0 is the definition of a proper linear holonomic task on tangent spaces, with accompanying documentation, by @ymontmarin. Thanks! 👍

API-wise, Levenberg-Marquardt damping is now defined in the base Task class and can therefore be set in any task. This release drops support for Python 3.7, and brings a seasonal batch of new examples and bug fixes.

Added

• Example: UR5 arm
• Example: flying dual-arm with UR3
• General linear holonomic task

Changed

• Cost vector is now defined for all tasks
• Drop support for Python 3.7
• Levenberg-Marquardt damping is now defined for all tasks
• Update joint-coupling task to derive from general linear holonomic task

Fixed

• Example: Draco 3 numerical stability

This release upgrades the BodyTask to a FrameTask handling all kinds of frames defined in the robot description. It was contributed by @proyan, thanks! 😃

Added

• Example: Stretch RE1

Changed

• Handle all frames, including non-body frames
• Rename BodyTask to FrameTask

This release fixes handling of models with/without configuration limits and with/without velocity limits.

Added

• Base class Limit for configuration and velocity limits
• In-place integration of a velocity from a configuration
• Unit tests for configuration limits
• Unit tests for velocity limits

Changed

• Add pink.limits submodule
• Configuration and velocity limits are now stacked rather than pre-reduced
• Move configuration limit to ConfigurationLimit class
• Move velocity limit to VelocityLimit class

This release adds the joint-coupling and linear-holonomic tasks contributed by @shbang91 👍 The tasks are unit tested and illustrated by a new humanoid example 💪

Added

• Example: Draco 3 humanoid by @shbang91
• Joint-coupling task by @shbang91
• Linear holonomic task by @shbang91
• Unit tests for joint-coupling and linear holonomic tasks by @shbang91

Changed

• Refactor apply_configuration into Configuration constructor
• Refactor assume_configuration into Configuration constructor
• Refactor task dynamics into compute_error and compute_jacobian

This release fixes the Jacobian of the body task, with a dedicated blog post to explain the fix. In short: we were using the frame Jacobian instead of the full task Jacobian (which includes a log-derivative). Using the frame Jacobian works fine in many use cases, but it can also fail drastically in weighted inverse kinematics. Example and details in the blog post 🗒️

Thanks to @aescande and @Gregwar for their help 👍

Added

• BodyNotFound exception
• Document spatial and body minus between transforms
• Example: SigmaBan humanoid
• Forward keyword arguments of solve_ik to the backend QP solver

Changed

• Return type of compute_velocity_limits now includes optionals
• VectorSpace type is now immutable

Fixed

• Jacobian of the body task

This revision improves joint limit computations significantly, with fixes, new unit tests and examples on the side.

Added

• Bounded subspace of tangent space, that is, restricted to bounded joints
• CI: test on both Ubuntu and macOS images
• Tangent space from Pinocchio model

Changed

• Example: UR3 arm
• Expose pink.Task from top-level module
• Improve joint limit computations

Fixed

• Empty inequalities when model has no bounded joint

This release makes the solver argument mandatory for all calls to solve_ik.

Note that the project is still in beta, so don't expect proper deprecation paths / API-change preemptive warnings before it hits v1.0.0 😉

With this release, Pink handles more general joint types, including fixed or free flyer root joints, unbounded joints (called continuous in URDF), etc. New examples showcase this on both arms 🦾 and legged 🦿 robots.

Under the hood, this release also improves on various points of the QP formulation (joint limits, posture task, ...) so that it works nicely with more solvers (e.g. CVXOPT), beyond quadprog and OSQP which were the two main solvers so far.

Added

• Body task targets can be read directly from a robot configuration
• Example: double pendulum
• Example: Kinova Gen2 arm
• Example: loading a custom URDF description
• Example: visualization in MeshCat
• Example: visualization in yourdfpy
• Generalize configuration limits to any root joint
• Handle descriptions that have no velocity limit
• Handle general root joint in configuration limits
• Handle general root joint in posture task
• Handle unbounded velocity limits in QP formulation
• Posture task targets can be read directly from a configuration
• Simple rate limiter in pink.utils

Changed

• Raise an error when querying a body that doesn't exist
• Transition from pink.models to robot_descriptions
• Update reference posture in Upkie wheeled biped example
• Warn when the backend QP solver is not explicitly selected

Fixed

• Unbounded velocities when the backend solver is CVXOPT

This release brings documentation, full test coverage, and handles robot models installed from PyPI.

Also, it indulges in a project icon 😉

Added

• Coveralls for continuous coverage testing
• Document differential inverse kinematics and task targets
• Single-task test on task target translations mapped to IK output translations

Changed

• Argument to build_from_urdf functions is now the path to the URDF file
• Bumped status to beta
• Examples use the jvrc_description and upkie_description packages
• Use jvrc_description and upkie_description packages from PyPI
• Task is now an abstract base class

Fixed

• Unit tests for robot models

This release adds proper handling of joint position and velocity limits.

Added

• Joint velocity limits
• Configuration limits

Changed

• Bumped status to alpha
• Configuration limit check now has a tolerance argument

This pre-release adds the regularizing posture task and corresponding unit tests.

Added

• Check configuration limits against model
• Mock configuration type for unit testing
• Tangent member of a configuration
• Unit test the body task

Changed

• Specify path when loading a model description
• Switch to the Apache 2.0 license
• build_jvrc_model is now build_from_urdf

Fixed

• Don't distribute robot models with the library
• IK unit test that used robot instead of configuration

This is a first working version of the library with a humanoid example that can be run and tweaked. Keep in mind that 0.x versions mean the library is still under active development, with the goal that 1.0 is the first stable version. So, this is still the very beginning 😉

Added

• Body task
• Humanoid example

Changed

• ConfiguredRobot(model, data) type is now Configuration(model, data, q)

Fixed

• Add floating base joint when loading JVRC model