Update docs: CLAUDE.md, README, segmentation class analysis

- Create CLAUDE.md with project overview, key decisions, structure
- Update README: add UAV_VisLoc dataset, 16-class palette, scripts
- Extend segmentation_class_analysis.md with UAV_VisLoc section:
  quantitative analysis of 2496 images, 5 new classes with detailed
  justification (bare soil, rooftop, sports field, wetland, embankment),
  threshold rationale, and irreducible background explanation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
pikaliov
2026-04-17 21:27:25 +03:00
parent 5c4a3a1371
commit 27eb315903
3 changed files with 192 additions and 20 deletions

View File

@@ -1,6 +1,6 @@
# World-UAV Annotation Pipeline
# Multi-Modal Annotation Pipeline
Автоматическая генерация 4 модальностей из RGB-изображений датасета World-UAV (973K images):
Автоматическая генерация 4 модальностей (depth, edges, segmentation, canopy height) из RGB-изображений аэрофотосъёмки. Поддерживает два датасета:
| Модальность | Модель | Выход | Скорость |
|:---|:---|:---|:---|
@@ -10,18 +10,24 @@
| **CHMv2** | DINOv3-ViTL16 (337M, FP32) | grayscale [256x256] | 31.7 img/s |
| **Consolidate** | SafeTensors (CPU) | `.safetensors` per image | ~5000 img/s |
| Датасет | Изображения | Классы сегментации | Скрипт |
|:---|:---|:---|:---|
| **World-UAV** | 973K (486K DB + 486K query) | 11 | `python -m src.main` |
| **UAV_VisLoc** | 81K (75K DB + 6.7K drone) | 16 | `python scripts/run_uav_visloc.py` |
## Quick Start
```bash
# 1. Запуск (из корня проекта)
# World-UAV (основной датасет)
python -m src.main
# 2. Тесты
# UAV_VisLoc
python scripts/run_uav_visloc.py
# Тесты (143 шт, без GPU)
python -m pytest src/tests/ -v
```
Все параметры настраиваются через `in/config_files/*.gin`. Аргументов командной строки нет.
## Структура проекта
```
@@ -60,6 +66,7 @@ python -m pytest src/tests/ -v
│ ├── utils/ # Profiler, benchmark, GPU utils
│ └── tests/ # 143 теста (pytest)
├── scripts/
│ ├── run_uav_visloc.py # Запуск для UAV_VisLoc (16 классов)
│ └── migrate_layout.py # Миграция со старого prefix-формата
└── docs/
├── segmentation_class_analysis.md # Анализ классов сегментации (11 классов)
@@ -114,6 +121,20 @@ SegConfig.threshold = 0.15
SegConfig.default_resolution = 1008
```
### UAV_VisLoc: 16 классов (расширенные)
UAV_VisLoc содержит больше сельских/прибрежных сцен. Анализ scene 01 (2496 images) показал 29% background при 11 классах. Добавлены 5 классов:
| ID | Промпт | Зачем |
|:--:|:---|:---|
| 11 | `bare soil and plowed field` | Распаханные поля без посевов — 15-20% бывшего background |
| 12 | `roof and rooftop` | Тёмные крыши, солнечные панели — `building` ловит стены, не крыши сверху |
| 13 | `sports field and playground` | Уникальная геометрия, сильный landmark для CVGL |
| 14 | `muddy ground and wetland` | Болотистый грунт между водоёмами (дамбы, берега) |
| 15 | `embankment and levee` | Линейные земляные сооружения вдоль каналов |
> Threshold снижен до 0.1 (vs 0.15 для World-UAV) — UAV_VisLoc содержит больше тёмных/низкоконтрастных сцен.
Подробный анализ выбора классов: [`docs/segmentation_class_analysis.md`](docs/segmentation_class_analysis.md)
### hardware.gin
@@ -193,21 +214,26 @@ World-UAV-aug/
| segmentation | `_segm` | RGB palette, class ID = argmax по палитре |
| chmv2 | `_chm` | grayscale (L), uint8, `value / 255.0` -> [0,1] |
### Палитра сегментации (11 классов)
### Палитра сегментации
| ID | Класс | Цвет | RGB |
| ID | Класс | RGB | Датасеты |
|:--:|:---|:---|:---|
| 0 | background | Black | (0, 0, 0) |
| 1 | building | Red | (220, 40, 40) |
| 2 | road | Gray | (160, 160, 160) |
| 3 | vegetation | Green | (30, 180, 30) |
| 4 | water | Blue | (30, 120, 220) |
| 5 | sand and gravel ground | Tan | (180, 140, 80) |
| 6 | rocky terrain | Brown | (120, 100, 80) |
| 7 | farmland | Yellow | (200, 200, 50) |
| 8 | railway | Purple | (100, 60, 120) |
| 9 | parking lot | Orange | (255, 165, 0) |
| 10 | sidewalk | Light gray | (200, 200, 200) |
| 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 |
## Использование для обучения
@@ -312,7 +338,7 @@ proc.save_pretrained('in/weights/dinov3-chmv2')
## Тесты
```bash
# Все тесты (141 штука, ~2.5 сек, без GPU)
# Все тесты (143 штуки, ~2.5 сек, без GPU)
python -m pytest src/tests/ -v
# Только pipeline integration