# FlyGuard · ML-ядро

Обнаружение посторонних объектов в тоннеле метро по данным 3D-лидара
Hesai Pandar128. Кейс 05, ЛЦТ-2026.

Это **ядро обработки**: облако точек на входе, решение о препятствии на выходе.
Узел ROS 2, транспорт, контейнер и визуализация живут отдельно и сюда не
входят — ядро от них не зависит и проверяется без ROS вообще.

---

## Чем это не является

Не нейросетевой детектор общего назначения. Конвейер собран по схемам
зрительной системы дрозофилы, и каждая стадия — это конкретный нейропиль с
конкретной функцией, а не слой, подобранный перебором:

```
облако точек 0.3–0.9 млн, 10 Гц
   │
   ├─ RETINA           омматидиальная решётка → дальностный образ 128 × N
   ├─ HALTERES         плоскость рельсов: крен, тангаж, высота сенсора
   ├─ LAMINA           диспаритет 1/R → ON/OFF, центр-окружение на 3 масштабах
   ├─ MEDULLA / LP     T4/T5 → LPTC: скорость поезда без одометрии
   ├─ LOBULA           LC11: кандидаты; разрез компоненты по контрасту
   ├─ MUSHROOM BODY    KC → APL → MBON: новизна формы (без меток)
   │                   + обученное считывание MBON (с метками из физики)
   ├─ FAN-SHAPED BODY  накопление лучей в координатах пути
   ├─ CENTRAL COMPLEX  накопление улик в координатах пути, треки
   └─ DESCENDING       два порога с гистерезисом → решение
```

Ничего про геометрию сенсора не захардкожено: решётка лучей, высота установки,
крен и тангаж **калибруются по самим данным** на первых кадрах. В записях
встречаются две раскладки скана (3600 азимутов на 360° и 1200 на 120°) и две
высоты установки (1.31 и 1.70 м) — ядро работает с обеими без правок.

---

## Что нужно интеграции: один класс, один вызов

```python
from flyguard.pipeline import FlyGuard, Params
from flyguard.mushroom_body import MushroomBody
from flyguard.mbon_readout import MbonReadout

fg = FlyGuard(Params(),
              memory=MushroomBody.load("artifacts/mushroom_body.npz"),
              readout=MbonReadout.load("artifacts/mbon_readout.npz"))

res = fg.process(cloud)          # cloud: flyguard.cdr.PointCloud2
if res is None:
    ...                          # первые 12 кадров уходят на калибровку решётки
else:
    d = res.decision             # detected, distance, confidence, emergency, objects
    res.total_ms                 # время обработки кадра
```

Требования к входу: `flyguard.cdr.PointCloud2` — поля `x, y, z, intensity`,
порядок точек как в сыром CDR. Конвейер **хранит состояние между кадрами**
(решётка, плоскость пути, ось пути, треки, накопитель), поэтому один экземпляр
обслуживает один поток данных; для параллельных сценариев нужны разные
экземпляры.

Выход `Decision`: `detected`, `distance` (м), `confidence` (0…1),
`emergency` (флаг экстренного торможения), `objects` (список подтверждённых
треков с id, дистанцией и габаритами).

Всё считается на **CPU**, GPU не требуется. Медиана обработки кадра — 43 мс
при бюджете 100 мс (замер по стадиям, один процесс, EXPERIMENTS п. 7.4).

Ламину можно перенести на **NVIDIA GPU** (`Params(device="auto")` или
`"cuda"`, модуль `flyguard/device.py` с переходом на CPU при любом сбое карты).
Замерено на RTX 5070 Ti: ламина 5.8 → 2.9 мс с копированием туда и обратно,
то есть кадр 43 → ~40 мс, — остальные 80 % времени кластеризация и геометрия,
которые видеокарта не ускоряет. Поэтому по умолчанию `device="cpu"`: выигрыш
в 3 мс не стоит отдельного образа и `--gpus all` на машине проверки.

---

## Структура

