UAV-VisLoc-prepare/README.md

UAV-VisLoc Dataset Preparation

Подготовка датасета UAV-VisLoc для задач cross-view retrieval / geo-localization.

Скрипт:

• ресайзит drone-кадры
• режет спутниковые карты на кропы фиксированного размера
• считает GPS-координаты центра каждого кропа
• сопоставляет каждый drone-кадр с ближайшим кропом (positive) и соседями по сетке (semi-positive)
• генерирует индексы в формате, совместимом с UAV-GeoLoc (Index/train_query.txt, Index/*_db.txt)

Входные данные

Ожидаемая структура сырого датасета (--src):

UAV_VisLoc_dataset/
├── 01/
│   ├── drone/*.JPG
│   ├── satellite01.tif
│   └── 01.csv
├── ...
├── 09/
│   ├── satellite09_01-01.tif
│   ├── satellite09_01-02.tif
│   ├── satellite09_02-01.tif
│   ├── satellite09_02-02.tif
│   ├── drone/*.JPG
│   └── 09.csv
├── satellite_ coordinates_range.csv
├── visloc_train.csv
└── visloc_test.csv

Примечания:

• Маршрут 07 исключён (спутниковая карта 3000×170 — невозможно нарезать 512×512).
• Для маршрута 09 спутник хранится 4 тайлами и автоматически сшивается в один большой image.

Выходные данные

Структура обработанного датасета (--dst):

UAV_VisLoc_processed/
├── 01/
│   ├── drone/*.JPG
│   ├── DB/
│   │   ├── img/crop_X_Y.png
│   │   └── db_postion.txt
│   ├── positive.json
│   └── semi_positive.json
├── ...
└── Index/
    ├── train_query.txt
    ├── test_query.txt
    ├── train_db.txt
    ├── test_db.txt
    ├── all_db.txt
    ├── train.txt
    └── test.txt

Установка

Python 3.10+.

python -m pip install -U pip
python -m pip install numpy pillow

Запуск

Минимальный пример:

python scripts/prepare_dataset.py \
  --src "/path/to/UAV_VisLoc_dataset" \
  --dst "/path/to/UAV_VisLoc_processed"

Рекомендованные параметры (частый пресет):

• --crop-size 512
• --stride 256 (50% overlap)
• --target-size 512 (если хотите хранить 512×512 на диске; иначе по умолчанию будет 256×256)

python scripts/prepare_dataset.py \
  --src "/path/to/UAV_VisLoc_dataset" \
  --dst "/path/to/UAV_VisLoc_processed" \
  --crop-size 512 \
  --stride 256 \
  --target-size 512

Обработать только выбранные маршруты:

python scripts/prepare_dataset.py \
  --src "/path/to/UAV_VisLoc_dataset" \
  --dst "/path/to/UAV_VisLoc_processed" \
  --routes 01 02 03

Что делает скрипт (по шагам)

1. Читает метаданные
   • satellite_ coordinates_range.csv: GPS bbox спутниковых карт по маршрутам
   • {route}/{route}.csv: GPS drone-кадров
   • visloc_train.csv / visloc_test.csv: train/test split по именам файлов
2. Ресайзит drone изображения в {route}/drone/*.JPG до --target-size × --target-size
3. Загружает спутниковую карту (route 09 — сшивка 4 тайлов)
4. Нарезает спутник на кропы --crop-size × --crop-size со --stride, сохраняет в {route}/DB/img/ как PNG, затем ресайзит кроп до --target-size
5. Считает GPS для центра каждого кропа (линейная интерполяция внутри bbox)
6. Матчит drone→crop
   • positive: ближайший кроп по haversine distance
   • semi-positive: соседи ±1 по grid (до 8 штук, если не на границе карты)
7. Пишет метаданные и индексы в стиле UAV-GeoLoc

Форматы файлов

Index/train_query.txt и Index/test_query.txt

Одна строка = один drone query:

01/drone/01_0001.JPG 0 01/DB/img/crop_5_18.png 01/DB/img/crop_4_17.png 01/DB/img/crop_4_18.png ...

Формат:

• query_path label pos1 pos2 ...
• label в этом проекте всегда 0 (как в исходных датасетах UAV-GeoLoc; дальше лоссы обычно не используют это поле)
• первый путь после label — positive (ближайший), остальные — semi-positive (соседи в сетке)

Index/*_db.txt и Index/all_db.txt

Галерея (DB) — список всех спутниковых кропов:

01/DB/img/crop_0_0.png
01/DB/img/crop_0_1.png
...

Важное: gallery одинаковая для train/test, split идёт по queries.

{route}/positive.json

Ключ = frame id без префикса маршрута (01_0001.JPG → "0001"):

{
  "0001": ["crop_5_18.png"],
  "0002": ["crop_5_19.png"]
}

{route}/semi_positive.json

До 8 соседей в сетке вокруг positive:

{
  "0001": ["crop_4_17.png", "crop_4_18.png"],
  "0002": ["crop_4_18.png", "crop_4_19.png"]
}

{route}/DB/db_postion.txt

Tab-separated, совместимо с UAV-GeoLoc (орфография postion сохранена намеренно):

crop_0_0.png	115.97197337	29.77349180	2.68e-06	-2.68e-06

Колонки:

• name
• longitude
• latitude
• scale_lon (deg/px)
• scale_lat (deg/px)

Про negatives / positives

Отдельного списка negative нет: negatives = все кропы gallery, которые не вошли в список positive+semi-positive для данного query.

Известные ограничения и качество матчингa

• Route 07 исключён (слишком узкая спутниковая карта).
• Встречается кейс, когда часть drone кадров может оказаться далеко от спутникового покрытия (в исходном датасете).
• --target-size влияет на то, какое разрешение хранится на диске; для обучения многие пайплайны всё равно делают финальный ресайз/кроп/аугментации уже в dataloader’е.

Память

Маршрут 09 (сшивка тайлов) — самый тяжёлый по RAM; остальные маршруты существенно легче.
Если не хватает памяти, можно прогонять маршруты по одному через --routes.