fuze_task/docs/00_project/03_EXPERIMENT_PROTOCOL_GTA_UAV.md

Единый экспериментальный 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.

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 сохраняет:

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.