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

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

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

50
CLAUDE.md Normal file
View File

@@ -0,0 +1,50 @@
# 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
# Тесты (143 шт, без GPU)
python -m pytest src/tests/ -v
```
## Ключевые решения
- **Формат выхода:** 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, 16 для UAV_VisLoc.
- **CHMv2 только FP32** — в FP16 NaN.
## Структура кода
```
src/main.py — точка входа, оркестрация стадий
src/augmentor/ — inference, I/O, dataset discovery
src/conf/ — gin-configurable dataclasses
src/nn/ — вендорированные DA3 + SegEarth-OV3
scripts/ — run_uav_visloc.py, migrate_layout.py
in/config_files/ — gin-конфиги
docs/ — документация
```
## Конфигурация
Все параметры через gin. CLI override: `--gin "PipelineConfig.source = 'db'"`.
Для нового датасета — создать скрипт в `scripts/` (пример: `run_uav_visloc.py`), не новый gin-файл.
## Что НЕ делать
- Не добавлять классы сегментации в `segmentation.gin` для конкретного датасета — классы специфичны для датасета, задавать в скрипте.
- Не использовать `.pt` (torch.save) для хранения тензоров — pickle, медленно.
- Не рендерить depth/seg в RGB colormap для обучения — OOD для DINOv3, потеря информации.

66
README.md
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 | | **CHMv2** | DINOv3-ViTL16 (337M, FP32) | grayscale [256x256] | 31.7 img/s |
| **Consolidate** | SafeTensors (CPU) | `.safetensors` per image | ~5000 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 ## Quick Start
```bash ```bash
# 1. Запуск (из корня проекта) # World-UAV (основной датасет)
python -m src.main python -m src.main
# 2. Тесты # UAV_VisLoc
python scripts/run_uav_visloc.py
# Тесты (143 шт, без GPU)
python -m pytest src/tests/ -v 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 │ ├── utils/ # Profiler, benchmark, GPU utils
│ └── tests/ # 143 теста (pytest) │ └── tests/ # 143 теста (pytest)
├── scripts/ ├── scripts/
│ ├── run_uav_visloc.py # Запуск для UAV_VisLoc (16 классов)
│ └── migrate_layout.py # Миграция со старого prefix-формата │ └── migrate_layout.py # Миграция со старого prefix-формата
└── docs/ └── docs/
├── segmentation_class_analysis.md # Анализ классов сегментации (11 классов) ├── segmentation_class_analysis.md # Анализ классов сегментации (11 классов)
@@ -114,6 +121,20 @@ SegConfig.threshold = 0.15
SegConfig.default_resolution = 1008 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) Подробный анализ выбора классов: [`docs/segmentation_class_analysis.md`](docs/segmentation_class_analysis.md)
### hardware.gin ### hardware.gin
@@ -193,21 +214,26 @@ World-UAV-aug/
| segmentation | `_segm` | RGB palette, class ID = argmax по палитре | | segmentation | `_segm` | RGB palette, class ID = argmax по палитре |
| chmv2 | `_chm` | grayscale (L), uint8, `value / 255.0` -> [0,1] | | chmv2 | `_chm` | grayscale (L), uint8, `value / 255.0` -> [0,1] |
### Палитра сегментации (11 классов) ### Палитра сегментации
| ID | Класс | Цвет | RGB | | ID | Класс | RGB | Датасеты |
|:--:|:---|:---|:---| |:--:|:---|:---|:---|
| 0 | background | Black | (0, 0, 0) | | 0 | background | (0, 0, 0) | оба |
| 1 | building | Red | (220, 40, 40) | | 1 | building | (220, 40, 40) | оба |
| 2 | road | Gray | (160, 160, 160) | | 2 | road | (160, 160, 160) | оба |
| 3 | vegetation | Green | (30, 180, 30) | | 3 | vegetation | (30, 180, 30) | оба |
| 4 | water | Blue | (30, 120, 220) | | 4 | water | (30, 120, 220) | оба |
| 5 | sand and gravel ground | Tan | (180, 140, 80) | | 5 | sand and gravel ground | (180, 140, 80) | оба |
| 6 | rocky terrain | Brown | (120, 100, 80) | | 6 | rocky terrain | (120, 100, 80) | оба |
| 7 | farmland | Yellow | (200, 200, 50) | | 7 | farmland | (200, 200, 50) | оба |
| 8 | railway | Purple | (100, 60, 120) | | 8 | railway | (100, 60, 120) | оба |
| 9 | parking lot | Orange | (255, 165, 0) | | 9 | parking lot | (255, 165, 0) | оба |
| 10 | sidewalk | Light gray | (200, 200, 200) | | 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 ```bash
# Все тесты (141 штука, ~2.5 сек, без GPU) # Все тесты (143 штуки, ~2.5 сек, без GPU)
python -m pytest src/tests/ -v python -m pytest src/tests/ -v
# Только pipeline integration # Только pipeline integration

96
docs/segmentation_class_analysis.md
View File