```
flyguard/          ядро: стадии обработки, память, считывание
  bag.py  cdr.py            чтение rosbag2 и разбор CDR без ROS
  device.py                 выбор CPU / NVIDIA GPU и переход на CPU при сбое
  retina.py  geometry.py    решётка лучей, плоскость рельсов, ось пути
  lamina.py  medulla.py     контраст (на CPU или GPU), движение
  lobula.py                 кандидаты
  mushroom_body.py          память тоннеля (без меток)
  mbon_readout.py           обученное считывание (с метками)
  track_readout.py          считывание по истории трека — инструмент замера
  fan_body.py               накопление в координатах пути
  central_complex.py        треки и улики
  descending.py             решение
  pipeline.py               сборка
  export.py                 3D-рамки, время до столкновения, маркеры RViz
  synth.py                  вставка предметов трассировкой лучей
tools/             обучение, оценка, разбор, полигон с аугментациями
tests/             50 тестов, запускаются без данных и без ROS
docs/              методика и результаты
artifacts/         обученные модели
```

---

## Как запустить

```bash
pip install -r requirements.txt
pytest tests -q          # или без pytest: python tests/run_tests.py
```

Через Docker (подробно — [docs/DOCKER.md](docs/DOCKER.md)):

```bash
./docker-run.sh build
docker compose run --rm test         # тесты
docker compose run --rm info         # что видно из контейнера: CPU, GPU, CUDA
docker compose run --rm evaluate     # ложные тревоги
docker compose run --rm benchmark    # полигон
```

Для обучения на видеокарте — `pip install -r requirements-gpu.txt` и
`--device cuda` у `train_mbon.py`, `train_mushroom_body.py`, `evaluate.py`.

Записи лидара в репозиторий не кладутся. Положите их рядом
(`../data/for_hackathon/...`) или укажите путь:

```bash
set FLYGUARD_DATA=D:\lidar\data
```

Обучение и оценка:

```bash
python tools/make_training_set.py                    # размеченная выборка
python tools/train_mbon.py --device cuda --baseline  # считывание MBON
python tools/evaluate.py --mbon-dir artifacts/mbon_folds   # ложные тревоги
python tools/make_benchmark.py --memory artifacts/mushroom_body.npz \
    --mbon-dir artifacts/mbon_folds                  # дальность обнаружения
python tools/plot_benchmark.py                       # кривые и график
python tools/compare_benchmark.py было.json стало.json   # правка парно
```

Большой бэг `new_data` (90 ГБ) не распаковывается целиком — инструменты
читают его кусками прямо из архива (`--tar`, по умолчанию
`../датасет/new_data` или `FLYGUARD_NEW_DATA`):

```bash
python tools/make_training_set.py --new-data 0:110 --out data/cache/training_set_nd.npz
python tools/train_mbon.py --device cuda --data data/cache/training_set.npz \
    --data data/cache/training_set_nd.npz --train-only new_data_ --out nd.npz
python tools/eval_new_data.py --shards 110: \
    --readout было=artifacts/mbon_readout.npz --readout стало=nd.npz --out nd.json
```

Проверка на второй половине честная: вставки идут только в первую, а
вторую модель не видит ни в каком виде (EXPERIMENTS п. 17.3).

Синтетику организаторов (`cloud_with_fake_obj`, 10 предметов) сверяет с
эталоном отдельный инструмент. Разметки к бэгу нет, но вставленные точки не
лежат на элевациях колец, и эталон извлекается из самого бэга (п. 18.2):

```bash
python tools/eval_org_synth.py                        # итоговые настройки
python tools/eval_org_synth.py --set half_width=1.6 --set h_top=0
```

В этом бэге нет поля `ring`, а порядок точек сбит вставками: `retina.py`
восстанавливает кольца по элевации и раскладывает такие кадры по углам точек.
До этой правки ядро на нём не обрабатывало ни одного кадра (п. 18.1).

Любое поле `Params` меняется без правки кода: `--set h_lo_core=0.28 --set
k_sigma=0.75` у `make_benchmark.py`, `evaluate.py`, `make_training_set.py` и
`check_obstacle.py`. Два прогона полигона сравнивайте только парно —
`compare_benchmark.py` считает, сколько наблюдений перевернулось в каждую
сторону на одних и тех же вставках. Итоговые таблицы двух прогонов шумят
сильнее, чем меняет их большинство правок (EXPERIMENTS п. 16.1).

