95f41a4401
- config_loader: add base_gin_files() to exclude dataset-specific pipeline_*.gin variants from default `python -m src.main` load (pipeline_uav_visloc.gin was overriding pipeline.gin) - main.py: use base_gin_files() in the --gin override branch too - pipeline.gin: source None (both DB + query) — was 'query', which silently dropped all DB satellite crops from discovery - README/CLAUDE/docs: sync source default, tensor format spec Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
77 lines
5.5 KiB
Markdown
77 lines
5.5 KiB
Markdown
# 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 spatial maps [1, H, W]** — финальные predictions, не промежуточные feature maps (zero-copy mmap, ~0.1ms). Подробная спецификация: `docs/tensor_format_spec.md`.
|
||
- **Что сохраняется:** depth (relative, float16), edge (Sobel magnitude, float16), segm (class IDs argmax, uint8), chm (relative height, float16). Всё в [0,1] кроме segm [0,16]. Per-frame normalized. Captions/text embeddings НЕ сохраняются.
|
||
- **Что НЕ сохраняется:** backbone features (ViT tokens), soft probabilities/logits, абсолютные значения глубины/высоты, text embeddings промптов.
|
||
- **Структура директорий:** модальность = папка (`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/tensor_format_spec.md — спецификация тензорных форматов (shapes, dtypes, normalization)
|
||
docs/ — документация
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
Все параметры через gin. CLI override: `--gin "PipelineConfig.source = 'db'"`.
|
||
|
||
Для нового датасета — создать скрипт в `scripts/` (пример: `run_gta_uav.py`).
|
||
|
||
Ключевые флаги pipeline:
|
||
- `seg_fix_dark_water=True` — автоматически исправлять тёмную воду (по умолчанию вкл.)
|
||
- `seg_fix_uniform_water=True` — исправлять однородную воду без контекста суши (по умолчанию вкл.). Два условия: (A) rgb_std < 0.10 для мутной речной воды, (B) mean_ch_std < 0.05 AND mean < 0.60 для синего океана со спутника.
|
||
- `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.
|
||
- Не менять `uniform_water_ch_std_thr` (0.05) — калибровано на GTA-UAV satellite ocean. Выше 0.05 — false positives на terrain (скалы, растительность).
|