@@ -177,6 +177,102 @@ SegConfig.default_resolution = 1008
| 9 | parking lot | (255, 165, 0) | Orange | | 9 | parking lot | (255, 165, 0) | Orange |
| 10 | sidewalk | (200, 200, 200) | Light gray | | 10 | sidewalk | (200, 200, 200) | Light gray |
---
## Конфигурация для UAV_VisLoc: 16 классов
UAV_VisLoc_processed — другой датасет (81K images, 11 сцен, DB + drone, 256x256). Анализ сегментации на scene 01 (2496 images) выявил 29% background — значительно больше, чем у World-UAV после настройки.
### Анализ проблемных зон
На 2496 изображениях scene 01 (UAV_VisLoc) были обнаружены 3 систематических паттерна ложного background:
| Паттерн | Примеры | RGB характеристика | Текущее покрытие (11 кл.) |
|---|---|---|---|
| **Распаханные поля** | crop_0_11, crop_0_58, crop_10_49 | Однородная коричнево-серая текстура (R≈140, G≈120, B≈100) | 0% — ни `farmland`, ни `sand/gravel` не срабатывают |
| **Тёмные/текстурированные крыши** | crop_0_97, crop_10_13 | Тёмные поверхности с солнечными панелями, промышленные объекты | ~50% — `building` ловит стены, но не крыши |
| **Спортплощадки, теплицы** | crop_10_5 | Яркие прямоугольные объекты с уникальной текстурой | 0% — нет подходящего класса |
| **Болотистый грунт / дамбы** | crop_0_0, crop_0_1 | Тёмно-зелёно-серый (R≈101, G≈103, B≈97), между водоёмами | 0% — слишком тёмный для `sand/gravel` |
| **Экстремально тёмная вода** | crop_0_4, crop_0_6 | Почти чёрный (R<30, G<30, B<30) | 0% — SegEarth не видит воду при очень низкой яркости |
### Количественный анализ (scene 01, 11 классов → 16 классов)
| Метрика | 11 классов | 16 классов (ожид.) |
|---|---|---|
| background % | 29.0% | ~10-15% |
| Изображений >50% bg | 475 / 2496 (19%) | ~100-150 |
| 100% background | ~50 | ~20-30 (экстремально тёмные) |
### 5 добавленных классов и обоснование
| ID | Промпт | Обоснование | Что покрывает |
|---|---|---|---|
| 11 | `bare soil and plowed field` | **Главная потеря** (~15-20% пикселей bg). `farmland` ловит только зелёные поля с посевами. Распаханная земля (коричневая, без растительности) — отдельный семантический класс. В UAV_VisLoc много сельских сцен с обработанными полями без всходов. | Распаханные поля, голая земля, стройплощадки |
| 12 | `roof and rooftop` | `building` обучен на стены/фасады. Крыши сверху (вид с БПЛА/спутника) — другая текстура: черепица, металл, солнечные панели, плоские бетонные крыши. SegEarth не уверен в `building` для тёмных крыш → background. | Крыши всех типов, солнечные панели на крышах |
| 13 | `sports field and playground` | Спортплощадки имеют уникальную геометрию (прямоугольники, разметка, цветные покрытия), не покрываемую ни одним из базовых классов. Для CVGL — сильный localization landmark. | Теннисные корты, футбольные поля, баскетбольные площадки |
| 14 | `muddy ground and wetland` | Болотистая земля между водоёмами (дамбы, берега, русла). Слишком тёмная для `sand/gravel`, слишком сухая для `water`. Специфична для UAV_VisLoc (прибрежные сцены). | Мокрый грунт, заболоченные участки, дамбы |
| 15 | `embankment and levee` | Насыпные сооружения (дамбы, набережные, обваловки) — линейные структуры из грунта вдоль водоёмов. Геометрически уникальны для matching. | Земляные дамбы, насыпи, обваловки каналов |
### Почему `threshold=0.1` (а не 0.15 как в World-UAV)
UAV_VisLoc содержит больше экстремальных сцен:
- Тёмная вода (почти чёрная) — confidence по `water` = 0.12-0.14
- Мокрый грунт — confidence по `bare soil` = 0.11-0.13
- При threshold=0.15 эти пиксели уходят в background, при 0.1 — корректно классифицируются
### Неустранимый background (~5-10%)
Остаётся background для изображений, где SegEarth-OV3 **физически не может** сегментировать:
- Почти чёрные кадры (ночная вода, тень) — нет визуальной информации
- Однородные текстуры без семантических признаков
- Это нормально — background здесь семантически корректен
### Полная конфигурация UAV_VisLoc (16 классов)
```python
SegConfig(threshold=0.1, prompts=[
"background", # 0
"building", # 1
"road", # 2
"vegetation", # 3
"water", # 4
"sand and gravel ground", # 5
"rocky terrain", # 6
"farmland", # 7
"railway", # 8
"parking lot", # 9
"sidewalk", # 10
"bare soil and plowed field", # 11
"roof and rooftop", # 12
"sports field and playground", # 13
"muddy ground and wetland", # 14
"embankment and levee", # 15
])
```
### Расширенная палитра (16 классов)
| ID | Класс | RGB | Цвет |
|:--:|:---|:---|:---|
| 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 |
---
## Оценка влияния на производительность ## Оценка влияния на производительность
- Инференс: ~1.8–2.2x медленнее (11 vs 5 text prompts) - Инференс: ~1.8–2.2x медленнее (11 vs 5 text prompts)