Виртуальный полигон для дрона

Визуализация полёта самолёта (drone_flight_demo)

WebGL-приложение показывает движение летательного аппарата в реальном времени:
модель Engee отправляет состояние по UDP, приложение Genie принимает его и отдаёт
браузеру, а страница проигрывает измерения без рывков и без движения назад.

┌──────────────────────────┐   UDP 14 × Float64    ┌──────────────────────────┐
│ drone_flight_demo.engee  │ ────────────────────► │ drone_graphics_app.jl    │
│ блок «3D сцена»          │   127.0.0.1:5150      │ Genie: /state, /trace    │
└──────────────────────────┘                       └────────────┬─────────────┘
                                                                │ HTTP
                                                                ▼
                                                   ┌──────────────────────────┐
                                                   │ браузер: public/flight.js│
                                                   │ + public/mesh.bin        │
                                                   └──────────────────────────┘

Состав проекта

Как работает клиент public/flight.js

Клиент не интегрирует координаты по своим стеновым часам. Он принимает поток
измерений с модельным временем t, складывает их в буфер и проигрывает буфер по
монотонным часам playT. Благодаря этому уже показанное положение никогда не
переопределяется, и аппарат не может поехать назад.

Приём данных

• GET /state опрашивается каждые POLL_MS = 40 мс (≈25 Гц), одновременно не
  более MAX_INFLIGHT = 2 запросов. Таймаут запроса — 2 с.
• Каждый ответ — одна строка CSV из 19 полей (см. «Формат /state»).
• Пакет считается новым по счётчику rx (поле 14). Повторный rx отбрасывается.
• Если между двумя ответами пропущено больше одного пакета (rx > prevRx + 1),
  клиент запрашивает GET /trace?since=<prevRx> и добавляет пропущенные
  измерения в буфер. Это закрывает паузы HTTP и потери UDP.

Буфер измерений

Каждое измерение хранит: t (модельное время), координаты, углы, линейные и
угловые скорости, rx, время приёма. Вставка отсортированная, поэтому /trace
может дослать пропущенное «в середину».

• Оценка скорости модельного времени: медиана Δt_модели / Δt_стены по
  последним 41 пакетам, ограничение 0.2…3.0.
• История интервалов между пакетами: последние 12 значений.
• Адаптивная задержка воспроизведения:
  delay = 1.6 × p90(интервалов), ограничение 0.12…1.6 с.
  При 25 Гц это ≈0.12 с, при 1 Гц и секундных пробелах — до 1.6 с.
• Буфер хранит delay + 8 × интервалов + 2 с истории, но не более 800 точек.

Воспроизведение

• playT — модельное время того, что сейчас нарисовано; только растёт.
• playT += dt × rate × corr, где rate — оценка скорости модельного времени,
  а corr = clamp(1 + err / 0.6, 0.7, 1.4) удерживает playT на delay позади
  самых свежих данных.
• Положение между двумя измерениями считается кубическим Эрмитом: узлы —
  координаты, касательные — скорости из модели. Углы интерполируются по
  кратчайшей дуге.
• Выбег (COAST_MAX = 1.0 с модельного времени): если впереди данных нет,
  аппарат продолжает движение по последней скорости, а не замирает.
• Только вперёд: если после выбега очередная точка оказалась позади уже
  показанной, из поправки убирается отрицательная продольная составляющая
  (поперечная остаётся). Счётчик таких коррекций — backCorrect (в HUD не
  выводится); u в HUD — число кадров, когда данных впереди не было.
• При перезапуске модели (модельное время ушло назад больше чем на 0.5 с)
  буфер и история очищаются, playT привязывается заново.
• Если вкладка была скрыта и playT отстал сильнее, чем хранится история,
  выполняется один прыжок вперёд — без обратного движения.

Управление и HUD

• Кнопка Camera переключает свободную камеру и камеру «погони».
• Мышь: перетаскивание — вращение, колесо — приближение, двойной клик —
  сброс камеры. Reset UI перезагружает страницу, Reset UDP вызывает
  POST /reset (перезапуск UDP-сокета).
• Строка HUD:

🟢 pkts:  1895 ✕ 0  hz: 21.0  age:  8ms  t: 75.76  buf: 70  d:0.13  r:0.65  u:4067
   p=(x,y,z)  ψ=...  γ=...  θ=...  r=0  v=...

Как должна выглядеть модель

В модели drone_flight_demo.engee используется блок «3D сцена» — причинный
компонент с 13 скалярными входами. Порядок входов фиксирован и совпадает с
порядком полей пакета:

Параметры блока:

Требования к CommonCode блока:

