---
tags:
  - task
  - CVGL
  - ЛИСАД/ВЛМ
---
[[Base-Terms]], [[ЭТАПЫ]], [[01_required]],
[[Основной пакет]], [[02_fusion_core_общий]], [[02_fusion_core_персональный]], 

**Изучение постановки и контекста проекта:**
- README.md; 
- docs/00_project/06_MERIDIAN_CONTEXT.md (включая §5 — требование корректного поведения при отсутствии модальности);
- docs/01_tasks/00_MASTER_ASSIGNMENT.md; 
- 01_INPUT_OUTPUT_CONTRACT.md; 
- 02_TEAM_WORKFLOW.md; 
- 03_EXPERIMENT_PROTOCOL_GTA_UAV.md

# MERIDIAN CONTEXT

## 1. MERIDIAN — асимметричная Teacher–Student система

MERIDIAN — асимметричная Teacher–Student система кросс-видовой геолокализации БПЛА (UAV ↔ satellite) с привилегированными модальностями (LUPI/KD) и лёгким edge-инференсом.

**Цель:**  сравнение методов объединения и выбор по обозначенным критериям 
## 2. Teacher

Имеет 8 входных потоков. 

|#|Поток|View|Источник|Природа сигнала|
|---|---|---|---|---|
|1|RGB satellite|sat|датасет|основной визуальный якорь|
|2|Text caption satellite|sat|VLM (Qwen3-VL)|глобальная семантика сцены|
|3|CHM satellite|sat|CHMv2|высота растительности/структура|
|4|Segmentation satellite|sat|SegFormer, 17 классов|land-cover semantics|
|5|RGB UAV|uav|датасет|основной визуальный якорь|
|6|Text caption UAV|uav|VLM (Qwen3-VL)|глобальная семантика сцены|
|7|Relative depth UAV|uav|Depth Anything|геометрия/структура сцены|
|8|Segmentation UAV|uav|SegFormer, 17 классов|spatial semantics|
## 3. Цель

Прямой перебор fusion-архитектур на полном Teacher (DINOv3-L, ~300M+ params) слишком дорог: один полный прогон занимает часы и съедает всю VRAM. Поэтому архитектурный поиск выполняется на **быстром прокси**:

Прокси сохраняет главное: frozen visual anchor + лёгкие обучаемые модули, те же модальности, тот же retrieval-протокол. Вывод «какой класс fusion-операторов выигрывает и за счёт чего» переносится; конкретные гиперпараметры — нет, и это нормально.

## 4. Назначение результата

1. Победившее семейство (primary) + fallback фиксируются в decision record.
2. Primary-механизм переносится на Teacher DINOv3 (адаптация: CNN stage maps → ViT token maps) и входит в спецификацию fusion MERIDIAN.
3. Fused-эмбеддинг Teacher становится KD-таргетом для RGB-only Student.
4. Ваши diagnostics (вклад модальностей, gate statistics) станут инструментами анализа Teacher.

## 5. Устойчивость к modality-dropout

В production Teacher модальности могут отсутствовать или быть деградированными (нет caption у ~55% satellite tiles уже сейчас; depth/CHM могут быть зашумлены). Кроме того, на следующем этапе MERIDIAN планируется обучение с **modality dropout** (стохастическое отключение модальностей) — ==оно НЕ входит в ваше задание==, но накладывает требование на архитектуру:

| Класс                                              | Поведение при отсутствии модальности         | Вердикт                        |
| -------------------------------------------------- | -------------------------------------------- | ------------------------------ |
| Cross-attention над пулом модальных токенов        | softmax перенормируется на оставшиеся токены | **безопасен by construction**      |
| FiLM / gating с zero-init (identity-at-init)       | выпавшая модальность даёт identity           | **безопасен при корректной init**  |
| Gated additive residual                            | residual = 0 → чистый RGB-путь               | **безопасен при корректной init**  |
| Чисто multiplicative gating (выход = RGB × f(aux)) | near-zero aux уничтожает RGB-сигнал          | опасен, требует additive-ветки |
| Differential conditioning (f(Xi − Xj))             | теряет смысл при отсутствии одного из Xi     | опасен                         |
| SSM/Mamba cross-state fusion                       | состояние дестабилизируется                  | research-arm, не primary       |
==Практическое следствие для всех трёх треков: тест «отключи модальность через validity mask и проверь, что descriptor конечен и близок к RGB-only» входит в обязательные unit-тесты, а поведение при missing modality — в decision table финального сравнения.==

