Загрузить файлы в «reports»

reports/1.1 Подготовительный этап (Конспект).md

@@ -0,0 +1,315 @@
+---
+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, стабильность и интерпретируемость вклада модальностей.