# Анализ классов сегментации для UAV-GeoLoc

## Обзор датасета

- **392 локации**, 76 кадров каждая (height100_rot90) = ~29 800 изображений
- **11 стран** (Country/): Australia, Brazil, English, French, German, Italy, Japan, Korea, Poland, Spain, USA
- **27 типов terrain** (Terrain/): Basin, Calcification, Danxia, Delta, Desert, Fall, Farm, Finca, Flowers, Glacier, Gorge, Hill, Hylare, Island, Karst, Lakes-ignore, Mountain, Oasis, Pasture, Plain, Plateau, Prairie, Snow, StoneForest, Terrace, Volcano, Wetland

## Проблема с исходной конфигурацией (5 классов)

Исходные промпты:
```
SegConfig.prompts = ['background', 'building', 'road', 'vegetation', 'water']
SegConfig.threshold = 0.3
```

При 5 классах **60-90% площади terrain-кадров и 30-50% городских кадров уходит в background**, теряя информативные объекты (ж/д пути, грунт, скалы и т.д.).

---

## Инвентаризация объектов

### URBAN (Country/) — 11 стран, ~300 локаций

| Объект | Где встречается | Частота |
|---|---|---|
| Здания (крыши: черепица, плоские, металл, стекло) | Все города | Доминирует |
| Дорога / асфальт | Все города | Очень высокая |
| Растительность (деревья, кустарники) | Все города | Высокая |
| Тротуар / пешеходная зона / набережная | Все города, особенно Европа | Высокая |
| Парковка | Мюнхен, SF, Варшава, Аделаида | Средняя |
| Железная дорога (рельсы, балласт, стрелки) | Мюнхен, Сидней, Варшава | Средняя |
| Вода (река, канал, море) | Париж/Сена, Венеция, Киото, Бусан, Копакабана | Средняя |
| Мост / эстакада | Сидней, Париж | Низкая-средняя |
| Внутренний двор | Все европейские города | Средняя |
| Открытый грунт / гравий | Мюнхен, Варшава | Средняя |
| Газон / парк | Лондон/Westminster, Rio | Средняя |
| Спортивная площадка | Мюнхен | Низкая |
| Пляж / песок | Копакабана, Бусан/Gwangalli | Низкая |
| Дорожная разметка (зебры, полосы) | Все города | Высокая, но мелкая |
| Солнечные панели | SF, Мюнхен | Низкая |

### TERRAIN — 27 типов

| Terrain | Что на кадрах | Ключевые поверхности |
|---|---|---|
| Desert (Gobi) | Песок, эрозионные борозды, скалы | bare ground, sand, rock |
| Farm (Bohemian) | Густой лес, кроны деревьев | vegetation |
| Glacier (Athabasca) | Лёд, снег, трещины | snow, ice, water |
| Island (Aldabra) | Бирюзовая вода, мелководье | water |
| Wetland (Danube) | Болотистая почва, кустарник | vegetation, bare ground, water |
| Mountain (Andes) | Песок/пыль, следы троп | bare ground, rock |
| Delta (Congo) | Лавовые/скальные поверхности | rock, bare ground |
| Volcano (Kilauea) | Тёмная лава, скальные породы | rock, bare ground |
| Snow (Aconcagua) | Белый снег, точки камней | snow |
| Danxia (GrandCanyon) | Красная порода + растительность | rock, vegetation |
| Oasis | Саванна, кустарники на песке | bare ground, vegetation |
| Finca (Althorp) | Хвойный лес, плантации | vegetation |
| Terrace (Banaway) | Сельхоз террасы, тропы | farmland, bare ground |
| Plain (Alberta) | Луг, речная пойма, грунтовая дорога | grassland, bare ground, road |
| Plateau | Кустарник на каменистой почве | vegetation, rock |
| Prairie (Etosha) | Саванна, точки кустов на песке | bare ground, vegetation |
| Gorge (Antelope) | Каньон, красные скалы | rock, bare ground |
| Karst (Mammoth) | Скальные плиты, трещины | rock |
| Calcification (ElTatio) | Гейзерные поля, песчаная порода | bare ground, rock |
| Flowers (BlueHotSpring) | Горячие источники, минеральные отложения | rock, water |
| Hylare (Amazon) | Густой тропический лес | vegetation |
| StoneForest (GrandCanyon) | Каньонные скалы + кустарник | rock, vegetation |
| Hill (Sedona) | Красные скалы + кустарник | rock, vegetation |
| Basin | — | — |
| Fall | — | — |
| Pasture | — | — |
| Lakes-ignore | — | — |

---

## Финальная конфигурация: 11 классов

```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, embankments
]
SegConfig.threshold = 0.15
SegConfig.default_resolution = 1008
```

### Эволюция конфигурации