## 6. В проекте отсутствует

- Никакого modality dropout в training loop (это следующий этап MERIDIAN, отдельная задача).
- Никакой дистилляции в Student (KD-мост строится после выбора fusion).
- Никакой замены StripNet или обучения собственных моделей depth/seg/CHM/captions.
- Никакого использования GPS, координат, имён локаций и paired-view признаков.

# MASTER ASSIGMENT

## 1. Исполнители 

| Сотрудник                  | Архитектурный трек                      | Общая ответственность                                |
| -------------------------- | --------------------------------------- | ---------------------------------------------------- |
| **Павленко Богдан Викторович** | **Condition-Aware RGB-Anchored Fusion**     | **общий fusion API и architecture consistency**          |
| Близно Максим Витальевич   | Token/Bottleneck Full-Modal Aggregation | benchmark, metrics, run registry и статистика        |
| Мороз Егор Сергеевич       | Role-Aware Hierarchical Fusion          | dataset contract, preprocessing и quality validation |
## 2. Что требуется решить

Нужно разработать алгоритм объединения модальностей для cross-view geo-localization. Для каждой view-ветки доступен свой набор:
- img
- text
- geom
- segm

Один shared `StripNet-small` кодирует RGB.
### 2.1. Зачем это нужно

Для архитектурного отбора fusion-механизма для Teacher системы MERIDIAN на быстром прокси (StripNet + GTA-UAV вместо DINOv3 + production-данных).  
Отсюда два следствия:

1. Нас интересует **класс механизма и причина его успеха**, а не выжатые гиперпараметрами проценты.
2. Вторичный критерий отбора — **корректное поведение при отсутствии модальности** (validity mask = 0): выход конечен, RGB-путь не искажён

### 2.2. Заметки о данных

|Факт|Значение|Следствие|
|---|---|---|
|Satellite RGB|14,640 PNG 256×256, **RGBA**|alpha-канал проверить и отбросить осознанно|
|UAV RGB|33,763 PNG 512×384, высоты 100–600 м|resize к 256×256 фиксируется единообразно|
|Captions UAV|33,411 из 33,763 (~99%)|почти полное покрытие|
|Captions satellite|**6,546 из 14,640 (~44.7%)**|text_valid mask обязателен; пустой caption ≠ нулевой текст|
|Auxiliary maps|48,403 изображений: segm/depth/edge/chm (+SafeTensors)|edges в primary input не входят|
|Segmentation|17 unified classes|канон классов — `vendor_reference/depth_edges_annotate_worlduav/scripts/seg_classes.py`|
|Seg-filter|37,498 из 48,403 прошли фильтр (≥90% background+water исключены)|фильтр применяется одинаково ко всем вариантам|
|Расположение данных|Linux-сервер: `/home/servml/Документы/datasets/GTA-UAV-LR{,-captions,-aug}/`|фактические пути фиксируются в gin и ENVIRONMENT_AUDIT|

