# ПОПРАВКА — планшетный тренажёр «тепловизор → дальность → упреждение»

Веб-приложение для планшета: берёт картинку с тепловизора, само находит дрон по
горячей отметке, считает **дальность** (по видимому размеру), **скорость** (по
перемещению за кадр) и **точку прицеливания с упреждением**. По нажатию «ОГОНЬ»
проверяется, попал бы виртуальный снаряд.

Второй игрок летает над полем на маленьком самолёте-дроне, вы пытаетесь попасть.
Ничего не стреляет по-настоящему — попадание считается математически.

> **Возвращаетесь к доработкам?** Откройте [`JOURNAL.md`](JOURNAL.md) — там история
> решений, найденные грабли, инфраструктура и чек-лист проверок.

---

## Быстрый старт

```
thermal-range-game/
├── index.html          ← приложение (открывать это)
├── presentation.html   ← лендинг с описанием и кнопками скачивания
├── core.js             ← математика и обработка кадра (тестируется в Node)
├── app.js              ← интерфейс, источники видео, HUD
├── style.css
├── build.mjs           ← сборка downloads/ (один файл + zip)
├── downloads/
│   ├── popravka.html   ← приложение одним файлом
│   └── popravka.zip    ← исходники + тесты
├── tests/
│   ├── core.test.js    ← автотесты
│   ├── diag.js         ← диагностика: оценка против истины по кадрам
│   └── tune.js         ← подбор окон трекера
└── README.md
```

`index.html` — это само приложение; `presentation.html` — витрина для него.
Пересобрать `downloads/` после правок: `node build.mjs`.

1. Скачайте папку целиком на планшет.
2. Откройте `index.html` в Chrome (файлы должны лежать рядом — это не один файл).
3. При первом запуске откроется справка, а сцена уже будет работать:
   **демо-режим** рисует дрон, летающий по известной траектории.

Если браузер капризничает с камерой из `file://`, поднимите локальный сервер
в этой папке:

```bash
python -m http.server 8080
# затем на планшете: http://<ip-компьютера>:8080/
```

или

```bash
npx serve .
```

---

## Демо-режим — обязательно начните с него

Демо-сцена не «нарисована для красоты»: рендерер строит кадр по пинхол-модели,
то есть рисует дрон **ровно того углового размера**, который соответствует его
реальной дальности (`ширина_px = f · S / R`). Если приложение показывает
дальность, близкую к истинной, — вся цепочка (угол обзора → размер пятна →
дальность → скорость → упреждение) настроена верно.

**Сценарий демо фиксированный:**

| Параметр | Значение |
|---|---|
| Высота | 100 м |
| Удаление | 400 м (наклонная дальность ~410 м) |
| Скорость | 150 км/ч (41,7 м/с) |
| Цель | самолётного вида, 3 м размах × 4 м длина (`S = √12 ≈ 3,46 м`) |
| Полёт | галс поперёк поля зрения, разворот за кадром |

Эта цель стоит первой строкой в таблице дронов и выбрана по умолчанию.
Камера демо изначально наклонена вверх на 14° — как если бы вы подняли планшет
на дрон.

Что проверить:

| Проверка | Как убедиться |
|---|---|
| дальность | в панели ~410 м, пятно ~9 px на рабочем кадре |
| скорость | ~41–43 м/с, то есть 150 км/ч |
| курс | около 0° — цель идёт вправо поперёк кадра |
| упреждение | ~2,5°, кружок смещён от центра на эту величину |
| попадание | совместите кружок с целью (в демо — тяните кадр) и жмите ОГОНЬ |

**Если выбрана другая цель.** Сценарий не масштабируется под габарит: цель в 1 м
на 400 м занимает меньше 2 px и не детектируется. Приложение предупредит об этом
всплывающим сообщением и попросит выбрать цель 3×4 м или крупнее. Это физика,
а не сбой: на такой дальности мелкий объект действительно не виден.

---

## Подключение тепловизора

Приложение умеет четыре источника (⚙ → «Источник»).

