# Задание Морозу Егору Сергеевичу

## 1. Трек

Role-Aware Hierarchical Fusion.

Дополнительная командная роль: владелец dataset contract, modality preprocessing, validity masks и контроля качества auxiliary inputs.

## 2. Исследовательский вопрос

Даёт ли отдельная обработка spatial semantics, geometry и global text более сильный retrieval descriptor, чем один универсальный оператор для всех модальностей?

## 3. Обязательное чтение

### Общий пакет

- все документы `docs/02_references/01_required/`;
- fusion core synthesis и taxonomy;
- StripNet analysis B14.

### Segmentation

- `REVIEW_segmentation_pairA.md`
- `DELTA_pair_A_seg_revised_v3.md`
- `ОБЗОР_fusion_rgb_segmentation_v1.md`
- `F36_FC-CLIP.md`
- `P52_CVGL_2024_A guided ... segmentation.md`

### Geometry

- `REVIEW_depth_normals_pairB.md`
- `DELTA_pair_B_depth_uav_v3.md`
- `REVIEW_chm_pairC.md`
- `DELTA_pair_C_chm_sat_v3.md`
- `M11_CHMv2_deep_dive_for_MERIDIAN.md`
- `M4_2025_JRN-Geo ... .md`
- `P44_MGS2_deep_dive_for_MERIDIAN.md`

### Text

- `REVIEW_text_pairD_final.md`
- `REVIEW_text_pairD_methodology.md`
- `F14_2025_WeatherPrompt_deep_dive_for_MERIDIAN.md`
- `F47_2026_TacFiLM_Tactile_Modality_Fusion_VLA.md`
- `P64_2025_CGSI_deep_dive_for_MERIDIAN.md`

⚠️ Документы `DELTA_pair_*_v3.md` — короткие changelog-вершины. Полное содержание pair-анализов лежит в `03_segmentation/_version_chain/` и `04_geometry/_version_chain/` (базовые версии 30–48 KB). Читать цепочкой: база → v2 → v3.

### Канонические опоры (проверенные выводы из vault, использовать в evidence matrix)

| Источник | Факт | Следствие для трека C |
|---|---|---|
| M4 JRN-Geo | normals дают +2.6% в паре с RGB, но alone → 37%: геометрия — модулятор, не самостоятельный поток | geometry-путь проектировать как модуляцию RGB-признаков, не как параллельный encoder |
| P44 MGS2 deep dive | асимметричная depth-ветка (только drone); Sobel-on-depth ≈ ориентационные карты — дешевле и устойчивее raw values | кандидат представления depth в C3 |
| P68 / обзор DA3 | metric scale depth на UAV ненадёжен | использовать только relative structure; запрет на абсолютные значения |
| B97 IM2HEIGHT (caveat) | DSM ≠ CHM; синтетический CHM может отравить обучение | проверять происхождение CHM-карт в data audit |
| F63 HLMamba (caveat) | multiplicative gating убивает информацию при near-zero RGB | аргумент за FiLM с additive β и residual-форму |
| P52 guided CVGL | land-cover guidance улучшает CVGL; GT-Guide vs Guided — прямое LUPI-evidence | главный прецедент пользы segmentation именно в CVGL |
| DFormerv2 (CVPR 2025, TRIAGE §2) | depth как geometry-prior bias в self-attention: модуляция ≡ identity при отсутствии depth | кандидат geometry-пути с бесплатной missing-modality устойчивостью |
| F14 WeatherPrompt deep dive | text→FiLM MLP: zero-init, two-speed LR; FiLM > CrossAttn > Concat | стартовая точка text-пути C5 |

## 4. Общая обязанность: data contract

Совместно с коллегами реализовать единый loader extension, который возвращает:

- RGB;
- captions и text-valid mask;
- segmentation tensor и valid mask;
- view-specific geometry tensor и valid mask;
- sample IDs только для logging;
- multi-match evaluation metadata.

Loader не должен знать выбранный fusion variant.

## 5. Персональные задачи

### C0. Data audit

Проверить минимум 40 samples, поровну satellite/UAV, и заполнить:

| Sample | View | RGB shape | Seg classes | Geometry range | Caption | Alignment issue | Verdict |
|---|---|---|---|---|---|---|---|

Отдельно проверить:

- satellite alpha channel;
- resize/crop mapping;
- orientation consistency;
- SafeTensors keys;
- invalid/constant maps;
- empty captions;
- segmentation background fraction.

### C1. Modality role contract

Для каждой modality заполнить:

| Field | RGB | Segmentation | Depth | CHM | Text |
|---|---|---|---|---|---|
| Raw input | | | | | |
| Normalization | | | | | |
| Encoder | | | | | |
| Spatial level | | | | | |
| Confidence | | | | | |
| Expected CVGL signal | | | | | |
| Main shortcut risk | | | | | |

### C2. Segmentation path

Сравнить:

1. Class ID embedding + convolution.
2. One-hot/probability maps + convolution.
3. Mask-pooled class tokens.
4. Segmentation-guided attention bias.

Ответить:

- где сохраняется spatial layout;
- как кодируются отсутствующие классы;
- что делать с high-background samples;
- нужна ли entropy/confidence;
- на каких StripNet stages segmentation полезнее.

### C3. UAV depth path

Сравнить input representations:

- normalized relative depth;
- inverse depth;
- depth gradients;
- depth + gradient channels;
- compact depth statistics.

Выбрать representation, которая не зависит от неизвестного absolute scale GTA-UAV.

### C4. Satellite CHM path

Сравнить:

- raw normalized CHM;
- robust percentile normalization;
- CHM gradients;
- CHM + validity mask;
- local height statistics.

Проверить, что CHM используется только для satellite view.

### C5. Text path

Сравнить:

1. Global FiLM.
2. Visual-query/text-key-value cross-attention.
3. L1/L2/L3 tokens.
4. Late descriptor gating.

Зафиксировать empty-caption behaviour и исключить location leakage.

### C6. Сформировать три кандидата

| Candidate | Required design |
|---|---|
| C-C1 | dense geometry+seg fusion, затем text FiLM |
| C-C2 | segmentation class tokens + geometry bias + late text attention |
| C-C3 | multi-stage role-specific adapters + hierarchical readout |

### C7. Обосновать hierarchy

Primary должен явно определить порядок, например:

```text
StripNet stage 2/3
  + segmentation spatial semantics
  + view-specific geometry structure
        -> fused spatial feature
        -> StripNet stage 4 / aggregation
        + text semantic context
        -> hierarchical readout
        -> descriptor [B,1024]
```

Нужно показать, почему другой порядок слабее или рискованнее.

### C8. Uncertainty/validity handling

Минимальный набор:

- `text_valid`;
- `segmentation_valid`;
- `geometry_valid`;
- segmentation entropy/background ratio;
- geometry valid fraction.

Learned reliability head добавлять только после сравнения с explicit deterministic indicators.

### C9. Shared и view-specific параметры

Обязательно view-specific:

- первый geometry projector;
- normalization depth/CHM;
- quality features, зависящие от geometry semantics.

Кандидаты на shared:

- output channel interface;
- segmentation encoder;
- text encoder;
- late fusion/readout.

### C10. Diagnostics

- segmentation class contribution;
- geometry feature norm;
- text contribution;
- valid fraction distributions;
- RGB vs fused cosine;
- per-view modality contribution;
- failure examples high-background/flat geometry/empty text.

### C11. Tests

1. Correct SafeTensors key mapping per view.
2. Segmentation IDs остаются в `0..16`.
3. Missing class mask pooling finite.
4. Depth не подаётся в satellite geometry path.
5. CHM не подаётся в UAV geometry path.
6. Constant maps finite.
7. Invalid pixels не влияют на pooled statistics.
8. Output shape и norm.
9. Spatial alignment after resize.

### C12. Персональные ablations

| ID | Сравнение |
|---|---|
| C-AB1 | one universal operator vs role-aware operators |
| C-AB2 | segmentation dense map vs class tokens |
| C-AB3 | raw depth vs inverse/gradient depth |
| C-AB4 | raw CHM vs robust/gradient CHM |
| C-AB5 | text FiLM vs cross-attention |
| C-AB6 | text early vs late |
| C-AB7 | spatial-first vs text-first |
| C-AB8 | validity only vs reliability head |
| C-AB9 | shared vs view-specific geometry projector |
| C-AB10 | global vs hierarchical readout |

### C13. Falsification

Role-aware hypothesis не подтверждена, если:

- универсальный Multi-FiLM не хуже;
- порядок fusion не влияет;
- geometry contribution близок к нулю;
- text полностью определяет descriptor;
- segmentation path улучшает same-area, но ухудшает cross-area;
- gain не повторяется по seed.

## 6. Кодовые артефакты

```text
src/fuse_proj/data/batch.py
src/fuse_proj/data/gtauav_multimodal.py
src/fuse_proj/data/validation.py
src/fuse_proj/models/fusion/role_aware.py
in/config_files/data_gtauav.gin
in/config_files/fusion_role_aware.gin
tests/test_multimodal_data.py
tests/test_role_aware.py
reports/moroz/DESIGN.md
reports/moroz/IMPLEMENTATION_AND_RESULTS.md
```

## 7. Definition of Done

- [ ] Data audit завершён.
- [ ] Loader contract принят всей командой.
- [ ] Role table заполнена.
- [ ] Segmentation/depth/CHM/text paths описаны отдельно.
- [ ] Три candidates сравнены.
- [ ] Primary/fallback выбраны.
- [ ] Все validity tests проходят.
- [ ] C-AB1..C-AB10 выполнены в согласованном объёме.
- [ ] Близно выполнил code review.
- [ ] Failure cases добавлены в общий отчёт.