pyCub Documentation

pyCub is iCub humanoid robot simulator written in Python. It uses PyBullet for simulation and Open3D for visualization.

Installation

  • Requires python3.10 to 3.12

    • newer python versions are now not supported due to incompatible with some dependencies

  • We recommend using virtual environment when installing from PyPi or from source

    • python3 -m venv pycub_venv
source pycub_venv/bin/activate
OTHER_COMMANDS

  1. (Recommended) Install from PyPi

    • python3 -m pip install icub_pybullet

  2. Install from source

    • Pull this repository

    • cd PATH_TO_THE_REPOSITORY/icub_pybullet
python3 -m pip install --upgrade pip
python3 -m pip install .

  3. Native Docker (GNU/Linux only)

  4. VNC Docker

  5. Gitpod

Examples

  • push_the_ball_pure_joints.py contains an example that shows how to control the robot in joint space

  • push_the_ball_cartesian.py contains an example that shows how to control the robot in Cartesian space

  • skin_test.py contains an example with balls falling the robot and skin should turn green on the places where contact occurs. You may want to slow the simulation a little bit to see that :)

Information

FAQ

  1. You get some kind of error with the visualization, e.g., segmentation fault.

    1. Try to check graphics mesa/opengl/nvidia drivers as those are the most common source of problems for the openGL visualization

    2. Try Native Docker

    3. In given config your load set in GUI standard=False; web=True to enable web visualization

    4. Try VNC Docker

    5. Try Gitpod Docker

  2. You get import errors, e.g. cannot load pycub from icub_pybullet

    1. Install from pip with python3 -m pip install icub_pybullet

    2. Install the package correctly with python3 -m pip install . from icub_pybullet directory of this repository

    3. put icub_pybullet directory to your PYTHONPATH

Docker

Native Version

  • version with native GUI; useful when you have problems with OpenGL (e.g., usually some driver issues)

  • only for GNU/Linux systems (Ubuntu, Mint, Arch, etc.)

    1. install docker-engine (DO NOT INSTALL DOCKER DESKTOP)

    1. Build/Pull the Docker Image

    • clone this repository

      cd SOME_PATH
git clone https://github.com/rustlluk/pyCub.git

    • pull the docker image (see Parameters for more parameters)

      cd SPATH_TO_THE_REPOSITORY/Docker
./deploy.py -p PATH_TO_THE_REPOSITORY -c pycub -pu

    • or, build the docker (see Parameters for more parameters)

      cd SOME_PATH/pycub_ws/Docker
./deploy.py -p PATH_TO_THE_REPOSITORY -c pycub -b

    • after you pull or build the container, you can run it next time as

      ./deploy.py -c pycub -e

    • if you want to open new terminal in existing container, run

      ./deploy.py -c pycub -t

VNC Version

Docker + PyCharm

Native Version:

You have two option:

  1. Either run pycharm from docker

  2. Open your pycharm on your host machine:

    • add ssh interpreter

      • user docker

      • ip can be localhost or ip where you run the docker

      • port 2222

    • uncheck automatic upload to remote folder

    • change remote path to /home/docker/pycub_ws
       #### VNC/Gitpod version

  3. open pycharm from inside the container

Deploy Parameters

  • cd to folder with Dockerfile

  • ./deploy.py

    • -b or --build when building

      • default: False

    • -e if you just want to run existing docker without building

      • default: False

    • -p or --path with path to current folder

      • default: “”

    • -pu or --pull to pull the image from dockerhub

      • default: False

    • -c or --container with desired name of the new, created container

      • default: my_new_docker

    • -t or --terminal to run new terminal in running docker session

      • default: False

    • -pv or --python-version to specify addition python version to install

      • default: 3.11

    • -pcv or --pycharm-version to specify version of pycharm to use

      • default: 2023.2.3

    • -bi or --base-image to specify base image that will be used

      • default: ubuntu:20.04

      • other can be found at hub.docker.com

    Do this on computer where you will run the code. If you have a server you have to run it on the server over SSH to make things work properly.

Docker FAQ

  • you get error of not being in sudo group when running image

    • check output of id -u command. If the output is not 1000 you have to build the image by yourself and can not pull it

      • this happens when your account is not the first one created on your computer

  • ``sudo apt install something`` does not work

    • you need to run sudo apt update first after you run the container for the first time

      • apt things are removed in Dockerfile, so it does not take unnecessary space in the image

Known bugs

License

` .. image:: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg

This work is licensed under a Creative Commons Attribution 4.0 International License.

` .. image:: https://i.creativecommons.org/l/by/4.0/88x31.png

Exercises

icub_pybullet

Examples