Bullet Plugin

Overview

About Bullet

Bullet Physics is an open-source (zlib license) physics library. It has a long track record of use in games and video production, and in the field of robotics it is also widely used in learning research through PyBullet, its Python binding.

Bullet is a general-purpose physics engine for rigid and soft bodies, but as a functionality for handling articulated robots, it also provides the multibody (btMultiBody) features that solve the equations of motion in the joint coordinate space based on the Featherstone’s method.

About the Bullet Plugin

The Bullet plugin of Choreonoid is a plugin for using Bullet as a physics engine of Choreonoid. It provides the “BulletSimulator” as a simulator item, which can be used in the same way as the simulator items of the other physics engines.

This plugin is implemented based on the multibody dynamics functionality of Bullet, and can handle articulated robots stably in the joint coordinate space like the AIST simulator. The standard body models handled by Choreonoid can be used as they are, and position control, velocity control, and torque control are all supported.

The plugin also supports PiecewiseRigidContinuousTrack (piecewise rigid continuous track), the continuous track (crawler) device shared with the PhysX plugin, so continuous track simulations of tracked robots can be performed. For details, see Piecewise Rigid Simulation of Continuous Tracks.

Note

The Bullet plugin included in previous versions of Choreonoid had remained an experimental implementation from more than ten years ago. In version 2.5.0, it has been re-implemented from scratch for the current version of Bullet and has become a practically usable plugin.

Setup

To build and use the Bullet plugin, the Bullet library must be installed.

On Ubuntu, the package installation script used in Installing Dependent Packages includes the Bullet package (libbullet-dev), so it is already installed if you have followed that procedure. To install it individually, execute the following command.

sudo apt install libbullet-dev

In an environment where Bullet is installed, Bullet is automatically detected in the CMake configuration of Choreonoid and the CMake option BUILD_BULLET_PLUGIN becomes ON by default. Therefore, just by following the normal build procedure, the Bullet plugin is also built. If Bullet is installed but you do not want to build the plugin, explicitly turn this option OFF.

If you want to use your own build of the Bullet library, set its installation directory to the CMake BULLET_DIR variable. To use this plugin on Windows, build and install Bullet from source and specify it with this method. When using a Bullet built with double precision, set BULLET_USE_DOUBLE_PRECISION to ON in CMake.

Using the Bullet Simulator

When the Bullet plugin is loaded, the “BulletSimulator” becomes available as a simulator item. Create it from the main menu with “File” - “New” - “BulletSimulator”, and place it as a child item of the world item following the procedure explained in Creating a Simulation Project. The basic usage is common to the other simulator items.

Supported Features

The Bullet simulator supports the following features:

• Actuation modes: torque command (JointEffort), velocity command (JointVelocity), and position command (JointDisplacement)

• Simulation of force sensors, acceleration sensors, and angular velocity sensors (rate gyros)

• State output of link velocities, accelerations, and drive efforts (enabled with the corresponding properties)

• Setting friction and restitution coefficients with Contact Materials

• Extra joints ( Setting Extra Joints )

• Simulation of pseudo continuous tracks and conveyors based on surface velocity

• Continuous track simulation with the PiecewiseRigidContinuousTrack device ( Piecewise Rigid Simulation of Continuous Tracks )

• Simulation of the equivalent rotor inertia set in models (with virtual geared rotor links; Setting the Rotor Inertia )

Properties

In addition to Properties Common to Simulator Items, the following properties are available in the Bullet simulator item.

Property	Default value	Meaning
Gravity	0 0 -9.80665	The gravitational acceleration vector [m/s^2].
Solver	Sequential impulse	Selects the constraint solver from “Sequential impulse” and “MLCP (Dantzig)”.
Solver iterations	50	The maximum number of iterations of the solver.
Contact ERP	0.2	The ERP (Error Reduction Parameter) for correcting the penetration of contacts. Specify in the range of 0 to 1.
Position gain	1.0	The gain of the motor constraints used for driving joints with position commands. Specify in the range of 0 to 1.
Velocity gain	1.0	The gain of the motor constraints used for driving joints with velocity commands. Specify in the range of 0 to 1.
Linear damping	0.0	The damping coefficient applied to the translational motion of rigid bodies.
Angular damping	0.0	The damping coefficient applied to the rotational motion of rigid bodies.
Collision margin	0.001 [m]	The margin applied to the Bullet collision shapes.
GImpact meshes for dynamic objects	false	Treats the concave mesh shapes of moving objects as GImpact meshes. When disabled, they are converted into convex shapes.
Internal edge smoothing	true	Suppresses unnatural contact reaction forces caused by the internal edges of meshes.
Self collision	false	Enables self collisions within body models by default.
Rotor inertia	true	When the equivalent rotor inertia is set in a model, simulates its effect using virtual geared rotor links.
Default rotor gear ratio	100.0	The gear ratio used in the rotor inertia simulation when a model does not provide the gear ratio information.
Velocity output	false	Outputs the link velocities as simulation results.
Acceleration output	false	Outputs the link accelerations as simulation results.
Drive effort output	false	Writes back the torque (or force for a prismatic joint) actually used for driving each joint as the joint effort value.

Samples

Sample projects that can use the Bullet plugin are provided in the choreonoid/sample/PiecewiseRigidContinuousTrack/ directory as samples of continuous track simulation. These samples contain both the Bullet simulator and the PhysX simulator items, and you can select which simulator to use for the simulation. For the contents of the samples, refer to the Samples section of PhysX Plugin.

In addition, for many of the general simulation samples bundled with Choreonoid ( sample/SimpleController/ etc.), you can also simulate them with Bullet by replacing the simulator item in the project with the Bullet simulator.