HOTA Script Reference#

mqtt_camera_capture_processor.py#

Location: usecases/scenescape-deterministic-inference/hota/scripts/hota-metrics/

Purpose: Subscribes to MQTT camera detection topics, captures a fixed number of frames, reconstructs a clean dataset with no gaps, and triggers the HOTA evaluation pipeline.

The script will:

  1. Subscribe to scenescape/data/camera/Cam_x1_0 and scenescape/data/camera/Cam_x2_0

  2. Wait silently until frame 0 arrives on both cameras (start of a fresh video loop)

  3. Collect 1,856 frames per camera

  4. Fill any dropped frames with empty-object placeholders

  5. Replace all timestamps with the reference timestamps from frame_timestamp_mapping.csv (so they align with gtLoc.json ground truth)

  6. Write the reconstructed detection files to hota-metrics/dataset/

  7. Automatically invoke pipeline_engine metric_test_evaluation.yaml to run HOTA scoring

HOTA results are written to /tmp/tracker-evaluation/<run-ID>/.

Key behaviours:

Behaviour

Detail

Frame synchronization

Waits for frame == 0 before starting capture — ensures the dataset always starts at the beginning of the video loop

Drop detection

Detects missing frame numbers (for example, frame 5 followed by frame 8 means frames 6 and 7 were dropped)

Drop compensation

Inserts placeholder entries with empty objects for every missing frame number

Timestamp normalization

Replaces all captured timestamps with the reference mapping from frame_timestamp_mapping.csv, so they match the gtLoc.json ground truth timestamps

Pipeline trigger

After capture completes, runs python -m pipeline_engine metric_test_evaluation.yaml automatically with PYTHONPATH=.. so it can import evaluation modules

Configuration (edit at top of script):

MAX_SAMPLES = 1856               # Number of frames to capture per camera
MQTT_BROKER_HOST = "127.0.0.1"  # MQTT broker address (Machine 1 local)
TIMESTAMP_MAPPING_CSV = "frame_timestamp_mapping.csv"  # Frame → timestamp reference
OUTPUT_DIRECTORY = "dataset"     # Where reconstructed JSON files are written

traffic_generator.py#

Location: usecases/scenescape-deterministic-inference/hota/scripts/

Purpose: Injects controlled network congestion using iperf3, gated by MQTT camera frame numbers so it does not interfere with the capture start or end.

Key behaviours:

Behaviour

Detail

MQTT-gated start

Waits until frame 0 is received on all configured camera topics before launching iperf3

Burst pattern

Runs iperf3 for --duration seconds, sleeps --sleep seconds, repeats — mimics real-world bursty congestion

Automatic stop

Exits when any camera frame exceeds --stop-frame, ensuring the final frames of the capture window are not interrupted

Key CLI arguments:

--broker       MQTT broker host (default: 10.106.147.105)
--topics       Camera MQTT topics to monitor for frame gating
--target       iperf3 server host
--bitrate      iperf3 UDP bitrate (default: 960M)
--duration     iperf3 run time in seconds (default: 2)
--sleep        Sleep between iperf3 runs (default: 1.0)
--stop-frame   Stop traffic when this frame number is exceeded (default: 1700)

sei_parser.py#

Location: usecases/scenescape-deterministic-inference/hota/scripts/gvapython/

Purpose: GVAPython plugin that extracts the SEI-embedded frame number from each H.264 buffer before inference and adds it as sei_frame_num to the MQTT detection message.

The UUID used to identify the SEI payload is 12345678-1234-5678-1234-567812345678. This matches the UUID used when the test videos were prepared with ffmpeg.