# 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+.

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

## Запуск

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

```bash
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)

```bash
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
```

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

```bash
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"`):

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

### `{route}/semi_positive.json`

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

```json
{
  "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`.