# Песочница орбит

Страница `/orbit-sandbox/` — инструмент для работы с орбитальными элементами без
привязки к каталогу портала: разобрать TLE на параметры и собрать обратно, рассчитать
предварительную TLE для будущего запуска, посмотреть трассу на глобусе на любое время и
получить прогноз пролётов. Доступна без входа. Все расчёты, кроме пролётов, выполняются
в браузере (`network/static/js/orbit_math.js`, satellite.js); пролёты считает сервер
теми же функциями skyfield, что и страница станции.

## Форматы

На вход принимаются, с автоопределением по первому символу:

| Формат | Признак | Примечание |
|---|---|---|
| TLE, 2 или 3 строки | строки, начинающиеся с `1 ` и `2 ` | Проверяются длина 69, контрольные суммы, совпадение номеров |
| Alpha-5 | буква в колонках 3–7 | Номера от 100000 (`A0000` = 100000, буквы I и O пропущены) |
| GP JSON | `{` или `[` | Запись CelesTrak/Space-Track (`MEAN_MOTION`, `RA_OF_ASC_NODE`…) или массив таких записей; также `{tle0, tle1, tle2}` из SatNOGS DB |
| OMM XML | `<` | CCSDS OMM, теги с теми же именами полей |

На выход — вкладки TLE, Alpha-5, JSON и OMM XML с кнопкой копирования. Для номеров
до 99999 вкладки TLE и Alpha-5 совпадают.

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

Форма показывает элементы TLE: эпоху, среднее движение (козаевское, об/сут),
эксцентриситет, наклонение, долготу восходящего узла, аргумент перигея, среднюю
аномалию, B\*. Высоты перигея и апогея, период, большая полуось и скорость — производные,
их считает SGP4 (`satrec.a`, `alta`, `altp`), поэтому они относятся к средним элементам.
Правка любого поля пересчитывает остальные и TLE. Правка высот перигея и апогея даёт
среднее движение через обращение формулы инициализации SGP4:

```
a = (hp + ha) / (2·R⊕) + 1
e = (ha − hp) / (ha + hp + 2·R⊕)
n = ke · a^−3/2
δ = 0.75 · J2 · (3cos²i − 1) / (a² · (1 − e²)^3/2)
n_TLE = n · (1 + δ)
```

Без множителя `(1 + δ)` — так делал `faketle` из sattools — орбита 500 км получается на
несколько километров выше или ниже заданной.

## Расчёт TLE для запуска

Исходные данные: космодром (справочник из sattools или координаты), время пуска `T0`,
задержка `Δt` до прохода трассы над площадкой (по умолчанию 300 с), направление
выведения (на север — восходящий участок, на юг — нисходящий), высоты перигея и апогея,
наклонение, аргумент перигея, B\*.

Алгоритм (`launch_elements` в `orbit_math.js`):

1. Эпоха `T = T0 + Δt`; среднее движение и эксцентриситет — из высот, как выше.
2. Геодезическая широта площадки переводится в геоцентрическую:
   `φ = atan((1 − f)² · tan φ_gd)`, `f = 1/298.26`.
3. Аргумент широты `u = asin(sin φ / sin i)`; для нисходящего участка `u = π − u`.
   Если `|sin φ| > sin i`, орбита над площадкой не проходит — ошибка.
4. Смещение по долготе от узла `Δλ = atan2(cos i · sin u, cos u)`; долгота восходящего
   узла `Ω = GMST(T) + λ − Δλ`.
5. Средняя аномалия — из истинной `ν = u − ω` через уравнение Кеплера.
6. Две итерации уточнения: элементы прогоняются через SGP4 на момент `T`, по фактической
   подспутниковой точке считаются те же `(Ω, u)`, разность прибавляется. Это снимает
   короткопериодические члены J2 и разницу средних и оскулирующих элементов; итоговая
   ошибка положения меньше 0,001°.

Перенос пуска — просто новое `T0`: плоскость поворачивается вместе со звёздным временем
(≈ 0,9856° в сутки), отдельного инструмента вроде `launchtle` не нужно. Такая TLE
описывает орбиту только после выведения; всё, что раньше эпохи, — фикция. Высота в
строке «Положение» — оскулирующая и отличается от средней на величину до ±10 км.

## Расчёт TLE по вектору состояния

Когда в документации на пуск есть вектор положения и скорости на момент отделения, он
точнее геометрии над космодромом. Блок принимает X, Y, Z (км), VX, VY, VZ (км/с), время
пуска, смещение до отделения в секундах и систему координат вектора:

| Система | Что делается |
|---|---|
| Гринвичская, зафиксированная на момент пуска | Инерциальная система с осью X на меридиане Гринвича в момент КП (так даны параметры в российских документах на пуск). Поворот вокруг Z на GMST момента пуска даёт TEME |
| J2000 | Прецессия IAU-76 к среднему экватору и равноденствию даты; нутацией (≈1″) пренебрегаем |
| TEME | Без преобразования |

Алгоритм (`state_elements` в `orbit_math.js`, аналог `rv2el` из sattools):

1. Вектор в TEME → оскулирующие элементы (a, e, i, Ω, ω, ϑ) классической процедурой.
2. Средние элементы SGP4 ищутся итерацией: элементы прогоняются через SGP4 на эпоху, из
   полученных r, v считаются оскулирующие, разность с целевыми прибавляется к средним.
   Для околокруговых орбит e и ω по отдельности плохо обусловлены (короткопериодический
   член J2 — постоянное смещение вектора эксцентриситета, и поправка по e уводит его в
   минус), поэтому итерация идёт по вектору эксцентриситета (e cos ω, e sin ω) и аргументу
   широты u = ω + M. Шесть проходов дают невязку по положению в десятки метров.
3. Среднее движение — козаевское из средней большой полуоси (см. выше).

Оскулирующие элементы и невязка показываются под кнопкой: их можно сверить с таблицей в
документе (большая полуось, e, i, Ω, ω, ϑ, оскулирующий период). Средняя большая полуось в
TLE отличается от оскулирующей на несколько километров — это и есть причина, по которой
оскулирующие элементы нельзя записывать в TLE напрямую.

## Пролёты

`GET /orbit-sandbox/passes/` (только AJAX, без входа) принимает `tle1`, `tle2`, `start`
(ISO 8601, по умолчанию сейчас), `hours` (до 48 для точки, до 24 для станций),
`min_horizon` и `mode`: `stations` — подключённые станции с координатами, `point` —
`lat`, `lon`, `alt`. Ответ — список пролётов, отсортированный по восходу:

```json
[{"station": {"id": 1, "name": "…", "lat": 55.7, "lon": 37.6},
  "rise": "…", "rise_az": 229.0, "tca": "…", "tca_alt": 45.0,
  "set": "…", "set_az": 40.0}]
```

Для своей точки `station` равен `null`. Пролёт, начавшийся до `start`, в ответ не
попадает. Один адрес может сделать 30 запросов в минуту; сверх этого — 429.

## Файлы

- `network/base/views/orbit_sandbox.py` — страница и эндпоинт пролётов.
- `network/static/js/orbit_math.js` — чистая математика, единственный форматтер TLE на
  JS в проекте; тесты в `tests/js/orbit_math.test.js` против satellite.js, в том числе
  на векторе состояния из реального документа на пуск.
- `network/static/js/orbit_sandbox.js` — формы, глобус, вызов эндпоинта.
- `network/base/test_orbit_sandbox.py` — тесты эндпоинта и кросс-проверка TLE, полученной
  в JS, питоновским SGP4.