### 1. USB-тепловизор как UVC-камера — самый простой путь
Большинство потребительских тепловизоров (HikMicro, InfiRay/Xinfrared, Guide,
Pulsar) с USB-C отдают обычный UVC-поток или работают как веб-камера в режиме
«камера/запись».

- Подключите тепловизор к планшету через OTG-переходник.
- ⚙ → «Источник» = **Камера** → «Найти камеры» → выберите устройство из списка.
- Если внешняя камера не видна, откройте её штатным приложением, включите режим
  веб-камеры и вернитесь в браузер.

Работает через `getUserMedia`, поэтому нужен Chrome и разрешение на камеру.

### 1а. Тепловизор с AV-выходом через граббер

Отдельный частый случай: тепловизор отдаёт аналоговый **композитный сигнал**
(PAL/NTSC), дальше переходник на USB и **видеограббер**, а он уже втыкается в
планшет. С точки зрения Android это обычная USB-камера, и путь тот же —
«Камера» → «Найти камеры».

Что важно:

- **Граббер должен быть UVC-совместимым.** Чипы MS2109/MS2130 и подобные работают
  без драйверов. Старые «EasyCap» на UTV007 в Android обычно не поднимаются.
- **Планшет должен поддерживать внешние USB-камеры.** Это свойство прошивки, а не
  приложения. Проверяется за минуту: если в списке камер после подключения граббера
  появилась вторая — всё в порядке. Если нет, приложение бессильно: система его
  не видит. Помогает проверка любым другим приложением для USB-камер.
- **Питание.** Граббер ест от OTG. Если не определяется — подключите через
  USB-хаб с внешним питанием.
- **Ставьте нативное разрешение** 720×576 (PAL) или 720×480 (NTSC). Режим
  «1920×1080» у таких грабберов — апскейл, деталей он не добавляет, а мыло
  мешает детектору.

**Чёрные поля.** У AV-грабберов вокруг картинки почти всегда рамка: сигнал 4:3
вписан в кадр 16:9, плюс overscan самого PAL. Это надо убрать ползунками
«Обрезка полей» в ⚙ → «Оптика», иначе реальная картинка занимает меньше пикселей,
чем приложение считает, и **дальность завышается пропорционально** полям.
Фокус объектива от обрезки не меняется — видимый угол обзора пересчитывается сам.

**Чересстрочность.** PAL — это 50 полукадров в 25 кадрах. На движении у пятна
появляется «гребёнка», центроид подрагивает. Смягчается понижением разрешения
обработки до 320 px (кадр усредняется) и длинным окном оценки дальности.

**Задержка.** USB-граббер добавляет 100–300 мс. На точность не влияет (кадры
обрабатываются как есть), но при наведении планшетом ощущается как «плывущая»
картинка.

### 2. Сетевой поток MJPEG

Если тепловизор раздаёт Wi-Fi и отдаёт MJPEG по HTTP (частый вариант:
`http://192.168.1.10:8080/stream` или `/mjpeg`, `/video`):

- ⚙ → «Источник» = **Сетевой поток MJPEG**, вставьте URL, «Подключить поток».
- **Важно:** чтобы приложение могло *анализировать* кадр, поток должен отдаваться
  с заголовком `Access-Control-Allow-Origin: *`. Иначе браузер покажет видео, но
  запретит читать пиксели — приложение честно напишет «только видео (CORS)».
  Лечится либо настройкой камеры, либо реверс-прокси на вашем сервере.

### 3. RTSP — только через релей

Браузеры **не умеют** RTSP. Если камера отдаёт только RTSP, поставьте рядом
(на ноутбуке/роутере) перепаковку в MJPEG или WebRTC:

```bash
ffmpeg -rtsp_transport tcp -i rtsp://192.168.1.10:554/stream \
       -vf fps=25 -q:v 6 -f mpjpeg -listen 1 http://0.0.0.0:8081/
```

и укажите в приложении `http://<ip>:8081/`. MJPEG не сжимает с потерями
межкадрово, поэтому угловой размер пятна не «плывёт» — для измерения это плюс.

### 4. Видеофайл

