forked from Pikaliov/fuze_task
fuse_proj: Initial operational package for 3 researchers (Pavlenko/Blizno/Moroz)
Multimodal fusion research on StripNet+GTA-UAV proxy: - 3 independent fusion tracks: condition-aware (A), token/bottleneck (B), role-aware (C) - Shared interfaces, protocol, dataset audit, baseline benchmarks - Canonical version-chain references to vault (SPEC, ANALYSIS, TRIAGE) - Personalized task plans and decision tables for each researcher - 3 generated DOCX task assignment files with milestones and DoD checklist - Full modality dropout diagnostics and missing-modality robustness requirements - Data contract, benchmark registry, experiment tracking infrastructure Operational documents: - docs/00_project/: MERIDIAN context, protocol, repository reuse guide, experiment specification - docs/01_tasks/: Master assignment + 3 individual researcher tracks + joint integration - docs/02_references/: Core literature, version-chain bases, code maps - docs/03_codebase_guides/: Existing code snapshots from vault - scripts/: gen_task_plans.js (DOCX generation), placeholder infrastructure - vendor_reference/: Snapshots of caption_test, depth_edges_annotate, existing SOFIA/SegModel code - reports/, results/, experiments/: Shared output structure for all 3 researchers 3 DOCX files generated from gen_task_plans.js (Times New Roman 14pt, GOST format): - План_заданий_Павленко_БВ.docx (Condition-Aware track, fusion API owner) - План_заданий_Близно_МВ.docx (Token/Bottleneck track, benchmark owner) - План_заданий_Мороз_ЕС.docx (Role-Aware track, data contract owner) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Pikaliov
96
docs/00_project/01_INPUT_OUTPUT_CONTRACT.md
Normal file
96
docs/00_project/01_INPUT_OUTPUT_CONTRACT.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Контракт входов и выходов
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user