# Fuse Project: multimodal fusion for cross-view geo-localization

Проект для совместной разработки и экспериментального сравнения способов объединения модальностей в задаче перекрёстной геолокализации БПЛА и спутниковых изображений.

## Команда

| Сотрудник | Основной трек | Дополнительная командная роль |
|---|---|---|
| Павленко Богдан Викторович | Condition-Aware RGB-Anchored Fusion | координатор общего архитектурного API |
| Близно Максим Витальевич | Token/Bottleneck Aggregation | координатор benchmark, метрик и воспроизводимости |
| Мороз Егор Сергеевич | Role-Aware Hierarchical Fusion | координатор входных модальностей и контроля качества данных |

Все три трека реализуются в одном репозитории, используют один набор данных, один StripNet contract, одинаковые split, loss, метрики и правила отчётности. Результатом является не три изолированных исследования, а общий сравнительный проект с тремя взаимозаменяемыми fusion-модулями.

## Постановка

Для satellite-ветки доступны:

1. RGB satellite.
2. Текстовое описание satellite-сцены.
3. CHM satellite.
4. Семантическая сегментация satellite.

Для UAV-ветки доступны:

1. RGB UAV.
2. Текстовое описание UAV-сцены.
3. Карта глубины UAV.
4. Семантическая сегментация UAV.

RGB кодируется shared `StripNet-small`. Каждая ветка независимо строит L2-нормированный descriptor `[B, 1024]`. Сопоставление веток выполняется только в retrieval objective. Прямая передача признаков или метаданных между paired satellite и UAV внутри encoder запрещена.

## С чего начать

1. Прочитать [контекст MERIDIAN](docs/00_project/06_MERIDIAN_CONTEXT.md) — частью какой системы является проект и почему важна устойчивость к отсутствию модальности.
2. Прочитать [общее задание](docs/01_tasks/00_MASTER_ASSIGNMENT.md).
3. Прочитать [контракт входов и выходов](docs/00_project/01_INPUT_OUTPUT_CONTRACT.md).
4. Прочитать [регламент совместной работы](docs/00_project/02_TEAM_WORKFLOW.md).
5. Открыть своё персональное задание в `docs/01_tasks/`.
6. Изучить обязательные документы по [карте чтения](docs/02_references/00_READING_MAP.md). Важно: канонические документы — это цепочки версий, полное содержание лежит в `_version_chain/` (см. карту чтения, §0).
7. Проверить доступность GTA-UAV и двух внешних проектов по [руководству переиспользования](docs/00_project/05_REPOSITORY_REUSE_GUIDE.md).
8. До реализации согласовать общий API на совместном архитектурном ревью.

## Данные

Датасет GTA-UAV-LR и его производные расположены на Linux-сервере с RTX 4090:

| Компонент | Путь |
|---|---|
| RGB + pair JSON | `/home/servml/Документы/datasets/GTA-UAV-LR/` |
| Captions (L1/L2/L3, JSON) | `/home/servml/Документы/datasets/GTA-UAV-LR-captions/` |
| Auxiliary maps (segm/depth/edge/chm, SafeTensors) | `/home/servml/Документы/datasets/GTA-UAV-LR-aug/` |
| Split snapshots, seg-filter | `caption-test/meta/` |

Фактические пути не хардкодятся: задаются через gin и фиксируются в `reports/joint/ENVIRONMENT_AUDIT.md`.

Рекомендуемое окружение: Python 3.11, PyTorch 2.x, CUDA для RTX 4090. Системный Python 3.14 не использовать для этого проекта, так как рабочие сборки PyTorch и pytest могут отсутствовать.

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q
```

## Структура

```text
fuse_proj/
├── docs/
│   ├── 00_project/          # постановка, контракты, workflow, эксперименты, контекст MERIDIAN
│   ├── 01_tasks/            # общее и персональные задания
│   ├── 02_references/       # физические копии обязательных материалов
│   │   ├── 01_required/     #   обязательный пакет для всех
│   │   ├── 02_fusion_core/  #   канон fusion (+ _version_chain/ с полными базовыми версиями)
│   │   ├── 03_segmentation/ #   pair A (+ _version_chain/)
│   │   ├── 04_geometry/     #   pair B/C (+ _version_chain/)
│   │   ├── 05_text/         #   pair D
│   │   └── 06_paper_analyses/ # конспекты статей F/P/B/M
│   └── 03_codebase_guides/  # карты использования внешних проектов
├── vendor_reference/        # снимки ключевых файлов двух рабочих проектов (read-only)
├── src/fuse_proj/           # общий код и fusion API
├── in/config_files/         # gin-конфигурации
├── tests/                   # unit, shape и integration tests
├── experiments/             # registry и шаблоны run-артефактов
├── reports/                 # персональные и общий отчёты
└── results/                 # локальные агрегированные результаты, без весов и датасета
```

## Доступные внешние проекты

| Назначение | Локальный путь | Remote |
|---|---|---|
| Генерация depth, segmentation, CHM и SafeTensors | `C:\Users\Lisadminipc\Documents\code\depth_edges_annotate_worlduav` | `https://git.lissad.keenetic.name/Pikaliov/depth_edges_annotate_worlduav` |
| StripNet, GTA-UAV loader, loss, eval, training utilities | `C:\Users\Lisadminipc\Documents\code\caption-test` | `https://git.lissad.keenetic.name/Pikaliov/caption-test` |

`vendor_reference/` содержит копии файлов для чтения и аудита. Реализацию следует переносить осознанно в `src/fuse_proj/`, а не редактировать снимки.

## Жёсткие ограничения

- Visual backbone: `StripNet-small`, shared для satellite и UAV.
- Основной размер входа: `256 x 256`.
- Descriptor: `1024`, L2 normalization.
- Dataset: GTA-UAV-LR, primary split `cross-area`.
- Full-modal forward использует RGB, text, segmentation и view-specific geometry.
- Стохастическое отключение модальностей при обучении не является частью задания.
- Leave-one-modality-out допускается только как контролируемая оценочная аблация.
- Координаты, имена локаций и paired-view признаки не должны попадать в fusion-модуль.
- Все сравниваемые варианты используют одинаковый protocol и минимум три seed в финальном сравнении.

## Главный результат

Команда должна предоставить общий benchmark трёх семейств fusion, выбрать primary, fallback и research-arm, а также показать, какая дополнительная модальность, на каком уровне StripNet и каким оператором даёт измеримое улучшение retrieval.