RaiSimPy: Python wrapper for RaiSim

This folder contains python wrappers around RaiSim (raisimLib and raisimOgre) using pybind11.

Small parts of the wrappers were inspired by the code given in the raisimGym/raisim_gym/env/ folder. If you use these wrappers, please acknowledge their contribution as well by citing [1-4].

The following wrappers have been tested on Ubuntu 16.04 with Python 3.5 and 2.7. Other platforms and Python versions might work as well but we didn't test them yet.

How to use the wrappers?

In order to use the wrappers, you will have to install at least raisimLib and raisimOgre. You will also have to install pybind11 as we use this to wrap the C++ code.

If you followed the installation procedure of raisimLib and/or raisimOgre, you will have the two following environment variables defined:

• WORKSPACE: workspace where you clone your git repos (e.g., ~/raisim_workspace)
• LOCAL_BUILD: build directory where you install exported cmake libraries (e.g., ~/raisim_build)

First, clone this repository:

cd $WORKSPACE
git clone https://github.com/robotlearn/raisimpy
cd raisimpy

Then, compile the python wrappers from the raisimpy folder by typing:

mkdir build && cd build
cmake -DPYBIND11_PYTHON_VERSION=$PYTHON_VERSION -DCMAKE_PREFIX_PATH=$LOCAL_BUILD -DCMAKE_INSTALL_PREFIX=$LOCAL_BUILD ..
make -j4
make install

where $PYTHON_VERSION is the Python version you wish to use (e.g. PYTHON_VERSION=3.5).

Now, you just need to export PYTHONPATH=$PYTHONPATH:$LOCAL_BUILD/lib to be able to access the python library. You can add this export line in your bashrc.

Once it has been compiled, you can access to the Python library raisimpy in your code with:

import raisimpy as raisim

print(dir(raisim))

We mostly follow the naming convention defined in raisimLib and raisimOgre, however we follow the PEP8 guideline. Thus, a C++ method like:

getComPosition()

becomes

get_com_position()

Note that in the original raisimLib, the authors sometimes use their own defined data types for vectors and matrices (such as Vec<n>, Mat<n,m>, VecDyn, MatDyn, etc). The Ogre library used for the visualization also uses its own defined data types (such as Vector3, Matrix3, Quaternion, etc). When using raisimpy, these datatypes are automatically converted (back and forth) to numpy arrays as this is the standard in Python. We also follow the convention that if an attribute is a python list or std::vector, we add the suffix 's' at the end of the attribute, and we write the full name of the variables (i.e. without using diminutives), such as:

Body b;
std::vector<Shape::Type> shapes = b.colshape;

in C++, becomes in Python:

b = Body()
shapes = b.collision_shapes  # no diminutives (colshape --> collision_shape), and added the 's' suffix to specify it is a list.

The code has been documented, so you can always see it using help or ?, for instance:

import raisimpy as raisim

world = raisim.World()
world.add_sphere?
# or
help(world.add_sphere)

Examples

Here is the C++ example that was provided in the README in [2]:

#include "raisim/World.hpp"

int main() {
    raisim::World world;
    auto anymal = world.addArticulatedSystem("pathToURDF"); // initialized to zero angles and identity orientation. Use setState() for a specific initial condition
    auto ball = world.addSphere(1, 1); // radius and mass
    auto ground = world.addGround();

    world.setTimeStep(0.002);
    world.integrate();
}

This becomes in Python:

import raisimpy as raisim

world = raisim.World()
anymal = world.add_articulated_system("path_to_urdf")
ball = world.add_sphere(radius=1, mass=1)
ground = world.add_ground()

world.set_time_step(0.002)
world.integrate()

Other examples can be found in the examples folder, which are the sames as the ones that you can find in the examples folders in raisimLib [2], raisimOgre [3], and raisimGym [4]. I will add the other examples as soon as I have the time.

References

• [1] "Per-contact iteration method for solving contact dynamics", Hwangbo et al., 2018
• [2] raisimLib: https://github.com/leggedrobotics/raisimLib
• [3] raisimOgre: https://github.com/leggedrobotics/raisimOgre
• [4] raisimGym: https://github.com/leggedrobotics/raisimGym
• [5] pybind11: https://pybind11.readthedocs.io/en/stable/

Troubleshooting

• fatal error: Eigen/*: No such file or directory

  • If you have Eigen3 installed on your system, you probably have to replace all the #include <Eigen/*> by #include <eigen3/Eigen/*>. You can create symlinks to solve this issue:

  cd /usr/local/include
  sudo ln -sf eigen3/Eigen Eigen
  sudo ln -sf eigen3/unsupported unsupported

  or you can replace the #include <Eigen/*> by #include <eigen3/Eigen/*>.

• Segmentation fault. This is probably an oversight on my part, the error is probably due to some poor management of pointers and memory allocation. E.g. an object has been deleted from the Python side but the C++ side is also trying to delete it. Just open an issue on Github, and I will fix it as soon as I can. If you fixed it, you can submit a pull request.

• Error about adress mapping while running RL examples, like the following one:

  Signal: Segmentation fault (11)
  Signal code: Address not mapped (1)
  Failing at address: xxxxx

  this seems to be caused by TensorFlow, but I have to investigate deeper what causes that error.

LICENSE

The following software is distributed under the MIT License, however the RaiSim software is under the End-User License Agreement that you can find here.

Citation

If the code presented here was useful to you, we would appreciate if you could cite the original authors:

@article{hwangbo2018per,
    title={Per-contact iteration method for solving contact dynamics},
    author={Hwangbo, Jemin and Lee, Joonho and Hutter, Marco},
    journal={IEEE Robotics and Automation Letters},
    volume={3},
    number={2},
    pages={895--902},
    year={2018},
    publisher={IEEE}
}

If you still have some space in your paper for the references, you can add the following citation:

@misc{delhaisse2019raisimpy
    author = {Delhaisse, Brian and Rozo, Leonel},
    title = {RaiSimPy: A Python wrapper for RaiSim},
    howpublished = {\url{https://github.com/robotlearn/raisimpy}},
    year=2019,
    }

Otherwise, you can just add me in the acknowledgements ;)

If you use raisimpy through the pyrobolearn framework (this is an ongoing work), you can cite this last one instead (but you still have to cite the authors of RaiSim).