Pikaliov/depth_edges_annotate_worlduav
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README and CLAUDE.md: unified 17 classes, post-processing, 3 datasets

Browse Source 
- All datasets now use unified 17 classes (not 11/14/16 separately)
- Document seg post-processing (dark water fix, wetland reclassify)
- Update test count (149), time estimates (17 prompts), palette
- Add seg_classes.py to project structure
- Fix outdated references throughout

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
pikaliov
2026-04-18 02:46:59 +03:00
parent f0c876dfc7
commit ff002ce142
2 changed files with 75 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
CLAUDE.md
View File

@@ -16,26 +16,38 @@ python scripts/run_uav_visloc.py
# GTA-UAV-LR (48K images, synthetic GTA V)
python scripts/run_gta_uav.py
# Тесты (143 шт, без GPU)
# Тесты (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 (zero-copy mmap, ~0.1ms чтение). Не NPY, не PNG, не `.pt`.
- **Структура директорий:** модальность = папка (`depth/`, `edge/`, `segm/`, `chm/`, `safetensors/`), не суффикс файла.
- **Стадии последовательно** — одна модель в GPU за раз (экономия VRAM).
- **Сегментация:** SegEarth-OV3 (SAM 3.1 + open-vocabulary prompts). 11 классов для World-UAV, **17 unified** для UAV_VisLoc + GTA-UAV (единые ID для transfer learning).
- **Сегментация:** SegEarth-OV3 (SAM 3.1 + open-vocabulary prompts). **17 unified классов** для всех датасетов (единые ID для transfer learning).
- **Post-processing:** два правила после SegEarth — dark water fix (background → water для тёмных изображений) и wetland reclassify (для GTA-UAV).
- **CHMv2 только FP32** — в FP16 NaN.
## Структура кода
```
src/main.py — точка входа, оркестрация стадий
src/augmentor/ — inference, I/O, dataset discovery
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/ — run_uav_visloc.py, migrate_layout.py
scripts/seg_classes.py — UNIFIED_PROMPTS (17 классов, единый источник)
scripts/run_*.py — скрипты запуска для каждого датасета
in/config_files/ — gin-конфиги
docs/ — документация
```
@@ -44,10 +56,15 @@ docs/ — документация
Все параметры через gin. CLI override: `--gin "PipelineConfig.source = 'db'"`.
Для нового датасета — создать скрипт в `scripts/` (пример: `run_uav_visloc.py`), не новый gin-файл.
Для нового датасета — создать скрипт в `scripts/` (пример: `run_gta_uav.py`).
Ключевые флаги pipeline:
- `seg_fix_dark_water=True` — автоматически исправлять тёмную воду (по умолчанию вкл.)
- `seg_reclassify_wetland=False` — переклассификация wetland в vegetation/bare soil (вкл. для GTA-UAV)
## Что НЕ делать
- Не добавлять классы сегментации в `segmentation.gin` для конкретного датасета — использовать `scripts/seg_classes.py` (единый набор 17 классов для transfer learning).
- Не менять порядок/ID классов в `scripts/seg_classes.py` — все датасеты зависят от фиксированных ID.
- Не использовать `.pt` (torch.save) для хранения тензоров — pickle, медленно.
- Не рендерить depth/seg в RGB colormap для обучения — OOD для DINOv3, потеря информации.
- Не снижать threshold ниже 0.1 — увеличивает false positives без значимого улучшения recall.

106
README.md
View File

