# Единый экспериментальный protocol GTA-UAV

## 1. Dataset

Primary dataset: GTA-UAV-LR.

| Компонент | Ожидаемый источник |
|---|---|
| UAV RGB | `drone/images/`, 33,763 изображений, исходно 512x384 |
| Satellite RGB | `satellite/`, 14,640 изображений, 256x256 |
| Pair labels | `cross-area-drone2sate-{train,test}.json` |
| Captions | GTA-UAV-LR-captions для UAV и satellite |
| Auxiliary maps | GTA-UAV-LR-aug SafeTensors |
| Split snapshots | `caption-test/meta/train_80.json`, `test_20.json` |
| Segmentation filter | `caption-test/meta/seg_filter.json` |

Фактические пути задаются через gin и записываются в run manifest.

## 2. Split

- Primary: cross-area.
- Same-area: только sanity check.
- Train/test split не пересоздаётся для разных fusion variants.
- Evaluation учитывает несколько допустимых satellite matches для одной UAV query.
- Диагональная оценка одного match на query считается некорректной для GTA-UAV.

### 2.1. Обязательная верификация split (Gate 0)

Унаследованные снапшоты `caption-test/meta/train_80.json` / `test_20.json` создавались скриптом `make_split.py --ratio 0.8 --seed 42`. До baseline команда обязана установить и записать в `ENVIRONMENT_AUDIT.md`:

1. К какому множеству пар применялся 80/20: ко всем парам или внутри официального `cross-area-drone2sate-train.json`.
2. Если 80/20 — случайный split по всем парам, он не эквивалентен официальному cross-area протоколу (train и test делят область → задача проще). В этом случае:
   - примary-сравнение допускается на унаследованном split (главное — одинаковость для всех вариантов);
   - финалисты дополнительно оцениваются на официальном `cross-area-drone2sate-test.json` без дообучения;
   - в отчётах оба числа маркируются явно: `split=inherited-80/20` и `split=official-cross-area`.
3. Количества пар train/test и размер satellite gallery фиксируются в manifest каждого run.

### 2.2. Числа датасета (для контроля аудита)

| Компонент | Ожидаемое значение |
|---|---|
| UAV RGB | 33,763 PNG, 512×384 |
| Satellite RGB | 14,640 PNG, 256×256, RGBA |
| Captions UAV / satellite | 33,411 / 6,546 (покрытие ~99% / ~44.7%) |
| Auxiliary maps | 48,403 (segm, depth, edge, chm) |
| Seg-filter passed | 37,498 из 48,403 (исключение ≥90% background+water) |
| Унаследованный split | train 26,966 → 24,891 после seg-filter; test 6,742 → 6,252 |
| Test gallery | ~2,684 unique satellite tiles в test_20 |

Расхождение фактических чисел с таблицей — находка data audit, а не повод молча продолжить.

## 3. Common model settings

| Параметр | Значение |
|---|---|
| Backbone | StripNet-small |
| Input size | 256x256 |
| Backbone sharing | shared satellite/UAV |
| Primary backbone state | frozen |
| Optional adaptation | одинаковые Conv-MONA stages 3-4 |
| Descriptor dim | 1024 |
| Descriptor norm | L2 |
| Segmentation classes | 17 |
| Text encoder | фиксируется на Gate 1 |

## 4. Retrieval objective

Primary objective: symmetric contrastive retrieval loss.

```math
L = w_{q2g} CE(z_{uav} z_{sat}^{T} / tau, y)
  + w_{g2q} CE(z_{sat} z_{uav}^{T} / tau, y)
```

Начальная конфигурация:

| Параметр | Значение |
|---|---:|
| `w_q2g` | 0.6 |
| `w_g2q` | 0.4 |
| `tau_init` | 0.07 |
| temperature | learnable, bounded |
| label smoothing | 0.1 |
| sampler | mutually exclusive для снижения false negatives |

Hard-negative strategy должна быть общей для всех вариантов. Нельзя включить memory bank только для одного fusion family в primary comparison.

## 5. Baselines

| ID | Конфигурация | Назначение |
|---|---|---|
| B0 | StripNet RGB-only | обязательная точка отсчёта |
| B1 | Late concat pooled auxiliary embeddings | простой multimodal baseline |
| B2 | Static additive residual | контроль против dynamic fusion |
| B3 | Multi-FiLM + additive merge | сильный общий baseline |
| A-primary | Condition-aware | трек Павленко |
| B-primary | Token/bottleneck | трек Близно |
| C-primary | Role-aware | трек Мороза |

## 6. Общие аблации

Оценочные аблации выполняются без изменения основного training protocol.

