This directory contains a short drone video clip, U_video_cut.mp4 (5 seconds), and its associated flight log, U_video_cut.csv. These files alone enable quick testing and demonstration of trajectory extraction in pixel coordinates.

The video clip is sourced from the Songdo Traffic dataset. It was created by extracting the first 5 seconds from U_D10_2022-10-07_PM5_60s.mp4 using the following command:

python tools/recut_video_and_log.py data/sample_videos/U_D10_2022-10-07_PM5_60s.mp4 -s 0 -e 150 -o data/U_video_cut.mp4 -ec

To reproduce the pixel-coordinate results in the data/results-pixel/ directory, run the following command from the repository root:

geotrax batch data/U_video_cut.mp4 --no-geo --show-class-names --show-conf

To reproduce the full Geo-trax pipeline results in the data/results-full/ directory, including georeferencing, road segmentation, kinematics, and real-world vehicle dimension estimation, run the following command from the repository root:

geotrax batch data/U_video_cut.mp4 -orf data/orthophotos -osf data/segmentations -mf data/master_frames --show-lanes --plot-segmentations -vm 0 3

Note: The trajectory and distribution plots generated from this 5-second sample are not statistically meaningful due to the limited sample size. Longer video clips are needed for representative results.

Prerequisites: Download the required files as described in the Sample Videos and Data section:

• Orthophoto files: orthophotos/U_center.txt, orthophotos/U.png, orthophotos/ortho_parameters.txt
• Segmentation files: segmentations/U.csv; optional overlay PNG can be generated later (see overlay instructions).
• Master frame files: master_frames/U.png, master_frames/U.txt

Tip: You can easily process any sample video from the Songdo Traffic dataset by replacing U_video_cut.mp4 with the desired filename (e.g., A_D1_2022-10-07_PM5_60s.mp4).

The Songdo Experiment provides ready-to-use files to test the full capabilities of the Geo-trax pipeline, including sample BEV drone footage from 20 different intersections (60-second clips), orthophotos and road segmentation masks for each intersection, and optional master frame files for consistent georeferencing.

All files are available from Zenodo. For detailed information about the experiment and dataset, see the associated article.

Choose one of the following options to download and extract the sample data. After extraction, verify that your directory structure matches the layout shown below.

Download the files manually from the links below, then extract each ZIP file into the data/ directory:

• Sample Videos — 26.8 GB (MD5: cbe3b6f6c1dc5e9dce3406b4c1162b6f)
• Orthophotos — 1.8 GB (MD5: 31a2712a456a22b3db8d5513e75da8b2)
• Segmentations — 24.9 KB (MD5: c39304c88ddf39f3e0a40b8621d384b9)
• Master Frames — 248.6 MB (MD5: 4af9a065be7bcc4ac09ac45a9ce1af71)

Run the following commands from the data/ directory to automatically download, extract, and clean up:

Note for macOS users: Replace wget with curl -L and -O with -o, or install wget via Homebrew: brew install wget

Note for Windows users: Install wget via Chocolatey (choco install wget), or use Option 1.

# Download and extract sample videos
wget "https://zenodo.org/records/17924857/files/sample_videos.zip?download=1" -O sample_videos.zip
unzip sample_videos.zip && rm sample_videos.zip

# Download and extract orthophotos
wget "https://zenodo.org/records/17924857/files/orthophotos.zip?download=1" -O orthophotos.zip
unzip orthophotos.zip && rm orthophotos.zip

# Download and extract segmentations
wget "https://zenodo.org/records/17924857/files/segmentations.zip?download=1" -O segmentations.zip
unzip segmentations.zip && rm segmentations.zip

# Download and extract master frames
wget "https://zenodo.org/records/17924857/files/master_frames.zip?download=1" -O master_frames.zip
unzip master_frames.zip && rm master_frames.zip

Note: This is a simplified, sample-only layout. The orthophoto, master-frame, and segmentation folders sit flat under data/ and are passed explicitly via -orf / -osf / -mf, which bypasses the default auto-detection (a PROCESSED/ folder with a sibling ORTHOPHOTOS/ containing nested master_frames/ and segmentations/). For the recommended layout used in real multi-drone projects, see Recommended project folder structure in the main README.

After downloading and extracting the four ZIPs, your data/ directory should look like the tree below. Each entry is tagged by source: download (one of the Zenodo ZIPs above), in repo (already shipped with the repository), or generated (created locally).

geo-trax/
└── data/
    ├── master_frames/    ← download: master_frames.zip
    │   ├── A.png
    │   ├── A.txt
    │   ├── ...
    │   ├── U.png
    │   └── U.txt
    ├── orthophotos/      ← download: orthophotos.zip
    │   ├── A_center.txt
    │   ├── A.png
    │   ├── ...
    │   ├── ortho_parameters.txt
    │   ├── ...
    │   ├── U_center.txt
    │   └── U.png
    ├── README.md         ← in repo
    ├── results/          ← created when you run the reproduce commands above
    │   ├── U_video_cut.txt
    │   ├── U_video_cut.csv
    │   ├── U_video_cut_mode_0.mp4
    │   ├── ...
    │   └── plots/
    ├── results-full/     ← in repo (reference output)
    ├── results-pixel/    ← in repo (reference output)
    ├── sample_videos/    ← download: sample_videos.zip
    │   ├── A_D1_2022-10-07_PM5_60s.mp4
    │   ├── ...
    │   └── U_D10_2022-10-07_PM5_60s.mp4
    ├── segmentations/    ← download: segmentations.zip (*.png generated locally)
    │   ├── A.csv
    │   ├── A.png          ← generated (see note below)
    │   ├── ...
    │   ├── U.csv
    │   └── U.png          ← generated (see note below)
    ├── U_video_cut.csv   ← in repo (sample clip log)
    └── U_video_cut.mp4   ← in repo (sample clip)

Note: The segmentation visualization PNGs (segmentations/*.png) are not included in the downloaded segmentations.zip. Generate them locally after downloading the orthophotos and segmentation CSVs:

python tools/viz_segmentations.py data/orthophotos/ -sf data/segmentations/

This overlays each CSV's lane polygons and section labels onto the corresponding orthophoto and writes the annotated PNG to data/segmentations/.