Installation

The simulation runs on Ubuntu 24.04 with ROS2 Jazzy and Gazebo Harmonic.

The easiest and OS-independent way to work with the simulation is the provided dev container (.devcontainer/): open the repository in VS Code (or any tool supporting dev containers) and “Reopen in Container”. This works on Linux, macOS and Windows and provides the full ROS2 + Gazebo toolchain.

For a native install on Ubuntu 24.04, run ./init/init.sh (see below).

Prerequisites

  • kitcar-python-utils: If not installed already, follow the steps described in GitLab before proceeding.

Clone

The first step is of course to clone the repository. These are some ways to get it:

  • KITcar internal. Clone this repository in the same directory as kitcar-ros.

    git clone git@git.kitcar-team.de:kitcar/kitcar-gazebo-simulation.git $KITCAR_REPO_PATH/kitcar-gazebo-simulation

$KITCAR_REPO_PATH

The environment variable $KITCAR_REPO_PATH must contain the directory in which you’ve cloned kitcar-gazebo-simulation.

Make sure that $KITCAR_REPO_PATH is set to the directory where you’ve cloned kitcar-gazebo-simulation into:

cd $KITCAR_REPO_PATH/kitcar-gazebo-simulation

should put you into the root directory of kitcar-gazebo-simulation.

If it doesn’t work, create the variable with:

export KITCAR_REPO_PATH=<DIRECTORY WHERE kitcar-gazebo-simulation IS>

Adding

export KITCAR_REPO_PATH=<DIRECTORY WHERE kitcar-gazebo-simulation IS>

to your .bashrc ensures that the path is always set.

Python

ROS2 Jazzy targets Python 3.12 (the default on Ubuntu 24.04). Verify with:

python3 -V

Python dependencies are managed with uv and declared in pyproject.toml (locked in uv.lock). ./init/init.sh installs uv automatically; the dev container ships with it. To install it manually:

curl -LsSf https://astral.sh/uv/install.sh | sh

ROS

ROS must also be installed on your machine. If it’s not yet installed, follow the installation guide.

Init-Script

To install the system packages (ROS2 Jazzy, Gazebo Harmonic) and the Python dependencies, run the init script. Change into the kitcar-gazebo-simulation folder and run:

cd $KITCAR_REPO_PATH/kitcar-gazebo-simulation
./init/init.sh

It installs uv, creates a .venv (with system site-packages so ROS2’s rclpy stays visible), and runs uv sync to install the locked dependencies.

The dependencies are split into optional extras in pyproject.toml: ml (PyTorch / CycleGAN), dev (linting, pre-commit, DVC) and docs (Sphinx). The init script always installs dev and asks about ml; none of the extras are needed to run the basic simulation. To (re-)install an extra later:

uv sync --extra ml      # or: --extra docs / --all-extras

Build

Then build the workspace by calling colcon build in the simulation folder of this repository:

cd $KITCAR_REPO_PATH/kitcar-gazebo-simulation/simulation
python3 -m colcon build --symlink-install
source install/setup.bash

Note

Build with python3 -m colcon (not bare colcon) so that the generated node entry-point scripts use the uv venv’s Python interpreter that carries the project’s dependencies (shapely, etc.). Activate the venv first (source .venv/bin/activate). The dev container and init/init.sh do this for you.

Automatic-drive demo (no brain)

To see the car drive itself along the road without the KITcar brain:

# headless
./simulation/scripts/automatic_drive_demo.sh
# or, with the Gazebo GUI (needs a display / Xvfb)
ros2 launch gazebo_simulation automatic_drive_demo.launch.py gui:=true

Git Lfs

Images and other binary files used within Gazebo are tracked using Git LFS, to download them locally, you need to pull them:

git lfs pull

For installing our fonts on your system you need to run:

sudo mkdir -p /usr/local/share/fonts/kitcar/
sudo cp -a "$KITCAR_REPO_PATH/kitcar-gazebo-simulation/simulation/models/fonts/." /usr/local/share/fonts/kitcar/

Data Version Control (DVC)

Datasets, machine learning models and similar are stored within a DVC container. DVC is designed to bring version control to the world of machine learning and large datasets. It integrates well with git. If you have set up your credentials as described in our WIKI , you can download all our datasets (very large, approx. 10 Gb) just execute:

dvc pull

This is only necessary if you want to train or test our neural networks.

If you are not part of KITcar, you cannot download our datasets. However, you can either setup your DVC server or simply use DVC locally. See DVC.org for more details. Our pipelines used to train and test models or extract datasets from the simulation will still work.

kitcar-rosbag

This is only required by some scripts to record rosbags in the simulation.

  • KITcar internal. Clone kitcar-rosbag in the same directory as kitcar-ros.

    git clone git@git.kitcar-team.de:kitcar/kitcar-rosbag.git $KITCAR_REPO_PATH/kitcar-rosbag

    Then follow the installation steps there.

Test

Let’s test if everything works. Open up a new terminal.

You can now start the simulation with

ros2 launch gazebo_simulation master.launch.py road:=default_road

Gazebo should now open with the car and a road.

Troubleshooting

  • Gazebo isn’t shown correctly

    This might be due to your graphics driver causing problems. Try to set

    export LIBGL_ALWAYS_SOFTWARE=1

    For further information take a look here.