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)
   • see Docker Native Version section
4. VNC Docker
   • see Docker VNC Version section
5. Gitpod
   • open https://app.gitpod.io/#https://github.com/rustlluk/pycub and log in with GitHub account
     • then open a port 6080 and in terminal run start-vnc-session.sh to start the VNC server
       • if using VScode browser version, on top left click on three lines -> Terminal -> New Terminal

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

• documentation can be found at https://lukasrustler.cz/pyCub/documentation or in pycub.pdf
• presentation with description of functionality can be found at pycub presentation
• simulator code is in pycub.py
  • it uses PyBullet for simulation and provides high-level interface
• visualization code in visualizer.py
  • it uses Open3D for visualization as it is much more customizable than PyBullet default GUI

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)
   • perform post-installation steps
2. 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

• this version works also on Windows and MacOS because it uses VNC server to show the GUI, i.e., the output will be shown on http://localhost:6080

1. Install docker-engine (GNU/Linux only) or docker-desktop (all systems)
   • perform post-installation steps
2. The same as for Native Version, but use -vnc option, e.g., to pull and run the image

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

3. run start-vnc-sessions.sh script in the container
4. Open http://localhost:6080

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

1. 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

• visualization with skin dies after ~65k steps
  • e.g., https://github.com/isl-org/Open3D/issues/4992

License

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