depth_edges_annotate_worlduav/CLAUDE.md

CLAUDE.md

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

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

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

# 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 (скалы, растительность).