fuze_task/docs/01_tasks/00_MASTER_ASSIGNMENT.md

Общее задание команде

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

Работа выполняется совместно. Каждый сотрудник обязан понимать входной contract, baseline, loss и evaluation всех трёх вариантов, а не только своего модуля.

2. Что требуется решить

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

View	RGB	Text	Geometry	Segmentation
Satellite	satellite image	satellite caption	CHM	satellite segmentation
UAV	UAV image	UAV caption	relative depth	UAV segmentation

Один shared StripNet-small кодирует RGB. Fusion-модуль должен использовать дополнительные сигналы и сформировать descriptor, подходящий для retrieval между UAV query и satellite gallery.

2.1. Зачем это нужно (большая система)

Проект — архитектурный отбор fusion-механизма для Teacher системы MERIDIAN на быстром прокси (StripNet + GTA-UAV вместо DINOv3 + production-данных). Победившее семейство будет перенесено на DINOv3-Teacher и станет KD-таргетом для RGB-only edge-Student. Отсюда два следствия:

1. Нас интересует класс механизма и причина его успеха, а не выжатые гиперпараметрами проценты.
2. Вторичный критерий отбора — корректное поведение при отсутствии модальности (validity mask = 0): выход конечен, RGB-путь не искажён. Подробности и таблица безопасных/опасных классов операторов: docs/00_project/06_MERIDIAN_CONTEXT.md §5.

Modality dropout в training loop при этом в задание НЕ входит (это следующий этап MERIDIAN); требуется только архитектурная готовность к нему.

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. Что подаётся на вход

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

Полный contract описан в docs/00_project/01_INPUT_OUTPUT_CONTRACT.md.

4. Что должно получаться на выходе

Для каждой view независимо:

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

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

5. Главная цель экспериментов

Проверить, может ли 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.

6. Общие архитектурные кандидаты

Track A: Condition-aware

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

Track B: Token/bottleneck

RGB stages, text, segmentation и geometry преобразуются в компактный token pool. Cross-modal reasoning выполняется через mutable queries, bottleneck tokens или soft experts.

Track C: Role-aware

Segmentation используется как spatial semantics, geometry как dense structural signal, text как global semantic context. Операторы и порядок fusion соответствуют роли модальности.

7. Общие этапы работы

Этап 0. Изучение материалов

• Прочитать docs/00_project/06_MERIDIAN_CONTEXT.md (контекст системы и терминология).
• Прочитать пять документов из docs/02_references/01_required/.
• Прочитать TRIAGE_teacher_fusion_dropout_2026-06-11.md (свежий аудит fusion-литературы; минимум §6a и сквозные выводы).
• Прочитать fusion core пакет; канонические документы читать цепочкой: полная база из _version_chain/ + верхняя дельта (см. 00_READING_MAP.md §0).
• Прочитать персональный paper package.
• Создать evidence matrix: механизм, исходная задача, переносимость, риск, ожидаемый эффект.
• Отделить факты статьи от проектных предположений.

Этап 1. Environment audit

• Проверить caption-test.
• Проверить depth_edges_annotate_worlduav.
• Найти GTA-UAV RGB и captions.
• Найти/generated GTA-UAV auxiliary SafeTensors.
• Проверить StripNet checkpoint.
• Записать версии Python, PyTorch, CUDA, GPU.
• Создать reports/joint/ENVIRONMENT_AUDIT.md.

Этап 2. Data audit

• Проверить 20 satellite и 20 UAV samples.
• Проверить shape, dtype, range и validity каждой модальности.
• Проверить совпадение spatial layout RGB и auxiliary maps.
• Проверить alpha channel satellite RGB.
• Проверить 17 segmentation classes.
• Проверить пустые captions (особенно satellite: покрытие ~44.7%).
• Проверить multi-match pair labels.
• Верифицировать split: установить, как meta/train_80.json/test_20.json соотносятся с официальными cross-area-drone2sate-{train,test}.json. Если 80/20 — случайный split по всем парам, он НЕ является cross-area; тогда финальная оценка дополнительно выполняется на официальном cross-area test, а решение фиксируется в INTERFACE_DECISION.md.
• Сформировать таблицу найденных аномалий.

Этап 3. Interface freeze

• Утвердить representation segmentation.
• Утвердить normalization depth и CHM.
• Утвердить text encoder и caption levels.
• Утвердить fusion API.
• Утвердить common diagnostics.
• Утвердить experiment naming.
• Создать reports/joint/INTERFACE_DECISION.md.

Этап 4. Baseline

• Перенести StripNet wrapper.
• Перенести GTA-UAV loader без изменения split semantics.
• Перенести multi-match evaluation.
• Настроить symmetric retrieval objective.
• Запустить B0 smoke.
• Запустить B0 seed 42.
• После проверки запустить B0 seeds 123 и 456.
• Создать reports/joint/BASELINE_REPORT.md.

Этап 5. Архитектурное проектирование

Каждый сотрудник обязан до кода:

• предложить минимум три варианта внутри трека;
• сравнить их таблицей;
• выбрать primary и fallback;
• показать tensor flow для satellite и UAV;
• указать StripNet insertion stages;
• записать формулы;
• оценить params/FLOPs/VRAM;
• определить falsification criteria;
• пройти совместное design review.

Этап 6. Реализация

• Реализовать variant за общим API.
• Добавить gin config.
• Добавить shape/unit tests.
• Добавить diagnostics.
• Добавить smoke config.
• Выполнить взаимное code review.

