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>
2026-04-17 21:27:25 +03:00
parent 5c4a3a1371
commit 27eb315903
3 changed files with 192 additions and 20 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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, потеря информации.
--- a/README.md
+++ b/README.md
@@ -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
--- a/docs/segmentation_class_analysis.md
+++ b/docs/segmentation_class_analysis.md
@@ -177,6 +177,102 @@ SegConfig.default_resolution = 1008
 | 9 | parking lot | (255, 165, 0) | Orange |
 | 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)