Для отладки и разбора полётов: запись экрана тепловизора или сохранённый поток.
Файл крутится по кругу.

---

## Калибровка (без неё дальность будет врать)

Дальность считается по формуле пинхол-модели:

```
R = S · f / w        f = (W/2) / tan(FOV/2)
```

- `S` — реальный габарит цели, м (⚙ «Габарит цели»);
- `FOV` — **полный горизонтальный** угол обзора тепловизора, ° (⚙ «Угол обзора»);
- `W` — ширина кадра в пикселях;
- `w` — измеренная ширина горячего пятна в пикселях.

### Откуда взять угол обзора

Из паспорта объектива. Маркировка `25 mm F1.0 384×288` угла не даёт — смотрите
характеристики: обычно пишут `FOV: 17.5° × 13.1°` или `12.5°×9.4°`. Берите
**горизонтальное** значение. Если паспорт даёт только фокусное и размер пикселя,
посчитайте: `FOV = 2·atan(W·pitch / (2·f_mm))`.

### Габарит цели и таблица дронов

Слева открывается таблица на **10 целей**. В каждой строке — название, размах и
длина в метрах (от 1,0 до 40,0 с шагом 0,1). Выбранная строка задаёт цель,
по которой считается вся баллистика; названия и размеры сохраняются в браузере.

Из двух габаритов берётся **характерный размер**:

```
S = √(размах × длина)
```

Это эквивалентный диаметр эллипса с осями «размах» и «длина». Удобство в том,
что площадь эллипса не зависит от ракурса: как ни разверни цель, `S` один и тот
же, и дальность не «прыгает» при повороте силуэта.

**Проверка калибровки:** поставьте дрон на известном расстоянии, наведите
тепловизор и подберите габарит в таблице так, чтобы показанная дальность
совпала. Это быстрее, чем угадывать по паспорту.

### Остальные параметры

| Параметр | Смысл |
|---|---|
| Скорость пули, м/с | по умолчанию **900** — как у винтовочной пули. Чем медленнее, тем больше упреждение и тем интереснее |
| Гравитация, м/с² | по умолчанию **9,81** — падение пули учитывается. 0 — стрельба «лазером» |
| Радиус поражения, % от габарита | по умолчанию **50 %** от `S`. Задаётся в процентах, а не в метрах: иначе для цели в 1 м и в 40 м требования были бы несопоставимы |
| Порог обнаружения | чуть выше шума: поднимите, если ловит облака/землю, опустите, если теряет дрон |
| Разрешение обработки | анализ идёт на уменьшенном кадре. 480 px — баланс; 640 точнее по дальности, но тяжелее |
| Инверсия | включите, если у тепловизора «чёрное горячее» |

Диагностика: включите **«Показывать маску детектора»** — красным подсветится то,
что приложение считает целью. Если красное пятно не на дроне, крутите порог.

---

## Как играть

1. Выберите цель в таблице слева (или создайте свою: название плюс размах и длина).
2. Пилот поднимает дрон, вы наводите тепловизор и ждёте, пока приложение само
   поймает отметку (или **тапните по дрону в кадре** — принудительный захват).
3. **Сетка в центре кадра — это прицел.** Пуля уходит строго по оси камеры, то есть
   по центру. Планшет с тепловизором и есть оружие: повернули планшет — повернулся
   и ствол.
4. **Оранжевый кружок** смещён от центра на величину упреждения. Это место, куда
   надо загнать цель: тогда ось камеры окажется впереди дрона ровно на столько,
   сколько нужно пуле. Двигайте планшетом (в демо — тяните кадр), пока цель не
   окажется внутри кружка. Строка `СОВМЕЩЕНИЕ` покажет `ГОТОВ`, кружок позеленеет.
   Радиус кружка равен допуску поражения — «цель внутри» и значит «попадёте».
5. Жмите **ОГОНЬ**. Результат: `ПОПАДАНИЕ` или `ПРОМАХ` с указанием, на сколько
   градусов цель была вне кружка.
6. Счёт `попаданий / выстрелов` — в верхней панели.

