plainmp

The project is licensed under the BSD 3 License (see LICENSE), except for the code in cpp directory which is licensed under the MPL2.0 (see cpp/LICENSE-MPL2).

plainmp provides:

• Fast sampling-based motion planning (e.g., less than 1ms for moderate problems using RRTConnect)
• Collision-aware inverse kinematics (IK) solver
• Motion planning/IK for various models (e.g. movable base, dual-arm, object attachment)
• Flexible framework for defining various robot model and motion planning problems
• Collision checking for primitives (sphere/box/cylinder...) and/or point cloud vs. robot
• (Beta) Sampling-based constrained motion planning solver (e.g., whole-body humanoid)
• (Beta) SQP-based constrained motion planning (will be used as smoother for sampling-based planner)

Note that plainmp currently heavily relies on approximations of robot body by spheres.

The TODO list is

• Speed up IK by reimplementing current Python/C++ mix into pure C++

Related/depeding projects:

• plainmp is a rewrite of my previous projects scikit-motionplan and tinyfk to achieve 100x speedup
• plainmp depends on OMPL (with unmerged PR of ERTConnect) for SBMP algorithms
• plainmp deponds on scikit-robt framework for visualization and planning problem specifications
• benchmark with VAMP (the world fastest motion planner as of 2024 to my knowledge) shows that
  • AMD Ryzen 7 7840HS (256-bit AVX) VAMP is faster (1.3x, 1.1x, 4.8x, 12.5x)
  • ARM Neoverse-N1 (128-bit NEON) both seems to be comparable (0.53x, 0.41x, 2.2x, 4.8x)
  • x-s are time ratio plainmp/VAMP for 4 different settings with resolution of 1/32

Performance example

panda dual bars: median 0.17 ms | panda ceiled dual bars: median 0.65 ms | fetch table: median 0.62 ms

* resolution is isotropically set to 0.05 rad or 0.05 m with box motion validator

* On my laptop (AMD Ryzen 7 7840HS)

The plots are generated by the following commands:

python3 example/bench/panda_plan.py  # panda dual bars
python3 example/bench/panda_plan.py --difficult  # panda ceiled dual bars
python3 example/bench/fetch_plan.py  # fetch table

installation and usage (Ubuntu/macOS)

On Ubuntu:

sudo apt install libeigen3-dev libboost-all-dev libompl-dev libspatialindex-dev freeglut3-dev libsuitesparse-dev libblas-dev liblapack-dev
pip install plainmp  # or build from source after git submodules update --init

On macOS:

brew install eigen boost ompl spatialindex suite-sparse openblas lapack
pip install plainmp  # or build from source after git submodules update --init

Then try examples in example directory with --visualize option. Note that you may need to install the following for visualization:

pip uninstall -y pyrender && pip install git+https://github.com/mmatl/pyrender.git --no-cache-dir

Troubleshooting

• Segmentation faults and other C++ runtime errors may occur when multiple OMPL versions are present - typically when installed via both from Ubuntu and ROS. To temporarily resolve this, disable ROS workspace sourcing in your shell or remove either OMPL installation.

How to add a new robot model

* Feel free to open an issue and include your (public) URDF file/link! I might be able to create a custom sphere model for that.

• (step 1) Prepare a URDF file. Note that robot_description package might be useful.
• (step 2) Implement a new class inheriting RobotSpec class in src/plainmp/robot_spec.py.
• (step 3) Write yaml file defining urdf location/collision information/control joints/end effector in (see example yaml files). For determining the sphere locations, tools like bheijden/bubblify or CoMMALab/form will be useful.

Note on motion validator of motion planning

We provides two types of motion validator type box and euclidean.

• The box type split the motion segment into waypoints by clipping the segment with the collision box. You need to specify box widths for each joint.
  • e.g. bow_width = np.ones(7) / 20 for panda robot
• The euclidean type is instead split the segment by euclidean distance of resolution parameter.
  • e.g. resolution = 1/20 for panda robot
• see problem.py for how to specify the motion validator.