• сигнатура вызываемого метода должна принимать 13 входов плюс t;
• в сокет отправляются 14 Float64 в big-endian в порядке портов, последнее
  поле — float(t);
• используется Sockets.localhost и параметр port;
• при остановке модели сокет закрывается в terminate!.

Минимальный фрагмент, который должен быть в CommonCode:

function (c::Block)(t::Real, xp, yp, zp, psi, gamma, theta,
                    vx, vy, vz, dpsi, dgamma, dtheta, st)
    bytes = UInt8[]
    for val in (xp, yp, zp, psi, gamma, theta,
                vx, vy, vz, dpsi, dgamma, dtheta, st, float(t))
        append!(bytes, reinterpret(UInt8, [hton(val)]))
    end
    send(c.udpsocket, Sockets.localhost, port, bytes)
end

Параметры решателя в файле модели: SolverName = Euler, SolverType = fixed-step, FixedStep = 0.1, StopTime = 50. StopTime задаёт длительность
прогона; SampleTime блока задаёт частоту пакетов (25 Гц). Фактическая скорость
модельного времени на поде может быть ниже реального времени (≈0.6–0.8×) — клиент
измеряет её сам и не требует точного совпадения.

Меш аппарата: локальный кадр после подготовки — +Z нос, +Y вверх, +X левое
крыло. Ориентация строится как R = Rψ · Rθ · Rγ (авиационная
последовательность 3-2-1). Размеры меша берутся в его собственных единицах и
переводятся в метры: если наибольший габарит больше MESH_MM_THRESHOLD = 100,
меш считается заданным в миллиметрах (масштаб 0.001), иначе — в метрах.
Клетка земли равна GROUND_CELL = 1.0 м, поэтому аппарат рисуется в истинном
масштабе относительно сетки. Точка вращения — pivotFrac = -0.1 от высоты.

Оформление сцены — стерильная сетка для тестирования: почти белые клетки,
тёмно-серые линии и средне-серое небо. Цвета задаются константами SKY_COLOR,
CELL_COLOR, LINE_COLOR, толщина линий — LINE_PX. Прежняя версия с
оранжевой шахматкой сохранена в public/flight_orange.js.

Передача данных

UDP-пакет модели

• Адрес: 127.0.0.1, порт 5150 (параметр port блока).
• Длина: 14 × 8 = 112 байт, Float64, big-endian (hton).
• Порядок: x, y, z, ψ, γ, θ, vx, vy, vz, dψ, dγ, dθ, state_id, t.
• Пакет отправляется на каждом шаге блока; t — модельное время в секундах.

Формат /state

Одна строка CSV, 19 полей:

Точность: координаты — 4 знака, углы и скорости — 5, t — 6 знаков после
запятой.

/trace?since=<rx>

Возвращает по строке на каждый пакет с rx > since в том же 19-полевом формате.
Кольцевой буфер хранит последние TRACE_MAX = 1200 пакетов (≈1 мин при 25 Гц,
несколько минут при 1 Гц). При перезапуске модели (модельное время ушло назад
больше чем на 0.5 с) буфер очищается.

/reset (POST)

Перезапускает UDP-сокет и увеличивает restarts. Используется кнопкой
Reset UDP, если приём «залип» или порт был занят.

Запуск

1. Собрать меш (если менялся OBJ):

   ;julia obj2bin.jl drone_model.obj public/mesh.bin
   

2. Запустить приложение:

   engee.genie.start(joinpath(@__DIR__, "drone_graphics_app.jl"),
                     log_file = joinpath(@__DIR__, "log.txt"), open_url = true)
   

   Первый запуск иногда завершается ошибкой «Unknown error while starting» —
   повторите через несколько секунд.

3. Запустить модель drone_flight_demo обычным образом. Пакеты пойдут на
   127.0.0.1:5150, страница начнёт движение.

4. Остановка:

   engee.genie.stop(joinpath(@__DIR__, "drone_graphics_app.jl")); sleep(5)
   

Параметры клиента, которые можно менять

Диагностика

Важные ограничения

• Гарантия «только вперёд» достигается ценой задержки: при 1 Гц картинка
  отстаёт от реального времени до ~1.6 с. Уменьшение задержки вернёт риск
  коротких остановок между редкими пакетами.
• При пропуске данных длиннее COAST_MAX аппарат останавливается в точке
  выбега; после прихода данных он продолжает движение вперёд, а поперечная
  ошибка исправляется. Продольного отката при этом не происходит.
• Порядок полей жёстко одинаков в трёх местах: CommonCode блока, приёмник
  drone_graphics_app.jl, страница flight.js. Менять его нужно сразу везде.