## 3. Входные и выходные данные
[[#IO CONTRACT]]
### 3.1. Satellite branch

```
RGB satellite       [B, 3, 256, 256]
Caption satellite   list[str] / tokenized text
CHM                  [B, 1, 256, 256]
Segmentation         [B, 1, 256, 256] IDs или [B, 17, 256, 256]
Validity masks       geometry + segmentation
```
### 3.2. Satellite branch

```
RGB UAV              [B, 3, 256, 256]
Caption UAV          list[str] / tokenized text
Relative depth       [B, 1, 256, 256]
Segmentation         [B, 1, 256, 256] IDs или [B, 17, 256, 256]
Validity masks       geometry + segmentation
```

### 3.3. Выходные данные

```
descriptor            [B, 1024], L2 normalized
rgb_descriptor        [B, 1024]
modality_contributions
diagnostics
```

Далее вычисляется similarity matrix UAV-to-satellite. Fusion-модуль не получает features противоположной view.

## 4. Цель экспериментов

Проверить, может ли full-modal representation улучшить cross-area retrieval относительно StripNet RGB-only и какой класс fusion делает это наиболее надёжно.

Primary metric: cross-area UAV-to-satellite R@1.
Secondary:
- R@5, R@10, MRR, AP;
- satellite-to-UAV retrieval;
- mean и std по seed 42/123/456;
- peak VRAM, latency, trainable params;
- вклад text, segmentation и geometry;
- отсутствие modality collapse.

## 5. Архитектурный кандидат

RGB остаётся anchor. Auxiliary encoders строят residual corrections, а controller определяет их вклад в зависимости от content и качества входов.
# IO CONTRACT

Одна обучающая запись содержит UAV-снимок запрос (query) и один положительный satellite кандидат (1 к 1). На eval может быть 1 к * (несколько допустимых sat matches)

## 1. Sat view

|Поле|Форма|Dtype|Нормализация|Назначение|
|---|---|---|---|---|
|`rgb`|`[B, 3, 256, 256]`|`float32`|ImageNet mean/std|вход StripNet|
|`text`|`list[str]` или tokens|string/int|согласно text encoder|описание сцены без location leakage|
|`geometry`|`[B, 1, 256, 256]`|`float32`|robust per-frame CHM normalization|высотная структура|
|`segmentation`|`[B, 1, 256, 256]` class IDs или `[B, 17, 256, 256]` probabilities|`uint8`/`float32`|IDs `0..16` или probabilities|land-cover semantics|
|`geometry_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные CHM pixels|
|`segmentation_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные segmentation pixels|
|`sample_id`|`[B]`|string|нет|только логирование, не feature|

## 2. UAV view

|Поле|Форма|Dtype|Нормализация|Назначение|
|---|---|---|---|---|
|`rgb`|`[B, 3, 256, 256]`|`float32`|ImageNet mean/std|вход StripNet|
|`text`|`list[str]` или tokens|string/int|согласно text encoder|описание сцены без location leakage|
|`geometry`|`[B, 1, 256, 256]`|`float32`|relative depth normalization|структура и масштабные признаки|
|`segmentation`|`[B, 1, 256, 256]` class IDs или `[B, 17, 256, 256]` probabilities|`uint8`/`float32`|IDs `0..16` или probabilities|spatial semantics|
|`geometry_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные depth pixels|
|`segmentation_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные segmentation pixels|
|`sample_id`|`[B]`|string|нет|только логирование, не feature|

## 3. StripNet

|Stage|Tensor|Spatial stride|Разрешённое использование|
|--:|---|--:|---|
|1|`[B, 64, 64, 64]`|4|преимущественно RGB low-level; auxiliary fusion только после отдельного обоснования|
|2|`[B, 128, 32, 32]`|8|dense segmentation/geometry кандидаты|
|3|`[B, 320, 16, 16]`|16|основной mid-level fusion|
|4|`[B, 512, 8, 8]`|32|high-level fusion и readout|
|GAP|`[B, 512]`|global|RGB anchor descriptor|
|Projection|`[B, 1024]`|global|retrieval descriptor до L2 normalization|
## 4. Fusion output

Каждый `encode_view` возвращает:

|Поле|Форма|Требование|
|---|---|---|
|`descriptor`|`[B, 1024]`|finite, L2 norm `1 +/- 1e-4`|
|`rgb_descriptor`|`[B, 1024]`|RGB anchor для диагностики|
|`modality_contributions`|`[B, 3]` или dict|text, segmentation, geometry|
|`diagnostics`|dict tensors/scalars|gates, attention mass, norms, entropy|

Диагностика не должна менять descriptor в eval mode.
## 5. Парный forward

satellite batch -> encode_view(view="satellite")   -> z_sat [B, 1024]
UAV batch       -> encode_view(view="uav")         -> z_uav [B, 1024]
similarity = z_uav @ z_sat.T / temperature
## 6. Text contrat

- Поддержать L1, L2, L3 или выбранную объединённую схему.
- Пустой satellite caption обрабатывается через explicit validity mask.
- Пустая строка не должна кодироваться как полноценный semantic signal.
- Caption не должен содержать координаты, названия районов, file names и прямые match identifiers.
- Text encoder и token budget фиксируются для честного сравнения fusion variants.
## 8. Geometry contract

- CHM и depth имеют общий ключ `geometry`, но разные preprocessing и projector parameters.
- Нельзя считать численные значения depth и CHM сопоставимыми до view-specific normalization.
- PNG допускается только для визуальной проверки. Для обучения использовать dense tensors/SafeTensors.
- Любая производная карта, например depth gradient, считается внутри documented preprocessing block.
## 9. Segmentation contract

- Канонический набор: 17 unified classes.
- Primary representation определяется командой на interface-freeze: class IDs + embedding или probabilities/logits.
- Hard RGB palette images не используются как model input.
- Редкие и отсутствующие классы не должны приводить к NaN при mask pooling.
## 10. Запрещённые признаки

- GPS и координаты.
- Название карты, района или локации.
- Индекс paired image как embedding.
- Features второй view-ветки внутри текущего encoder.
- Evaluation labels внутри preprocessing.

# Регламент совместной работы

У команды три архитектурных трека, но одна кодовая и экспериментальная система.

| Область                            | Driver       | Обязательные reviewers |
| ---------------------------------- | ------------ | ---------------------- |
| **Fusion API и registry**          | **Павленко** | Близно, Мороз          |
| Dataset и modality validation      | Мороз        | **Павленко**, Близно   |
| Training/eval benchmark            | Близно       | **Павленко**, Мороз    |
| **Condition-aware module**         | **Павленко** | Мороз                  |
| Token/bottleneck module            | Близно       | **Павленко**           |
| Role-aware module                  | Мороз        | Близно                 |
| Общая experiment matrix            | Близно       | все                    |
| **Финальная архитектурная оценка** | **все**      | **все**                |
## Этапы

### Gate 0. Environment audit

- Проверить локальные пути двух внешних проектов.
- Зафиксировать путь GTA-UAV RGB, captions, pair JSON и annotations.
- Проверить checkpoint StripNet.
- Выполнить чтение обязательного пакета.
- Создать `reports/joint/ENVIRONMENT_AUDIT.md`.
### Gate 1. Interface freeze

До реализации архитектур команда совместно утверждает:

1. Формат segmentation: IDs/embedding или probabilities.
2. Формат CHM/depth и normalization.
3. Text encoder, уровни captions и output dimension.
4. `FusionModelBase` API.
5. Common diagnostics keys.
6. Baseline config и output directory convention.

Результат: `reports/joint/INTERFACE_DECISION.md`. Изменения после freeze требуют записи причины и влияния на все три варианта.
###  Gate 2. RGB-only baseline

- Один общий StripNet-only run.
- Один общий dataloader.
- Один общий evaluation script.
- Smoke run на малом subset.
- Полный baseline минимум на seed 42, затем финальный baseline на 42/123/456.
Без подтверждённого baseline реализация fusion не переходит к полным запускам.
###  Gate 3. Independent implementation behind common API

Каждый сотрудник реализует свой модуль в отдельной feature branch. Разрешены разные внутренние операторы, но входы, выходы, loss и logging одинаковы.
### Gate 4. Pair review

Reviewer проверяет:

- shape contract;
- отсутствие cross-view leakage;
- корректность masks;
- identity/residual path;
- вычислительную сложность;
- диагностируемость вклада модальностей;
- тесты и gin config.
### Gate 5. Smoke comparison

Все три модуля запускаются:

- на одном subset;
- с одним seed;
- на одинаковом числе batches;
- с одинаковым optimizer/loss;
- с logging peak VRAM и latency.

Цель: найти ошибки интеграции, а не выбрать победителя.
### Gate 6. Full experiment matrix

После smoke comparison выполняются primary runs и выбранные ablations по общему protocol.
### Gate 7. Joint decision

Команда совместно заполняет decision table. Архитектура не выбирается по одному лучшему run. Учитываются mean, variance, compute, стабильность и интерпретируемость вклада модальностей.