Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dfki-ric/uxo-dataset2024/llms.txt

Use this file to discover all available pages before exploring further.

This guide will help you install the necessary dependencies to work with the UXO Dataset 2024, including viewing, processing, and analyzing the data.

​
System Requirements

Before installing, ensure your system meets the following requirements:

Python

Python 3.8 or higher recommended

Operating System

Linux, macOS, or Windows
Some preprocessing scripts require ROS1 (Robot Operating System). For these scripts, Ubuntu 20.04 with ROS Noetic is recommended, or use robostack to set up a ROS1 environment.

​
Installation Steps

1

Clone the Repository

First, clone the UXO Dataset 2024 processing scripts repository:
git clone https://github.com/dfki-ric/uxo-dataset2024.git
cd uxo-dataset2024
2

Create Virtual Environment (Recommended)

Create and activate a Python virtual environment to isolate dependencies:
python3 -m venv venv
source venv/bin/activate
3

Install Python Dependencies

Install the required Python packages from requirements.txt:
pip install -r requirements.txt
This will install the following key dependencies:
  • ffmpeg (1.4) - Video processing
  • matplotlib (3.9.0) - Data visualization
  • numpy (2.0.1) - Numerical computing
  • pandas (2.2.2) - Data manipulation
  • PyQt5 (5.15.11) - GUI framework for the viewer
  • pytransform3d (3.5.0) - 3D transformations
  • PyYAML (6.0.1) - YAML file parsing
  • scipy (1.14.0) - Scientific computing
  • tqdm (4.66.2) - Progress bars
4

Install OpenCV

OpenCV is required for image processing but may need to be installed separately:
pip install opencv-python
5

Verify Installation

Verify that all dependencies are installed correctly:
python -c "import cv2, yaml, pandas, PyQt5; print('All dependencies installed successfully')"
If this command runs without errors, you’re ready to use the dataset tools.

​
ROS1 Setup (Optional)

ROS1 is only required if you plan to run preprocessing scripts that extract data from ROS bag files (e.g., prep_5_gantry_extract.py). If you’re only viewing or analyzing the exported dataset, you can skip this section.
For scripts that interact with ROS1 bag files:

​
Option 1: Ubuntu 20.04 with ROS Noetic

If you’re running Ubuntu 20.04, install ROS Noetic: 
# Add ROS repository
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'

# Add keys
sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654

# Install ROS Noetic
sudo apt update
sudo apt install ros-noetic-desktop-full

# Initialize rosdep
sudo rosdep init
rosdep update

​
Option 2: Docker Container

Use an Ubuntu 20.04 Docker container with ROS1: 
docker pull ros:noetic
docker run -it --rm -v $(pwd):/workspace ros:noetic bash

​
Option 3: Robostack

Use robostack to set up ROS1 in a conda environment: 
conda create -n ros_env python=3.9
conda activate ros_env
conda install -c robostack ros-noetic-desktop

​
Configuration

The processing scripts use a configuration file located at scripts/config.yaml. This file contains paths and settings for data processing.
The configuration file includes settings for:
  • Input/output paths for ARIS, gantry, and GoPro data
  • Image formats and compression settings
  • Polar transformation methods and resolution
  • Optical flow calculation parameters
  • Export settings for the dataset
You generally don’t need to modify this file unless you’re reprocessing the raw data.

​
Troubleshooting

If you encounter issues installing PyQt5, especially on Linux:
# Install system dependencies first
sudo apt-get install python3-pyqt5
Or use conda:
conda install pyqt
If you get ImportError: libGL.so.1 on Linux:
sudo apt-get install libgl1-mesa-glx
If you encounter video codec errors:
# Install system FFmpeg
sudo apt-get install ffmpeg  # Linux
brew install ffmpeg          # macOS

​
Next Steps

Now that you have the dependencies installed:

View the Data

Learn how to use the dataset viewer

Dataset Structure

Understand the organization of the dataset

Build docs developers (and LLMs) love

Get started for freeTalk to us