# Контракт входов и выходов

## 1. Единица данных

Одна обучающая запись содержит UAV query и один положительный satellite candidate. Для evaluation одна UAV query может иметь несколько допустимых satellite matches.

## 2. Satellite 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 |

## 3. 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 |

## 4. StripNet contract

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

Backbone weights shared между satellite и UAV. Базовый вариант заморожен, адаптеры stages 3-4 рассматриваются одинаково для всех fusion families.

## 5. Выход fusion-модуля

Каждый `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.

## 6. Парный forward

```text
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
```

Между двумя вызовами `encode_view` нет обмена признаками. Положительные и отрицательные связи используются только при вычислении retrieval objective.

## 7. Text contract

- Поддержать 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.