Строка `КУРС` показывает направление движения цели в кадре (0° — вправо,
90° — вниз). При движении оно берётся из смещения отметки, у почти неподвижной
цели — из ориентации силуэта (в этом случае рядом с цифрой стоит «ось»).

### Компас и наклон

Над перекрестием — лента азимута с цифрой и строкой `наклон / крен`, как в
тепловизорах. Данные берутся с датчиков планшета (`deviceorientationabsolute`,
при отсутствии — `deviceorientation`).

- **Магнитный азимут** возможен только при наличии магнитометра. Если его нет,
  под лентой будет написано «азимут относительный» — угол считается от того
  положения, в котором датчик стартовал. У многих планшетов магнитометра нет;
  это ограничение железа, не приложения.
- **Наклон** (угол места) и **крен** работают и без магнитометра, на акселерометре.
  Кнопка `⟲` в шапке принимает текущее положение за ноль — удобно, если планшет
  закреплён на штативе под наклоном.
- Данные датчиков, как и камера, требуют **защищённого контекста**: `https://`
  или файл, открытый локально. На `http://` по IP браузер их не отдаст.

### Подсказка под перекрестием

Строка `двигайте вправо 6,2°  вверх 0,4°` говорит, куда именно повернуть планшет.
Когда всё совмещено — зелёное `СОВМЕЩЕНО`. По краям сетки подписаны стороны:
`верх`, `низ`, `лево`, `право`.

Полоска под телеметрией — устойчивость решения. Зелёная: цель идёт ровно,
можно стрелять. Красная: трек дёргается, ждите.

Клавиши (для отладки на компьютере): `Space` — огонь, `L` — захват по центру,
`F` — таблица дронов, `H` — справка, стрелки — наведение в демо.

---

## Что именно считается

**Дальность.** В пинхол-модели объект ширины `S` на дистанции `R` занимает
`w = f·S/R` пикселей — точно, без малоугловых приближений. Обратно:
`R = f·S/w`. Здесь `S = √(размах × длина)` — характерный размер цели из таблицы.

Размер пятна `w` берётся **не по рамке**, а как эквивалентный диаметр по площади:
`w = 2·√(A/π)`. Рамка квантуется по пикселям — цель шириной 8 px даёт рамку 7, 8
или 9, то есть ±12% по дальности. Площадь набирается из десятков пикселей и даёт
тот же геометрический размер с ошибкой ~1%. На демо-сцене это видно сразу:
ошибка дальности падает с 12% до 0,2%.

**Курс.** Направление движения в кадре — по проекции положения и положения через
0,5 с (учитывает перспективу). Если цель почти неподвижна, направление берётся
из ориентации силуэта: большая ось пятна через центральные моменты второго
порядка,

```
θ = ½ · atan2(2μ₁₁, μ₂₀ − μ₀₂)
```

и вытянутость `√(λ₁/λ₂)` как мера, насколько силуэт вообще имеет ось.

**Скорость.** Двумя линейными регрессиями: направление `d(t)` — по короткому окну
(~0,3 с, чтобы успевать за манёвром; шум центроида для этого достаточно мал),
дальность `R(t)` — по длинному (~1,2 с, потому что размер пятна шумит сильнее
углового положения).

```
v = R · ď + Ṙ · d
```

Первое слагаемое — тангенциальная (боковая) скорость, второе — скорость
сближения. Регрессия по направлению, а не по положению, важна: шум дальности
иначе раздувает оценку скорости.

**Упреждение.** Решается уравнение встречи — момент `t`, когда снаряд догонит цель:

```
|P + V·t| = V_снар · t
(V·V − V_снар²)·t² + 2(P·V)·t + P·P = 0
```

Берётся наименьший положительный корень, точка прицеливания `A = P + V·t`.
С гравитацией вектор запуска корректируется: `v₀ = A/t − ½·g·t·ŷ`.

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

Для чисто бокового движения это сводится к классическому
`ψ = atan(v_цели / v_пули)` — угол упреждения **не зависит от дальности**
(время полёта растёт ровно настолько, насколько растёт промах).

