ODE Plugin¶

Overview ¶

About ODE¶

Open Dynamics Engine (ODE) is an open-source rigid body dynamics library. It is one of the physics engines with a long history and has a track record of use in various applications including the robotics field.

About the ODE Plugin¶

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

In version 2.5.0, this plugin has also been improved, and a full set of simulator item features is now available, including support for contact materials, self collisions, and extra joints.

Note that compared to the physics engines of the PhysX and MuJoCo plugins, which are built by default, ODE is inferior in some aspects of functionality and performance. Unless you have a specific reason, it is recommended to consider using those engines or the AIST simulator first, but this plugin is useful when you want to check behaviors with ODE or when you have existing assets that assume ODE.

Setup ¶

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

On Ubuntu, it can be installed with the following command (it is already installed if you are using the package installation script of Choreonoid).

sudo apt install libode-dev

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

Building on Windows¶

To use the ODE plugin on Windows, first build and install the ODE library from source. The ODE source archive can be downloaded from the download page in Bitbucket.

Extract the downloaded archive and execute the following commands in the ODE source directory.

cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release -- -m
cmake --install build --config Release --prefix c:/local/ODE

This operation installs the built ODE library under “C:\local\ODE”. The default installation destination is “C:\Program Files\ODE”, and it is also OK to install there (in that case, administrator privileges are required).

If ODE is installed in one of these directories, ODE is automatically detected in the CMake configuration of Choreonoid and BUILD_ODE_PLUGIN becomes ON by default. If you have installed it in another directory, set that directory to the CMake ODE_DIR variable.

Using the ODE Simulator ¶

When the ODE plugin is loaded, the “ODESimulator” becomes available as a simulator item. Create it from the main menu with “File” - “New” - “ODESimulator”, 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 ODE simulator supports the following features:

Actuation modes: torque command (JointEffort) and velocity command (JointVelocity)
Simulation of force sensors, acceleration sensors, and angular velocity sensors (rate gyros)
Setting friction and restitution coefficients with Contact Materials
Self collisions within body models (following the settings on the model side)
Extra joints, including constraints across different bodies ( Setting Extra Joints )
Simulation of pseudo continuous tracks and conveyors based on surface velocity

Note that actuation with position commands (JointDisplacement) is not supported. For position control, convert it into torque or velocity commands on the controller side, for example with PD control.

Properties¶

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

Property	Default value	Meaning
Step mode	Iterative (quick step)	Selects the stepping method of the dynamics computation. “Iterative (quick step)” uses the iterative solver (dWorldQuickStep), which computes fast. “Big matrix” uses the direct solver (dWorldStep), which is more accurate but computationally more expensive.
Collision space type	Simple	Selects the spatial data structure used in the ODE collision detection from “Simple”, “Hash”, and “Sweep and prune”. Simple is sufficient when the number of objects is small; the other types may be faster when there are many objects.
Gravity	0 0 -9.80665	The gravitational acceleration vector [m/s^2].
Friction	1.0	The friction coefficient of contacts. For pairs of objects for which the friction coefficient is set by contact materials, that value is used instead.
Limit joint range	false	Sets the joint ranges of motion of the models as ODE joint limits so that the joints are constrained within the ranges.
Add joint-axis inertia to link inertia	false	Approximately reflects the equivalent rotor inertia set in the models by adding it to the link inertia around the joint axes (see Setting the Rotor Inertia ).
Global ERP	0.4	The ERP (Error Reduction Parameter) of the whole ODE world. Specifies the ratio of correcting constraint errors in the range of 0 to 1.
Global CFM	1.0e-10	The CFM (Constraint Force Mixing) of the whole ODE world. Specifies the degree of softening the constraints.
Iterations	50	The number of solver iterations when the step mode is “Iterative (quick step)”.
Over relaxation	1.3	The SOR (successive over-relaxation) coefficient of the iterative solver. Specify in the range of 0.1 to 1.9.
Limit correcting vel.	true	Applies an upper limit to the velocity for correcting the penetration of contacts.
Max correcting vel.	0.01 [m/s]	The upper limit of the penetration correction velocity. It is used when “Limit correcting vel.” is enabled.
Surface drive culling depth	0.005 [m]	The threshold for not applying the drive to contact points whose penetration depth exceeds this value in the surface-velocity-based drive (pseudo continuous tracks, etc.). When 0 is set, this culling is not performed.
2D mode	false	Performs the simulation with the motions of the objects constrained in a 2D plane.
Use WorldItem’s Collision Detector	false	Uses the collision detector selected in the world item instead of the built-in collision detection of ODE.

Samples ¶

No samples dedicated to the ODE plugin are provided, but for many of the general simulation samples bundled with Choreonoid ( sample/SimpleController/ etc.), you can simulate them with ODE by replacing the simulator item in the project with the ODE simulator.