1. **v1** (исходная): 5 классов, threshold=0.3 — слишком много background
2. **v2** (первая итерация): 12 классов (`bare ground`, `rock`, `snow`, `farmland`, `railway`, `parking lot`, `sidewalk`), threshold=0.3 — terrain по-прежнему плохо
3. **v3** (вторая итерация): 12 классов с переименованными промптами (`sand and gravel ground`, `rocky terrain`, `snow and ice`), threshold=0.15 — значительное улучшение terrain
4. **v4** (финальная): 11 классов — убран `snow and ice` (SegEarth-OV3 не различает снег/лёд от воды при виде сверху), threshold=0.15

### Обоснование каждого нового класса

| Класс | Промпт | Обоснование | Покрытие |
|---|---|---|---|
| bare ground | `sand and gravel ground` | Без него пустыня, гейзеры, плато, прерия, пляж уходят в background | Критичен для terrain |
| rock | `rocky terrain` | Вулканы, каньоны, карст — уникальная текстура | Критичен для terrain |
| farmland | `farmland` | Террасы, поля — геометрически уникальны для matching | Важен для Terrace/Plain/Farm |
| railway | `railway` | Ж/д пути — линейный ориентир с уникальной топологией | Важен для городов |
| parking lot | `parking lot` | Чёткая прямоугольная геометрия, видна и с дрона и со спутника | Средний для городов |
| sidewalk | `sidewalk` | Структурные границы в городах, набережные | Средний для городов |

### Отброшенные классы и причины

| Класс | Причина отказа |
|---|---|
| `snow and ice` | SegEarth-OV3 классифицирует лёд/снег как `water` при виде сверху — промпт не работает. Проверено на Glacier (Athabasca) |
| `beach` / `sand` | Покрыт `sand and gravel ground` |
| `bridge` | Слишком редко, перекрывается с `road` |
| `grassland` / `lawn` | Перекрывается с `vegetation` |
| `river` / `sea` / `lake` | Всё покрыто единым `water` |
| `sports field` | Слишком редко на полном датасете |
| `courtyard` | Семантически = `bare ground` + `building` |
| `fence` | Слишком тонкий объект для SegEarth на 1008px |
| `road marking` | Слишком мелкий, лучше оставить как часть `road` |
| `solar panel` | Редко, мелко, часть крыши |

---

## Результаты тестирования на 10 изображениях

Тестовые изображения: 6 городских (Munich, Paris, Venice, New York, Sydney, Busan) + 4 terrain (Desert, Glacier, Volcano, Danxia).

### Городские сцены

| Локация | Обнаруженные классы | Качество |
|---|---|---|
| Munich (ж/д пути) | railway, sand/gravel, vegetation, road, water | Отлично — ж/д = фиолетовый, балласт = бежевый |
| Paris (набережная Сены) | road, vegetation, water, sidewalk, parking lot | Отлично — река, тротуар, дорога разделены |
| Venice (старый город) | building, road, water, parking lot | Хорошо — каналы появились как water |
| New York (Manhattan) | building, road, vegetation, parking lot, sidewalk | Отлично — все городские классы |
| Sydney (эстакада) | road, building, vegetation, parking lot, sidewalk | Хорошо |
| Busan (пляж) | water, sand and gravel ground | Отлично — пляж = бежевый, море = синий |

### Terrain

| Локация | Обнаруженные классы | Качество |
|---|---|---|
| Desert (Gobi) | road, rocky terrain | Приемлемо — пустыня = road (серый близок к песку) |
| Glacier (Athabasca) | water | Ограничение модели — лёд = water |
| Volcano (Kilauea) | rocky terrain | Отлично — было 100% background, стало 100% rocky terrain |
| Danxia (GrandCanyon) | vegetation | Частично — кусты определены, скалы в background |

### Известные ограничения SegEarth-OV3

- Ледники/снег классифицируются как `water` — визуально неразличимы сверху для модели
- Красные скалы (Danxia) плохо определяются как `rocky terrain`
- Пустынный грунт может путаться с `road`

---

## Палитра цветов

| 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 |

---

## Unified 17 классов для transfer learning

UAV_VisLoc и GTA-UAV используют **единый набор 17 классов** (`scripts/seg_classes.py`). Это обеспечивает совместимость class IDs при transfer learning (pretrain GTA-UAV → fine-tune UAV_VisLoc). Не каждый датасет содержит пиксели каждого класса — класс с 0 пикселей просто не даёт вклад в loss.

Источник единой конфигурации: `scripts/seg_classes.py:UNIFIED_PROMPTS`.

---

## Конфигурация для UAV_VisLoc: 17 классов (unified)

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 здесь семантически корректен

### Конфигурация (unified 17 классов)

```python
from scripts.seg_classes import UNIFIED_PROMPTS
SegConfig(threshold=0.1, prompts=UNIFIED_PROMPTS)
# UNIFIED_PROMPTS содержит 17 классов (ID 0-16)
# UAV_VisLoc: активны все кроме 16 (swimming pool — редко)
```

### Расширенная палитра (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 |

---