| ID | Вариант |
|---|---|
| G-AB1 | full multimodal |
| G-AB2 | без text на evaluation |
| G-AB3 | без segmentation на evaluation |
| G-AB4 | без geometry на evaluation |
| G-AB5 | RGB + text |
| G-AB6 | RGB + segmentation |
| G-AB7 | RGB + geometry |
| G-AB8 | late-only fusion |
| G-AB9 | multi-stage fusion |
| G-AB10 | frozen StripNet |
| G-AB11 | StripNet + одинаковая Conv-MONA adaptation |
| G-AB12 | shared vs view-specific auxiliary projectors |

Стохастическое отключение входных модальностей в training loop не входит в protocol.

## 7. Primary metrics

| Группа | Метрики |
|---|---|
| Retrieval | R@1, R@5, R@10, MRR, AP |
| Directions | UAV-to-satellite и satellite-to-UAV |
| Generalization | cross-area primary, same-area sanity |
| Improvement | delta к B0 по каждому seed и mean delta |
| Stability | mean, std, 95% bootstrap CI |
| Efficiency | params, trainable params, peak VRAM, latency, throughput |
| Fusion health | contribution, gate/attention entropy, descriptor variance |

## 8. Diagnostic metrics

- L2 norm descriptor.
- Per-dimension descriptor standard deviation.
- Cosine similarity между RGB-only и fused descriptor.
- Gradient norm по modality projectors и fusion core.
- Contribution каждого auxiliary path.
- Attention mass или gate statistics по модальностям.
- CKA/cosine redundancy между modality representations.
- Доля NaN/Inf и invalid auxiliary pixels.

## 9. Seeds

| Фаза | Seeds |
|---|---|
| Smoke | 42 |
| Development | 42 |
| Final primary comparison | 42, 123, 456 |
| Expensive secondary ablations | 42, если primary effect подтверждён |

## 10. Run artifacts

Каждый run сохраняет:

```text
out/<experiment_id>/
├── config/                 # копии всех gin-файлов
├── manifest.json           # commit, seed, paths, hardware, timestamp
├── metrics.csv             # epoch metrics
├── eval_report.json        # final retrieval metrics
├── diagnostics.json        # gates, attention, norms, contributions
├── model_best.safetensors  # если нужен checkpoint
├── model_last.safetensors
└── logs/
```

## 11. Предварительные decision rules

Fusion candidate допускается к финальным трём seed, если:

1. Не хуже B0 более чем на 0.5 п.п. R@1 в smoke/full seed 42.
2. Не содержит NaN/Inf.
3. Дополнительный peak VRAM не превышает 6 GB относительно B0 на согласованном batch.
4. Latency не превышает B0 более чем в 2 раза без доказанного accuracy gain.
5. Хотя бы одна дополнительная модальность имеет измеримый положительный contribution.

Primary promotion:

- mean cross-area R@1 выше B0 минимум на 1.0 п.п.;
- улучшение положительно минимум на двух из трёх seed;
- 95% bootstrap CI для парного delta не пересекает существенное отрицательное значение;
- нет критического modality collapse;
- compute укладывается в RTX 4090 24 GB.

Если thresholds не достигнуты, команда выбирает самый информативный отрицательный результат и формулирует, какая fusion hypothesis опровергнута.

## 12. Внешние ориентиры (не targets)

Из предыдущих экспериментов на GTA-UAV (другой протокол: полное обучение backbone, 100 epochs, batch 64, без auxiliary модальностей):

| Конфигурация | R@1 | Комментарий |
|---|---:|---|
| StripNet, полный fine-tuning + ImageNet pretrain | ~0.775 | верхний ориентир возможностей backbone на этих данных |
| Лучший компактный экспериментальный backbone | ~0.665 | средний диапазон |

В этом проекте StripNet заморожен (адаптация только Conv-MONA stages 3-4), поэтому B0 будет заметно ниже верхнего ориентира — это ожидаемо и нормально. Ориентиры используются только для sanity-контроля порядка величин: B0 с R@1 около нуля или выше 0.8 — признак ошибки протокола, а не выдающегося результата.

## 13. Поведение при missing modality (оценочное требование)

Для каждого primary-варианта в финальном отчёте обязательна таблица: descriptor при validity=0 для каждой auxiliary модальности по очереди (eval-time, без переобучения).

| Режим | Требование |
|---|---|
| full-modal | базовое качество варианта |
| без text / без seg / без geometry (по одному) | descriptor конечен; деградация плавная, без обвала ниже B0 более чем на оговорённый командой порог |
| только RGB (все aux отключены) | descriptor близок к RGB-якорю; cosine(fused, rgb_descriptor) фиксируется |

Это не modality-dropout-обучение, а проверка well-posedness архитектуры (см. `06_MERIDIAN_CONTEXT.md` §5); результат входит в decision table.