Этап 7. Smoke benchmark

• B0, A-primary, B-primary, C-primary.
• Один subset, seed 42, одинаковое число steps.
• Сравнить loss, R@K sanity, VRAM, latency, NaN.
• Исправить integration defects.

Этап 8. Primary comparison

• Полный seed 42 для трёх variants.
• Отсечь варианты, не прошедшие decision rules.
• Запустить финалистов на 123 и 456.
• Выполнить bootstrap CI и paired comparison.

Этап 9. Ablation

• Leave-one-modality-out на evaluation.
• Single-modality auxiliary pairs.
• Late-only vs multi-stage.
• Frozen vs common Conv-MONA setting.
• Shared vs view-specific projectors.
• Персональные ablations каждого трека.

Этап 10. Итог

• Свести общую таблицу.
• Выбрать primary, fallback, research-arm.
• Описать failure cases.
• Зафиксировать, какие hypotheses подтверждены или опровергнуты.
• Подготовить reports/joint/FINAL_COMPARISON.md.
• Подготовить reports/joint/DECISION_RECORD.md.

8. Обязательные baselines

ID	Реализация
B0	StripNet RGB-only
B1	Late concat: pooled RGB + pooled text + pooled seg + pooled geometry
B2	Static additive residual с фиксированными weights
B3	Multi-FiLM + ADD

Нельзя сравнивать сложные варианты только друг с другом без B0-B3.

9. Общая документация каждого варианта

В design report должны быть:

1. BLUF: primary/fallback и ожидаемая причина успеха.
2. Формализация входов и выхода.
3. Evidence matrix минимум по 8 источникам.
4. Сравнение трёх кандидатов.
5. Architecture diagram.
6. Tensor table для satellite и UAV.
7. Equations.
8. Pseudocode.
9. Params/FLOPs/VRAM estimate.
10. Diagnostics.
11. Experiment matrix.
12. Risks и falsification.

10. Результаты, которые считаются содержательными

Положительный результат:

• устойчивое улучшение retrieval;
• понятный вклад минимум одной auxiliary modality;
• приемлемая стоимость;
• повторяемость по seed.

Отрицательный результат также принимается, если:

• protocol корректен;
• baseline воспроизводим;
• причина провала диагностирована;
• показано, какой механизм не работает и при каких условиях.

11. Запрещено

• Использовать GPS/coordinates/location name.
• Передавать features второй view в текущий encoder.
• Менять split, loss или gallery только для одного варианта.
• Выбирать метрики после просмотра результатов.
• Сравнивать runs с разными data filters без явного отдельного эксперимента.
• Кодировать auxiliary maps как цветные RGB renderings для обучения.
• Скрывать failed runs из отчёта.

12. Файлы сдачи

Сотрудник	Design report	Implementation report
Павленко	reports/pavlenko/DESIGN.md	reports/pavlenko/IMPLEMENTATION_AND_RESULTS.md
Близно	reports/blizno/DESIGN.md	reports/blizno/IMPLEMENTATION_AND_RESULTS.md
Мороз	reports/moroz/DESIGN.md	reports/moroz/IMPLEMENTATION_AND_RESULTS.md

Общие:

• reports/joint/ENVIRONMENT_AUDIT.md
• reports/joint/INTERFACE_DECISION.md
• reports/joint/BASELINE_REPORT.md
• reports/joint/FINAL_COMPARISON.md
• reports/joint/DECISION_RECORD.md

13. Milestones

Milestone	Проверяемый результат
M0	окружение и данные доступны
M1	interface frozen
M2	RGB-only baseline воспроизведён
M3	три design reports приняты
M4	три implementations проходят tests
M5	smoke benchmark завершён
M6	primary comparison завершён
M7	ablations и статистика завершены
M8	финальное решение принято

14. Ориентировочный календарь (8 недель)

Календарь — ориентир для самоконтроля, не замена milestones. Если этап задерживается больше чем на 3 рабочих дня, блокер фиксируется в WORKLOG.md и обсуждается с руководителем.

Неделя	Этапы	Milestone
1	Этап 0 (чтение) + Этап 1 (environment audit)	M0
2	Этап 2 (data audit) + Этап 3 (interface freeze)	M1
3	Этап 4 (baseline B0–B3)	M2
4	Этап 5 (design reports, перекрёстное ревью)	M3
5	Этап 6 (реализация за общим API)	M4
6	Этап 7 (smoke) + начало Этапа 8	M5
7	Этап 8 (primary comparison, 3 seeds для финалистов)	M6
8	Этап 9 (ablations) + Этап 10 (итоговые отчёты, decision meeting)	M7, M8

Чтение литературы не заканчивается на неделе 1: evidence matrix дополняется по мере проектирования, но после M1 новые источники не могут менять общий interface без RFC.

15. Контрольные вопросы самопроверки (до design report)

Каждый сотрудник должен уметь ответить письменно:

1. Почему geometry-каналы satellite и UAV нельзя кодировать одним projector без view-specific нормализации?
2. Что произойдёт с вашим оператором, если segmentation полностью отсутствует у sample (validity = 0)? Покажите формулой.
3. Почему чисто multiplicative gating опасен для RGB-якоря?
4. Чем modality collapse отличается от modality shortcut и какой диагностикой ловится каждый?
5. Почему нельзя оценивать GTA-UAV по diagonal-only similarity matrix?
6. Какой ваш baseline сильнее всего угрожает вашей же гипотезе и почему?