Using pybullet

From Physics Simulation Wiki

Jump to: navigation, search



This is the prerelease of some cutting edge pybullet documentation. The official documentation will be released soon. The shared memory physics client-server API (in Bullet/examples/SharedMemory/PhysicsClientC_API.h) and pybullet are meant to replace all of Bullet 2.x API, and allow us to migrate from Bullet 2.x to Bullet 3.x (GPU/OpenCL physics engine) and Bullet 4.x (future machine learning/deep learning/reinforcement learning physics engine...) without users having to change the API.

Use-cases will be robotics and interactive VR and games. It should be possible to use pybullet also in Blender scripts, both BGE and regular Blender Python. So, we will develop and figure out a way to create shapes, rigid bodies from inside Blender scripts.

For the moment, you will need to create your objects using URDF descriptions, and load them. URDF are just text files, please give it a try. One option is to create a programmatic way to create URDF files, and load those. Loading a URDF lets you specify collision shapes, mass, inertia, constraints etc. In the future, there might be possibilities to have access to programmatically created content, without using URDF/SDF files.

Additionally, there will also be direct C++ access, using Bullet\examples\RoboticsLearning\b3RobotSimAPI.h. Once this is more complete, it will be renamed b3PhysicsSimAPI.h. Using the Bullet connect 'DIRECT' method, you will be able to do your own graphics engine of course (instead of GUI or SHARED_MEMORY as shown below).



On any platform.

   $ git clone
   $ cd bullet3
   $ cmake --version
   cmake version 3.6.1

On Windows, replace references to Python with your local install in build_cmake_pybullet_win32.bat, and then run:

   $ c:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat
   $ build_cmake_pybullet_win32.bat
   $ msbuild ALL_BUILD.vcxproj

On Linux and MacOS:


You should now have access to the ExampleBrowser application. Play with this for a bit.

   $ cd examples/ExampleBrowser/Debug
   $ App_ExampleBrowser

Finally, symlink the pybullet Python library to something more accessible.

   $ cd ../pybullet
   $ mklink libpybullet.pyd pybullet.pyd  # Windows
   $ ln -s  # Linux
   $ ln -s libpybullet.dylib # MacOS
   $ python -c "import pybullet"

On Windows, this currently throws a Fatal Python error: PyThreadState_Get: no current thread.

Run and use

As we are talking about really cutting edge code (this is cutting edge documentation and you are an early adopter), if a method name has changed or is not available anymore, your best guess is to run:

  import pybullet as p

This will give you a listing of all the methods available.

pybullet in different modes

  • Start python while in this directory, so it can find, and start your first script: (replace p.GUI with p.DIRECT or p.SHARED_MEMORY, -> shared memory will connect to example browser, while in 'experimental/physics server' mode)

   import pybullet as p
  • The VR example only works on Windows at the moment (waiting for Valve/HTC Vive/Oculus Rift),

but you can see it using pybullet as follows:

   import pybullet as p

  • There are also some example pybullet scripts in Bullet/examples/pybullet.

pybullet to connect to a 'physics server' in the example browser

  • First start the example browser, and select the 'Experiments/Physics Server' example, and leave it running. Before running the script below, your ExampleBrowser in 'Experiments/Physics Server' should look similar to this:

In the example browser, make sure to select Experiments/Physics Server, NOT "Physics Client (Shared Memory)".

  • In a new terminal, start python in the build_cmake/example/pybullet directory, start it (python) and then run the following script.
   import pybullet as p

  • The p.setRealTimeSImulation(1) will add some hard-coded world/objects (used for the VR demo). You can also leave out the 'p.setRealTimeSimulation(1)' command. In that case, you have to manually 'step' the simulation by sending 'p.stepSimulation' commands and put objects in the world by using loadUrdf/loadSdf.
  • After running above script, it should look similar to this:


URDF format for pybullet

For the moment, the main way to setup a robot is to use .urdf files. URDF is a format defined for the Robot Operating System to easily model robots and can easily be written by hand as its internal format is xml. If you are new to URDF, you can follow the tutorial on the page to create simple URDFS:

In case you intend to build larger models, the xacro tool might come in handy. It enables you to create macros and constants to replicate a component several times in a similar fashion or add the same constant into different places. To simplify the usage of xacro for Bullet Physics development, the is placed in the data folder and can be run using a python shell.

pybullet and VR

The latest Bullet version comes with a Virtual Reality demo for HTC Vive and Oculus Rift (based on Valve's OpenVR) with hand controller and grabbing interaction.

See the video of the result:

The grabbing happens similar to mouse picking in 2D: using constraints: either a point to point constraint, or a fixed constraint. You can control the stiffness using the maximum applied force/impulse of the constraint. This way, all interactions are consistent, including collision detection and collision response and joint limits, motors etc. The VR pybullet environment uses btMultiBody by default, for rigid joints needed in robotics.

You'll notice some lag in the hand controller, which can be tuned using max force and error reduction parameter, time step, solver iterations etc. The user feedback so far confirmed that this current implementation using constraints is a reasonable compromise as a starting point, but by no means finalized. The nice part of the Virtual Reality demo is that it is a generic physics sandbox: you can start with an empty world, and use pybullet Python to add objects, control joint motors etc.

At some stage I hope to find time to document this properly, but until then, please try it out and try out pybullet and read those minimal instructions: Minimal instructions for pybullet and VR by Erwin.

The URDF and SDF format used in VR/pybullet is very simple xml that adds physics parameters and allows you to use .obj, .stl or COLLADA .dae graphics/collision representations. See ROS Tutorials and Specification. Although this is robotics oriented, it is also suitable for games I think.

I'll upload some Windows executable + Python distribution + pybullet plugin all precompiled, with the data assets, to make it really easy to try it out, given HTC Vive and/or Oculus Rift + Touch.

A few more interesting details about the Bullet VR demo:

  1. physics runs in its own thread, with non-blocking synchronization with the graphics
  2. pybullet Python can connect using such Python scripts:
  3.    import pybullet as p
  4. Physics runs at 240 Hz, 100 constraint solver iterations, everything simulated as btMultiBody. This is mainly for robotics quality, it can be tuned towards games too.
  5. Graphics runs as fast as possible, with VSYNC disabled. For best experience use an NVIDIA GTX1080, and don't spawn too many extra objects.

The VR demo will become better over time, and also allows to create new scenes (basic physics world editor)


Personal tools