**Попадание.** Численно минимизируется расстояние между снарядом
`v₀t + ½g t²` и целью за время полёта. В демо-режиме цель берётся по **истинной**
траектории дрона, в остальных режимах — по экстраполяции текущей скорости.

---

## Точность и ограничения — читать обязательно

- **Дальность — монокулярная оценка размера.** Ошибка обратно пропорциональна
  числу пикселей на цель. Цель шириной 20 px даёт ~±5 %, шириной 8 px — уже
  ±12 %. Дрон на 150 м в объектив 12° будет 2–3 px: там дальность бесполезна.
  Практический диапазон — пока дрон занимает хотя бы ~10 px.
- **Размер пятна зависит от порога.** Меняя порог, вы меняете и `w`, и дальность.
  Калибруйте `S` при том пороге, с которым будете играть.
- **Один кадр — одно измерение.** Быстрый дрон на малой частоте кадров
  «размазывается» или прыгает; трек может сорваться. 25–30 fps комфортно.
- **Скорость — это оценка по прошлому.** Боковая составляющая — по последним
  ~0,3 с, скорость сближения — по ~1,2 с. На резком манёвре оценка отстаёт, и
  упреждение врёт. Это не баг, а физика: по прошлому нельзя предсказать
  разворот. Красная полоска качества — сигнал «не стреляй».
- **Есть предел, который не обойти.** Даже если положение и скорость цели
  известны идеально, за время полёта снаряда (0,6–0,7 с) маневрирующий дрон
  уходит от расчётной точки. На демо-сцене «идеальный» выстрел промахивается
  на ~0,8 м, а реальный — на ~1,15 м. Разница в 0,35 м — это и есть цена
  оценки по кадрам; остальное — манёвр цели.
- **Эквивалентный диаметр зависит от порога.** Меняя порог, вы меняете площадь
  пятна, а значит и дальность. Калибруйте габарит при том пороге, с которым
  будете играть.
- **Фон.** В жару земля и камни теплее неба. Вычитание фона убирает статичный
  тёплый мусор, но движущиеся тёплые объекты (люди, машины) будут ловиться —
  тапните по дрону, чтобы захват был именно на нём.
- **CORS.** Поток с чужого origin без `Access-Control-Allow-Origin` не даст
  читать пиксели. Это ограничение браузера, не приложения.

---

## Тесты

Математика вынесена в `core.js` и проверяется без браузера:

```bash
node tests/core.test.js
```

Проверяется: оптическая модель и обратное проецирование, восстановление
дальности, оценка скорости по зашумлённому треку, решение задачи встречи,
попадание/промах, гравитационная поправка, детектор областей, и полный цикл
на синтетической демо-сцене (рендер → детектор → дальность → скорость →
упреждение → выстрел по истинной траектории).

---

## Сборка и публикация

```bash
node build.mjs
```

Собирает то, что лежит в разделе «Скачать» на лендинге:

- `downloads/popravka.html` — приложение одним файлом (CSS и JS встроены внутрь);
- `downloads/popravka.zip` — исходники, тесты и этот README.

Сайт полностью статический, бэкенда нет. Раскладка:

| Путь | Что это |
|---|---|
| `/presentation.html` | лендинг |
| `/index.html` | само приложение |
| `/downloads/popravka.html` | приложение одним файлом |
| `/downloads/popravka.zip` | архив с исходниками |

Для nginx удобно сделать лендинг страницей по умолчанию:

```nginx
root /var/www/popravka;
index presentation.html index.html;
```

Тогда `/` — витрина, `/index.html` — приложение, `/downloads/…` — скачивание.
На хостингах, которые жёстко отдают `index.html` как страницу по умолчанию
(GitHub Pages, Netlify), лендинг будет доступен по `/presentation.html`.

## Идеи для развития

- запись и разбор сессии (телеметрия в CSV);
- несколько целей одновременно (сейчас — одна);
- оценка дальности по второй камере/стереопаре — убирает главный источник ошибки;
- «ветер» и снижение скорости снаряда по дистанции;
- рейтинг пилота: сколько секунд он держал ровный курс под обстрелом.