Тяжёлые шаги сами раскладываются по бэгам на процессы — записей пять, физических
ядер шесть, и это вся доступная зернистость: конвейер держит состояние между
кадрами, поэтому разрезать одну запись нельзя. Замерено: полигон 134 → 36 с,
сбор выборки 96 → 26 с на облегчённой конфигурации, то есть 3.7–3.8×, и файл на
выходе совпадает с последовательным **побайтово**. Отключается `--jobs 1`.

Для замера задержки кадра `--jobs 1` обязателен: под пятью процессами время
кадра растёт с 32 до 56 мс. Это свойство замера, а не конвейера, поэтому
`evaluate.py` в параллельном режиме печатает задержку как `nan` — чтобы такое
число нельзя было случайно привести в отчёте.

---

## Где мы сейчас

| Метрика | Значение | Чем измерено |
|---|---|---|
| Реальный объект 0.67 × 1.35 м на 55 м | **99.5 %** кадров | `tools/check_obstacle.py` |
| Синтетика организаторов, 10 предметов | **9 из 10** верно | `tools/eval_org_synth.py` |
| Ложные тревоги, leave-one-bag-out | **5.7 трека на км**, 8.4 % кадров | `tools/evaluate.py --mbon-dir` |
| То же без обученного считывания | 11.9 на км, 20.3 % кадров | там же, без `--mbon-dir` |
| На незнакомой линии (памяти нет) | **12.8 на км**; без считывания 36.1 | `tools/evaluate.py --no-memory` |
| Вторая половина `new_data`: другой день, 3.41 км, не видена при обучении | **11.7 на км**, 17.9 % кадров | `tools/eval_new_data.py` |
| Дальность (полигон, 15 560 наблюдений) | человек стоя: рабочая дальность **100 м**, P@50 = 0.72, P@100 = 0.52, P@150 = 0.46 | `tools/plot_benchmark.py` |
| Человек, упавший на пути | P@50 = **0.50** (было 0.27), рабочая дальность 20 м | там же |
| Обработка кадра | медиана 33 мс из бюджета 100 мс; на ядре уровня стенда жюри 55 / 65 мс (медиана / p95) | контейнер, EXPERIMENTS п. 18.5, 19.5 |
| Разделение «знакомое / новое» (без учителя) | ROC AUC 0.905 | `tools/tune_memory.py` |
| Считывание MBON «предмет / тоннель» (с учителем) | ROC AUC **0.986** | `tools/train_mbon.py` |

Проверка всегда **leave-one-bag-out**: память обучается на всех записях, кроме
проверяемой. Иначе цифры лгут — подавлять конструкции, которые сам же и
запомнил, умеет кто угодно, а на приватном тесте будет новый участок.

---

## Что честно не работает

Разобрано замерами, подробности — в `docs/EXPERIMENTS.md`:

* **За 200 м на этих участках не увидит никто**: прямая видимость в тоннелях
  121–167 м, дальше линия взгляда упирается в стену кривой. На отдельных
  перегонах и того меньше — 49–90 м.
* **Мелкие предметы на большой дальности невозможны с этим сенсором**: ведро
  (0.1 м²) на 160–190 м даёт один луч, каска и бутылка — ноль.
* **За 80–90 м прирельсовая зона не наблюдается вовсе**: луч скользит по
  полотну, и самая низкая видимая точка у оси пути оказывается выше головки
  рельса на 0.1–0.6 м.
* Привыкание внутри проезда сделано и **отвергнуто замером** — п. 10.
* **Яркость как признак мы себе не засчитываем.** Абсолютной шкалы
  интенсивности в записях нет: медиана по кандидатам обстановки 3…7 в пяти
  бэгах и 23.5 в шестом. Вставка берёт яркость реальных возвратов с тех же
  лучей, то есть признак намеренно обесточен, и дальность из-за этого
  занижена — настоящий предмет был в 1.47 раза ярче окружения. Разбор — п. 11.1.

---

## Документация

* `docs/ALGORITHM.md` — что делает каждая стадия и почему именно так.
* `docs/EXPERIMENTS.md` — все замеры, включая отрицательные результаты.
* `docs/CONNECTOME.md` — что взято из коннектома как число, а что как идея.