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.

The UXO Dataset 2024 includes a convenient viewer script that allows you to step through recordings and visualize synchronized sonar, camera, and trajectory data.

​
The Dataset Viewer

The view_recording.py script provides an interactive Qt-based GUI for exploring the dataset. It displays:
  • ARIS sonar frames (raw or polar-transformed)
  • Synchronized GoPro camera frames
  • Gantry trajectory and pose information
  • Frame and file metadata
  • Recording notes

​
Basic Usage

To view a recording, use the following command: 
python scripts/view_recording.py data_export/recordings/<target_type>/<recording-folder>

​
Example

python scripts/view_recording.py data_export/recordings/mine_type_1/recording_001
Replace <target_type> and <recording-folder> with the actual paths from your downloaded dataset.

​
Command-Line Options

The viewer supports several command-line arguments to customize the display:
​
recording_dir
string
required
Path to the recording directory to view
​
-p, --polar
boolean
default:"true"
Display polar-transformed sonar images instead of raw sonar data. Use --no-polar to view raw frames.
​
-c, --colorize
boolean
default:"true"
Apply colormap to sonar images for better visualization. Use --no-colorize for grayscale.
​
-l, --use-lru-cache
boolean
default:"false"
Enable LRU caching to speed up navigation by keeping frames in memory. Useful for repeated viewing.

​
Usage Examples

python scripts/view_recording.py data_export/recordings/mine_type_1/recording_001

​
Viewer Interface

The viewer window is divided into several sections:
1

Sonar Display (Left)

Shows the ARIS sonar frame for the current position. By default, displays polar-transformed images with a colormap applied (TWILIGHT_SHIFTED).
2

Camera Display (Top Right)

Shows the synchronized GoPro camera frame corresponding to the current sonar frame.
3

Position Information

Displays the current frame index and position in the recording (e.g., “Frame 42 (1 / 150)”).
4

Trajectory Information

Shows gantry crane position data including transforms between sonar and targets.
5

Metadata Panels (Bottom)

Three information boxes display:
  • Notes: Recording-specific notes from notes.txt
  • File Metadata: Recording-level ARIS configuration from aris_file_meta.yaml
  • Frame Metadata: Per-frame ARIS parameters from aris_frame_meta.csv

​
Keyboard Controls

Navigate through the recording using keyboard shortcuts:
​
Arrow Keys
navigation
​
Q
action
Quit the viewer
You can also use the slider at the bottom of the window to jump to specific frames directly.

​
Understanding the Display

​
Sonar Visualization

The ARIS sonar data can be displayed in two formats:
Polar-transformed images represent what the sonar was actually “seeing” - the acoustic image projected into a 2D plane. This format is more intuitive for human interpretation.
  • Resolution: 1000 pixels per meter (configurable)
  • Format: PNG with compression
  • Colormap: TWILIGHT_SHIFTED (can be disabled with --no-colorize)

​
Camera Frames

GoPro frame label coordinates should be multiplied by 3 for correct scaling due to the downsampling process.
The GoPro frames are:
  • Extracted from UHD (5.3K) source footage
  • Downsampled to Full HD (1920x1080) for export
  • Synchronized with sonar frames via motion matching
  • Saved as individual JPEG files indexed by ARIS frame number

​
Trajectory Data

The gantry information panel shows:
  • Position and orientation of the gantry crane
  • Accurate transforms between sonar and UXO targets
  • Timestamps synchronized with ARIS frame indices

​
Advanced Usage

​
Enabling Frame Caching

For faster navigation when repeatedly viewing the same frames: 
python scripts/view_recording.py data_export/recordings/mine_type_1/recording_001 --use-lru-cache
This uses Python’s LRU (Least Recently Used) cache to keep frames in memory.
Caching increases memory usage but significantly improves performance when jumping back and forth between frames.

​
Viewing Multiple Recordings

To compare different recordings, open multiple viewer instances: 
# Terminal 1
python scripts/view_recording.py data_export/recordings/mine_type_1/recording_001

# Terminal 2
python scripts/view_recording.py data_export/recordings/mine_type_1/recording_002

​
Troubleshooting

Ensure PyQt5 is properly installed:
pip install PyQt5
On Linux, you may need system dependencies:
sudo apt-get install python3-pyqt5
Verify the recording directory structure:
ls data_export/recordings/<target_type>/<recording-folder>/
Required directories:
  • aris_polar/ or aris_raw/
  • gopro/
  • gantry.csv
  • aris_frame_meta.csv
  • aris_file_meta.yaml
Some recordings may not have complete GoPro coverage. The viewer will display sonar data even if camera frames are unavailable for certain indices.
If the colormap appears incorrect, try viewing without colorization:
python scripts/view_recording.py <recording-folder> --no-colorize

​
Next Steps

Dataset Structure

Learn about the organization and file formats

Processing Scripts

Explore the preprocessing pipeline

Build docs developers (and LLMs) love

Get started for freeTalk to us