@@ -1,6 +1,6 @@
# Multi-Modal Annotation Pipeline
Автоматическая генерация 4 модальностей (depth, edges, segmentation, canopy height) из RGB-изображений аэрофотосъёмки. Поддерживает два датасета:
Автоматическая генерация 4 модальностей (depth, edges, segmentation, canopy height) из RGB-изображений аэрофотосъёмки. Поддерживает три датасета:
| Модальность | Модель | Выход | Скорость |
|:---|:---|:---|:---|
@@ -12,11 +12,11 @@
| Датасет | Изображения | Сегм. классы | Скрипт |
|:---|:---|:---|:---|
| **World-UAV** | 973K (486K DB + 486K query) | 11 (базовые) | `python -m src.main` |
| **World-UAV** | 973K (486K DB + 486K query) | 17 (unified) | `python -m src.main` |
| **UAV_VisLoc** | 81K (75K DB + 6.7K drone) | 17 (unified) | `python scripts/run_uav_visloc.py` |
| **GTA-UAV-LR** | 48K (15K sat + 34K drone) | 17 (unified) | `python scripts/run_gta_uav.py` |
> UAV_VisLoc и GTA-UAV используют **единый набор 17 классов** (`scripts/seg_classes.py`) для совместимости при transfer learning.
> Все датасеты используют **единый набор 17 классов** (`scripts/seg_classes.py`) для совместимости при transfer learning.
## Quick Start
@@ -30,7 +30,7 @@ python scripts/run_uav_visloc.py
# GTA-UAV-LR
python scripts/run_gta_uav.py
# Тесты (143 шт, без GPU)
# Тесты (149 шт, без GPU)
python -m pytest src/tests/ -v
```
@@ -65,15 +65,16 @@ python -m pytest src/tests/ -v
│ │ └── utils/ # I/O, export, geometry
│ ├── augmentor/
│ │ ├── models.py # Загрузка/выгрузка моделей
│ │ ├── inference.py # Inference функции (depth, chmv2, edges, segm)
│ │ ├── inference.py # Inference + post-processing (depth, chmv2, edges, segm)
│ │ ├── io_utils.py # Сохранение файлов (sync + async) + палитра
│ │ └── dataset.py # Discovery, filtering, PyTorch Dataset
│ ├── conf/ # Gin-configurable dataclasses
│ ├── utils/ # Profiler, benchmark, GPU utils
│ └── tests/ # 143 теста (pytest)
│ └── tests/ # 149 тестов (pytest)
├── scripts/
│ ├── run_uav_visloc.py # Запуск для UAV_VisLoc (16 классов)
│ ├── run_gta_uav.py # Запуск для GTA-UAV-LR (14 классов)
│ ├── seg_classes.py # UNIFIED_PROMPTS — 17 классов (единый источник)
│ ├── run_uav_visloc.py # Запуск для UAV_VisLoc
│ ├── run_gta_uav.py # Запуск для GTA-UAV-LR
│ └── migrate_layout.py # Миграция со старого prefix-формата
└── docs/
├── segmentation_class_analysis.md # Анализ классов сегментации (11 классов)
@@ -108,29 +109,9 @@ PipelineConfig.subset = None # None=все, 'Rot', 'Country', 'Ter
PipelineConfig.source = 'db' # 'db' = спутник, 'query' = БПЛА, None = оба
```
### segmentation.gin (11 классов open-vocabulary)
### segmentation.gin (unified 17 классов)
```python
SegConfig.prompts = [
'background', # 0 -- unclassified
'building', # 1 -- buildings, rooftops
'road', # 2 -- roads, asphalt
'vegetation', # 3 -- trees, bushes, forest canopy
'water', # 4 -- rivers, canals, sea, lakes
'sand and gravel ground', # 5 -- soil, gravel, sand, dust, bare earth
'rocky terrain', # 6 -- rock, stone, lava, canyon walls
'farmland', # 7 -- agricultural terraces, fields
'railway', # 8 -- railway tracks, rails
'parking lot', # 9 -- parking areas
'sidewalk', # 10 -- sidewalks, pedestrian zones
]
SegConfig.threshold = 0.15
SegConfig.default_resolution = 1008
```
### Unified 17 классов (UAV_VisLoc + GTA-UAV)
Для transfer learning (pretrain GTA-UAV → fine-tune UAV_VisLoc) оба датасета используют **единый набор 17 классов** из `scripts/seg_classes.py`. Не каждый датасет содержит пиксели каждого класса — это нормально (0 пикселей = 0 loss).
Все датасеты используют **единый набор 17 классов** из `scripts/seg_classes.py` для совместимости при transfer learning (pretrain GTA-UAV → fine-tune UAV_VisLoc/World-UAV). Не каждый датасет содержит пиксели каждого класса — это нормально (0 пикселей = 0 loss).
| ID | Промпт | World-UAV | UAV_VisLoc | GTA-UAV |
|:--:|:---|:---:|:---:|:---:|
@@ -145,14 +126,20 @@ SegConfig.default_resolution = 1008
| 8 | railway | + | + | + |
| 9 | parking lot | + | + | + |
| 10 | sidewalk | + | + | + |
| 11 | bare soil and plowed field | — | + | + |
| 12 | roof and rooftop | — | + | + |
| 13 | sports field and playground | — | + | редко |
| 14 | muddy ground and wetland | — | + | — |
| 15 | embankment and levee | — | + | — |
| 16 | swimming pool | — | редко | + |
| 11 | bare soil and plowed field | + | + | + |
| 12 | roof and rooftop | + | + | + |
| 13 | sports field and playground | + | + | редко |
| 14 | muddy ground and wetland | + | + | reclassify* |
| 15 | embankment and levee | + | + | редко |
| 16 | swimming pool | + | редко | + |
> UAV_VisLoc threshold=0.1, GTA-UAV threshold=0.15. Подробный анализ: [`docs/segmentation_class_analysis.md`](docs/segmentation_class_analysis.md)
\* GTA-UAV: `seg_reclassify_wetland=True` — wetland переклассифицируется в vegetation/bare soil (ложные срабатывания на холмах GTA V).
**Post-processing** (после SegEarth-OV3):
- `seg_fix_dark_water=True` (все датасеты) — background на тёмных изображениях (mean_rgb < 0.24) → water
- `seg_reclassify_wetland=True` (только GTA-UAV) — wetland → vegetation (зелёный) / bare soil (коричневый)
> Подробный анализ: [`docs/segmentation_class_analysis.md`](docs/segmentation_class_analysis.md)
### hardware.gin
@@ -235,23 +222,23 @@ World-UAV-aug/
| ID | Класс | RGB | Датасеты |
|:--:|:---|:---|:---|
| 0 | background | (0, 0, 0) | оба |
| 1 | building | (220, 40, 40) | оба |
| 2 | road | (160, 160, 160) | оба |
| 3 | vegetation | (30, 180, 30) | оба |
| 4 | water | (30, 120, 220) | оба |
| 5 | sand and gravel ground | (180, 140, 80) | оба |
| 6 | rocky terrain | (120, 100, 80) | оба |
| 7 | farmland | (200, 200, 50) | оба |
| 8 | railway | (100, 60, 120) | оба |
| 9 | parking lot | (255, 165, 0) | оба |
| 10 | sidewalk | (200, 200, 200) | оба |
| 11 | bare soil | (140, 100, 50) | UAV_VisLoc |
| 12 | rooftop | (180, 60, 60) | UAV_VisLoc |
| 13 | sports field | (50, 200, 150) | UAV_VisLoc |
| 14 | muddy/wetland | (80, 100, 70) | UAV_VisLoc |
| 15 | embankment | (170, 130, 100) | UAV_VisLoc |
| 16 | swimming pool | (0, 200, 255) | GTA-UAV |
| 0 | background | (0, 0, 0) | Black |
| 1 | building | (220, 40, 40) | Red |
| 2 | road | (160, 160, 160) | Gray |
| 3 | vegetation | (30, 180, 30) | Green |
| 4 | water | (30, 120, 220) | Blue |
| 5 | sand and gravel ground | (180, 140, 80) | Tan |
| 6 | rocky terrain | (120, 100, 80) | Brown |
| 7 | farmland | (200, 200, 50) | Yellow |
| 8 | railway | (100, 60, 120) | Purple |
| 9 | parking lot | (255, 165, 0) | Orange |
| 10 | sidewalk | (200, 200, 200) | Light gray |
| 11 | bare soil | (140, 100, 50) | Dark tan |
| 12 | rooftop | (180, 60, 60) | Dark red |
| 13 | sports field | (50, 200, 150) | Teal |
| 14 | muddy/wetland | (80, 100, 70) | Olive |
| 15 | embankment | (170, 130, 100) | Sandy brown |
| 16 | swimming pool | (0, 200, 255) | Cyan |
## Использование для обучения
@@ -334,7 +321,8 @@ proc.save_pretrained('in/weights/dinov3-chmv2')
## Известные особенности
- **CHMv2 работает только в FP32** -- в FP16 выдает NaN. Модель автоматически загружается в FP32 независимо от `use_fp16`
- **SegEarth-OV3 bottleneck** -- grounding decoder (11 промптов x per-image) = ~84% времени инференса. Text embeddings кэшируются. Batch size backbone = 16
- **SegEarth-OV3 bottleneck** -- grounding decoder (17 промптов x per-image) = ~84% времени инференса. Text embeddings кэшируются. Batch size backbone = 16
- **Post-processing сегментации** -- dark water fix (background → water для тёмных изображений) + wetland reclassify (GTA-UAV: wetland → vegetation/bare soil)
- **16 сцен Country исключены** -- неполные (нет DB-кропов). Фильтруются автоматически через `INCOMPLETE_SCENES`
- **Ледники/снег** -- SegEarth-OV3 классифицирует как `water` (ограничение модели). Класс `snow and ice` убран как неэффективный
- **Verbose логи подавлены** -- DA3, transformers, SAM 3.1, HF Hub. Управляется через `_silence_model_loggers()`
@@ -345,10 +333,10 @@ proc.save_pretrained('in/weights/dinov3-chmv2')
|:---|:---|:---|
| Depth | ~14.7 ч | 16% |
| Edges | ~0.6 ч | <1% |
| Segmentation (bs=16, 11 prompts) | ~77 ч | **~70%** |
| Segmentation (bs=16, 17 prompts) | ~120 ч | **~76%** |
| CHMv2 | ~8.5 ч | ~8% |
| Consolidate (.safetensors) | ~0.1 ч | <1% |
| **Итого** | **~101 ч (~4 дня)** | |
| **Итого** | **~144 ч (~6 дней)** | |
> При обработке только DB (спутник, `source='db'`): ~486K изображений, ~50 ч.
> При обработке только query (БПЛА, `source='query'`): ~486K изображений, ~50 ч.
@@ -356,7 +344,7 @@ proc.save_pretrained('in/weights/dinov3-chmv2')
## Тесты
```bash
# Все тесты (143 штуки, ~2.5 сек, без GPU)
# Все тесты (149 штук, ~2.5 сек, без GPU)
python -m pytest src/tests/ -v
# Только pipeline integration
@@ -372,7 +360,7 @@ python -m pytest src/tests/test_inference.py -v
| Документ | Описание |
|---|---|
| [`docs/segmentation_class_analysis.md`](docs/segmentation_class_analysis.md) | Анализ 392 локаций, выбор 11 классов, результаты тестирования |
| [`docs/segmentation_class_analysis.md`](docs/segmentation_class_analysis.md) | Unified 17 классов: анализ World-UAV (392 локации), UAV_VisLoc, GTA-UAV |
| [`docs/segearth_ov3_architecture.md`](docs/segearth_ov3_architecture.md) | Архитектура SegEarth-OV3 + SAM 3.1, pipeline инференса, профиль производительности |
| [`docs/analysis_optimization.md`](docs/analysis_optimization.md) | Общий анализ и оптимизация пайплайна |
| [`docs/skills_optimization_io_dl_ml.md`](docs/skills_optimization_io_dl_ml.md) | Справочник приемов оптимизации I/O, DataLoader, ML |