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:
sudo apt install virtualenvwrapper
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/jazzy/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.
Setup your Development Environment#
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.10 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>
pip install -e ".[doc]"
Run coraplex and build the docs.
cd <path-to-repo>/doc/source
jupyter-book build .
Show the index.
firefox _build/html/index.html