Installation Guide#
Compatability#
CoraPlex is compatible and tested with ROS2 Jazzy/ Ubuntu24.04 and Python 3.12.
CoraPlex and ROS#
While CoraPlex works on its own and is not dependent on ROS to work some of its functionallity requires a ROS environment. This includes:
Loading URDFs
Using the visualization with RVIZ2
Synchronizing between different processes
This is especially required to run the examples
Installation with Pip#
The easiest way to install CoraPlex is via Pip. For this first setup a virtual environment using the following command:
python3 -m venv coraplex-venv --system-sitepackages
Then just activate the environment and install CoraPlex
source coraplex-venv/bin/activate
pip install coraplex
Installation for Development#
For development it is recommended to use the virtualenvwrapper package to setup the virtual environment. To install the virtualenvwrapper just execute the following command:
Set virtualenvwrapper’s WORKON_HOME env variable, of which the default value is ~/.virtualenvs
echo "export WORKON_HOME=~/envs" >> ~/.bashrc
mkdir -p $WORKON_HOME
Activate virtualenvwrapper at terminal start
echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc
source ~/.bashrc
Create a virtual env based on the workspaces libraries (see build-ws_) and add the –system-site-packages to get them properly. The env will be registered in $WORKON_HOME.
mkvirtualenv coraplex --system-site-packages
ls $WORKON_HOME
Now you can activate the venv from anywhere using the command:
workon coraplex
Afterwards clone the CoraPlex github repo and install it into the venv.
git clone git@github.com:cram2/coraplex.git
pip install -e coraplex
Remeber that the git clone command requires you to have a valid ssh-key in your GitHub account (you can read about adding a new ssh key here).
Using PyCharm#
We recommend using PyCharm for development. PyCharm might have trouble finding ROS dependencies since they are not added to the PYTHON_PATH by default. To solve this problem start PyCharm from a terminal in which ROS is sourced.
source /opt/ros/jayyz/setup.bash
pycharm
Instead of “pycharm” the command could also be “pycharm-professional” that depends on your installation. Just use <TAB> to autocomplete.
Install ROS Dependencies#
To execute the examples or tests of CoraPlex you need to setup a ROS environment and the dependency packages that are needed by ROS. For your convenience there is a script to install ROS and setup the dependencies for CoraPlex
curl -s https://raw.githubusercontent.com/cram2/coraplex/dev/scripts/setup_ros.sh | bash
Appendix#
The instructions here are not needed to work with CoraPlex and are just additional info.
If you installed CoraPlex and checked that the installation works you can continue with the next step of setting up your development environment by following the link here.
Manual Setup#
If you already have a ROS setup you are probably already aware how to install and build ROS packages. In that case you need install and build these two ROS packages:
Make sure to select the correct branch for ros-jazzy
Building the documentation#
The documentation uses jupyter-book as engine. Building the documentation requires Python 3.9 or higher to avoid dependency conflicts.
Source the venv that contains CoraPlex
source coraplex-venv/bin/activate
Install the requirements in your python interpreter.
cd <path-to-repo>/doc
pip install -r requirements.txt
Run coraplex and build the docs.
cd <path-to-repo>/doc/source
jupyter-book build .
Show the index.
firefox _build/html/index.html