# CLAUDE.md

## Что это за проект

Пайплайн автоматической генерации 4 вспомогательных модальностей (depth, edges, segmentation, canopy height) из RGB-изображений аэрофотоснимков. Используется для подготовки обучающих данных для NADEZHDA — системы cross-view geolocalization (БПЛА ↔ спутник).

## Быстрый старт

```bash
# World-UAV (973K images, основной датасет)
python -m src.main

# UAV_VisLoc (81K images)
python scripts/run_uav_visloc.py

# GTA-UAV-LR (48K images, synthetic GTA V)
python scripts/run_gta_uav.py

# Тесты (149 шт, без GPU)
python -m pytest src/tests/ -v
```

## Поддерживаемые датасеты

| Датасет | Изображения | Тип | Скрипт |
|---|---|---|---|
| World-UAV | 973K | Реальные аэрофото, 27 terrain, 11 стран | `python -m src.main` |
| UAV_VisLoc | 81K | Реальные, 11 сцен, DB + drone | `python scripts/run_uav_visloc.py` |
| GTA-UAV-LR | 48K | Синтетика GTA V, 6 высот полёта | `python scripts/run_gta_uav.py` |

## Ключевые решения

- **Формат выхода:** SafeTensors с **dense tensor maps** (zero-copy mmap, ~0.1ms). Все модальности — прямые тензоры (float16/uint8), не RGB-рендеры.
- **Структура директорий:** модальность = папка (`depth/`, `edge/`, `segm/`, `chm/`, `safetensors/`), не суффикс файла.
- **Стадии последовательно** — одна модель в GPU за раз (экономия VRAM).
- **Сегментация:** SegEarth-OV3 (SAM 3.1 + open-vocabulary prompts). **17 unified классов** для всех датасетов (единые ID для transfer learning).
- **Post-processing:** два правила после SegEarth — dark water fix (mean<0.24, std<0.18 → water; satellite bg 57%→5%) и wetland reclassify (GTA-UAV: ложный wetland 14%→0%).
- **CHMv2 только FP32** — в FP16 NaN.

## Структура кода

```
src/main.py              — точка входа, оркестрация стадий
src/augmentor/inference.py — инференс + postprocess_segmentation()
src/augmentor/io_utils.py  — I/O, SafeTensors, палитра 17 классов
src/augmentor/dataset.py   — discovery, filtering (DB/query/drone/satellite)
src/conf/                  — gin-configurable dataclasses
src/nn/                    — вендорированные DA3 + SegEarth-OV3
scripts/seg_classes.py     — UNIFIED_PROMPTS (17 классов, единый источник)
scripts/run_*.py           — скрипты запуска для каждого датасета
in/config_files/           — gin-конфиги
docs/                      — документация
```

## Конфигурация

Все параметры через gin. CLI override: `--gin "PipelineConfig.source = 'db'"`.

Для нового датасета — создать скрипт в `scripts/` (пример: `run_gta_uav.py`).

Ключевые флаги pipeline:
- `seg_fix_dark_water=True` — автоматически исправлять тёмную воду (по умолчанию вкл.)
- `seg_reclassify_wetland=False` — переклассификация wetland в vegetation/bare soil (вкл. для GTA-UAV)

## Что НЕ делать

- Не менять порядок/ID классов в `scripts/seg_classes.py` — все датасеты зависят от фиксированных ID.
- Не использовать `.pt` (torch.save) для хранения тензоров — pickle, медленно.
- Не рендерить depth/seg в RGB colormap для обучения — OOD для DINOv3, потеря ~70% информации. Использовать dense tensor maps из SafeTensors.
- Не снижать threshold ниже 0.1 — увеличивает false positives без значимого улучшения recall.
- Не менять `dark_water_std_thr` (0.18) — калибровано на GTA-UAV ocean (std 0.10-0.15). Ниже — не ловит, выше — false positives на normal images.