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.

​
Overview

The view_recording.py script provides an interactive GUI application for viewing and exploring individual recordings from the UXO Dataset. Built with PyQt5, it displays synchronized ARIS sonar imagery, GoPro camera footage, gantry positioning data, and frame metadata.

​
Command-Line Usage

python view_recording.py <recording_dir> [options]

​
Arguments

​
recording_dir
string
required
Path to the recording directory containing the ARIS frames, GoPro frames, gantry data, and metadata files.

​
Options

​
-p, --polar
boolean
default:"True"
Use polar-transformed ARIS images instead of raw images. When enabled, reads from aris_polar/ directory; otherwise uses aris_raw/.
​
-c, --colorize
boolean
default:"True"
Apply colormap to ARIS images. Uses OpenCV’s COLORMAP_TWILIGHT_SHIFTED to enhance visualization.
​
-l, --use-lru-cache
boolean
default:"False"
Enable LRU caching for frame loading. Improves performance when repeatedly viewing the same frames at the cost of memory usage.

​
Examples

# View a recording with default settings
python view_recording.py data/recordings/barrel/2024_05_15_001

​
DatasetViewer Class

The main class that implements the interactive viewer application.

​
Constructor

DatasetViewer(
    recording_dir: str,
    aris_polar: bool = True,
    aris_colorize: bool = True,
    use_lru_cache: bool = False
)
​
recording_dir
str
required
Path to the recording directory
​
aris_polar
bool
default:"True"
Whether to load polar-transformed ARIS images
​
aris_colorize
bool
default:"True"
Whether to apply colormap to ARIS images
​
use_lru_cache
bool
default:"False"
Whether to enable frame caching

​
Key Methods

​
get_data()

Retrieves all data for a specific frame position. 
def get_data(self, pos: int) -> tuple:
    """Returns (aris_frame_idx, aris, gopro, gantry, frame_meta)"""
Returns:
  • aris_frame_idx (int): The ARIS frame index
  • aris (QPixmap): ARIS sonar image
  • gopro (QPixmap): GoPro camera frame
  • gantry (pd.Series): Gantry position data (x, y, z)
  • frame_meta (pd.Series): ARIS frame metadata

​
Data Files Required

The viewer expects the following files in the recording directory:
File/DirectoryDescription
aris_polar/ or aris_raw/Directory containing ARIS frame images
gopro/Directory containing GoPro frame images
gantry.csvGantry positioning data indexed by aris_frame_idx
aris_frame_meta.csvPer-frame ARIS metadata indexed by frame_index
aris_file_meta.yamlARIS file-level metadata
notes.txtRecording notes (optional)

​
Keyboard Controls

The viewer supports keyboard navigation for efficient frame browsing: 
Left Arrow    : Previous frame
Right Arrow   : Next frame
Up Arrow      : Skip forward 10 frames
Down Arrow    : Skip backward 10 frames
Q             : Quit application
The slider can also be used for direct frame navigation by clicking or dragging.

​
GUI Layout

The viewer window is divided into several sections:

​
Left Panel

  • ARIS Display: Shows the sonar imagery with optional colorization

​
Right Panel

  • GoPro Display: Synchronized optical camera footage
  • Position Info: Current frame index and total frame count
  • Gantry Info: Real-time gantry position (x, y, z coordinates)
  • Notes: Recording notes and target information
  • File Metadata: ARIS file-level metadata
  • Frame Metadata: Per-frame ARIS header information

​
Bottom

  • Slider: Frame navigation control

​
Image Processing

The viewer applies several transformations to the ARIS imagery:
  1. Polar Transformation: When using raw images (--no-polar), the viewer flips the image to correct beam ordering (right-to-left to left-to-right)
  2. Colorization: When enabled (default), applies OpenCV’s COLORMAP_TWILIGHT_SHIFTED colormap to enhance visualization
  3. Aspect Ratio: Images are automatically scaled to fit the window while maintaining aspect ratio

​
Performance Considerations

Enable --use-lru-cache when working with recordings you’ll navigate repeatedly. This caches loaded frames in memory for instant access.
The LRU cache has no size limit when enabled. For large recordings or limited memory systems, leave caching disabled.

​
Dependencies

The script requires the following Python packages:
  • PyQt5 - GUI framework
  • opencv-python (cv2) - Image processing
  • pandas - Data handling
  • PyYAML - Configuration loading
And custom modules from the UXO Dataset codebase:
  • common.matching_context
  • common.aris_definitions
  • common.q_custom_widgets

Build docs developers (and LLMs) love

Get started for freeTalk to us