## Конфигурация для GTA-UAV-LR: 14 классов

### Характеристики датасета

GTA-UAV-LR — синтетический датасет, сгенерированный из игрового движка GTA V (Grand Theft Auto V).

| Параметр | Значение |
|---|---|
| Drone изображения | 33 763 шт., 512x384 px, RGB PNG |
| Satellite изображения | 14 640 шт., 256x256 px, **RGBA** PNG |
| Итого | 48 403 изображения |
| Высоты полёта | 100, 200, 300, 400, 500, 600 м |
| Локация | Карта GTA V (Лос-Сантос и окрестности) |
| Сцены | Город, пригород, сельская местность, побережье, горы, пустыня |
| Формат аннотаций | JSON (cross-area, same-area, train/test splits) |

**Особенности:**
- **Satellite RGBA:** alpha-канал обозначает границы карты GTA V. Прозрачные пиксели (alpha=0) = за пределами игрового мира. При обработке конвертируется в RGB (прозрачное → чёрный).
- **Drone не квадратные:** 512x384 → resize в 512x512 (потеря aspect ratio, но это синтетика — не критично).
- **Синтетические текстуры:** GTA V рендерит реалистичные но не фотореалистичные текстуры. SegEarth-OV3 справляется хорошо — текстуры достаточно близки к реальным для open-vocabulary grounding.
- **Бассейны** — характерная особенность пригородов GTA V (Vinewood Hills, Rockford Hills). Яркий бирюзовый цвет, уникальная геометрия — сильный localization cue для CVGL.

### Выбор 14 классов

11 базовых классов (совпадают с World-UAV) + 3 специфичных:

| ID | Промпт | Обоснование |
|---|---|---|
| 11 | `bare soil and plowed field` | GTA V содержит много пустырей, стройплощадок, грунтовых дорог в пригородах (Sandy Shores, Grapeseed). Без этого класса ~10-15% уходит в background. |
| 12 | `roof and rooftop` | Плоские крыши коммерческих зданий, вертолётные площадки (Maze Bank Tower). GTA V рендерит крыши с детализированными текстурами (кондиционеры, антенны), которые `building` не ловит сверху. |
| 13 | `swimming pool` | Бассейны во дворах вилл — один из самых характерных визуальных элементов пригородов GTA V. Яркий бирюзовый цвет на сером/зелёном фоне — сильнейший landmark для cross-view matching. `water` не различает бассейн от океана. |

### Почему не добавлены

| Класс | Причина |
|---|---|
| `highway` | Покрыт `road` — SegEarth не различает шоссе и обычную дорогу |
| `beach` | Покрыт `sand and gravel ground` |
| `mountain` | Покрыт `rocky terrain` + `vegetation` |
| `sports field` | Есть в GTA V, но редко виден сверху (стадионы закрыты) |
| `muddy ground` | Не актуален для GTA V (нет болот в Лос-Сантосе) |

### Конфигурация (unified 17 классов)

```python
from scripts.seg_classes import UNIFIED_PROMPTS
SegConfig(threshold=0.15, prompts=UNIFIED_PROMPTS)
# + seg_fix_dark_water=True, seg_reclassify_wetland=True
```

### Результаты post-processing (проверено на 128 satellite + drone)

| Метрика | Без post-processing | С post-processing |
|---|---|---|
| Satellite background | 57.6% | **5.3%** |
| Satellite >50% bg images | 56.7% | **1%** |
| Satellite water | 3.7% | **58.5%** |
| Drone wetland (ложный) | 14.3% | **0%** |
| Drone background | 11.4% | ~8% |

Два правила:
1. **Dark water fix** (`seg_fix_dark_water=True`): если background-пиксели имеют mean_rgb < 0.24 и std < 0.18, переклассифицировать в water (class 4). Пороги калиброваны на GTA-UAV ocean: mean ~0.12-0.18, std ~0.10-0.15.
2. **Wetland reclassify** (`seg_reclassify_wetland=True`): промпт "muddy ground and wetland" ложно срабатывает на холмистой местности GTA V (трава + грунт). Переклассификация по цвету: зелёный → vegetation (3), коричневый → bare soil (11).

---

## Оценка влияния на производительность

- Инференс: ~1.8–2.2x медленнее (11 vs 5 text prompts)
- На 973K изображений: дополнительные ~8–12 часов на RTX 4090
- Background на terrain: сокращение с 60–90% до ~10–20%
- Background на urban: сокращение с 30–50% до ~5–15%

## Методология анализа

Просмотрено ~50 кадров с равномерной выборкой:
- По 1–3 кадра из каждой страны (разные города/районы)
- По 1 кадру из каждого типа terrain (первая доступная локация)
- Кадры выбирались из середины траектории (frame 30) для репрезентативности
- Дополнительно просмотрены кадры из начала/конца траектории для Мюнхена (полный обзор 76 кадров)
- Тестирование проведено в 3 итерации с подбором формулировок промптов и порога confidence