added docs

docs/processing.md

@@ -0,0 +1,475 @@
+# Режимы обработки
+
+Процессор (`data_processor`) превращает предобработанные коллекции в результат
+выбранного режима. Режимов четыре: pass-through, B-scan, GPR и 3D SAR; в списке
+**Mode** под кнопками управления они называются `pass_through`, `bscan`, `gpr` и `sar3d`.
+Режим и его настройки меняются
+на ходу, сбор при этом не перезапускается. Физический смысл обработки объяснён в
+главе [Как работает радар](principles.md), здесь — что делает каждый режим и каждая
+его настройка.
+
+## Когда применяются настройки
+
+Изменённая настройка обработки сразу уходит процессору. Программа записывает живые
+настройки в `python_app/runtime/processing_live.json` с новым номером ревизии.
+Процессор перечитывает файл примерно раз в 100 мс и пересчитывает новейшую
+сохранённую коллекцию, а в режиме B-scan — все сохранённые.
+
+Если программа не смогла проверить или записать настройки, поля возвращаются к
+последним опубликованным значениям и появляется сообщение
+`Failed to update live processing settings: …` (в веб-интерфейсе —
+`Failed to apply web live settings: …`). Неверную правку таблицы антенн окно
+отклоняет сразу, сообщением **Invalid Antenna Geometry**. Если файл не принял сам процессор,
+он продолжает работать с последними принятыми настройками и пишет предупреждение в
+свой журнал `python_app/runtime/logs/data_processor.err.log`.
+
+GPR и 3D SAR рисуют только результаты текущей ревизии. После изменения программа до
+0,8 с ждёт пересчитанный результат, поэтому старая картинка на экране не мелькает.
+Если процессор не работает, вид остаётся пустым до следующего результата.
+
+Часть настроек только перерисовывает готовый результат: параметры вида pass-through,
+**Subtract mean A-scan** и **Scans to show (stopped)** в B-scan, **Render mode** в GPR,
+**SAR_CLOUD_THRESHOLD**, **Zoom (%)** и **SAR_MARK_ENABLE** в 3D SAR. Они сохраняются в
+профиль, но процессору не передаются.
+
+У страниц GPR и 3D SAR свои поля для одинаковых по смыслу настроек: номера антенн,
+границы дальности, полоса частот, скорость, угол обзора, вычитание среднего,
+выравнивание пар. Процессор получает значения со страницы выбранного режима, а в
+pass-through и B-scan — со страницы GPR. Поэтому переключение между GPR и 3D SAR
+меняет и эти значения: угол обзора по умолчанию — 0° в GPR и 19,5° в 3D SAR.
+
+Границы полосы частот (**Start (MHz)**, **Stop (MHz)**, **F_START MHz**,
+**F_STOP MHz**) не выходят за развёртку прибора, а у радиофотонного радара — за его
+выходную полосу. Значения за пределами программа подрезает к границе; если это
+случилось после изменения развёртки, в журнале появляется
+`Processing frequency limits were clamped to the active radar sweep.`
+
+## Pass-through
+
+Показывает предобработанный S21 каждой пары по частоте: модуль в дБ (20·lg|S21|) и
+фазу в градусах. Обработки нет; режим нужен, чтобы проверить сигнал, калибровку и
+референс. Подпись кривой — `in<вход>/out<выход>`. У одиночного LibreVNA и
+радиофотонного радара в режимах pass-through и B-scan снимается только пара `0:0`,
+если оба ВЧ-ключа в `mock` или у обоих одно положение. Результаты других режимов здесь не
+рисуются: после переключения на pass-through экран ждёт первого результата этого
+режима.
+
+Все параметры этого режима только перерисовывают график.
+
+| Параметр | По умолчанию | Что делает |
+| --- | --- | --- |
+| **Show magnitude** | включён | показывает график модуля |
+| **Show phase** | включён | показывает график фазы |
+| **Unwrap phase** | выключен | убирает скачки фазы на 360° (развёртывает её); шкала фазы подбирается по данным, без развёртки она закреплена на ±180° |
+| **Switch combos** | пусто — все пары | список пар `вход:выход` через запятую, например `0:0,1:0`. При ошибке в записи показываются все пары, а в журнале — `Invalid pass-through switch-combo filter.` |
+| **Fix magnitude Y range** | выключен | закрепляет шкалу модуля; без неё шкала подбирается по данным |
+| **Y min (dB)**, **Y max (dB)** | −100 и 0 | границы закреплённой шкалы, от −240 до 240 дБ; доступны при включённой **Fix magnitude Y range** |
+
+## B-scan
+
+Для каждой пары строит А-скан и укладывает А-сканы последовательных развёрток в
+изображение: по горизонтали номер развёртки (**Sweep #**), по вертикали дальность
+(**Range (m)**). На экране — одна пара; её выбирают в списке **B-scan pair** в
+секции ключей (пары записаны как `вход : выход`), а кнопка **Next Combination**
+переходит к следующей: сначала меняется выход, затем вход, после последней пары снова
+первая. В списке все пары, которые есть в истории, независимо от текущего списка пар
+сбора. Список и кнопка доступны только в режиме B-scan, кнопка — когда пар хотя бы
+две.
+
+Как строится А-скан:
+
+1. Из развёртки берутся точки в полосе от **Start (MHz)** до **Stop (MHz)**. Если их
+   меньше двух, профиля нет, и развёртка в изображение не попадает.
+2. Обратное преобразование Фурье без окна.
+3. Отсчёт с временем t соответствует пути c·t (c = 299 792 458 м/с). Дальность
+   отсчитывается от **Cut (m)**: d = (c·t − 2·Cut) / 2, показываются отсчёты с
+   0 ≤ d ≤ **Max depth (m)**.
+4. Значение — модуль, вещественная часть или фаза отсчёта (**Axis**), умноженное на
+   d в степени **Gain**.
+
+| Параметр | По умолчанию | Пределы | Что делает |
+| --- | --- | --- | --- |
+| **Axis** | `abs` | `abs`, `real`, `phase` | что рисовать: модуль, вещественную часть или фазу (в радианах). Для `abs` — шкала от тёмного к светлому, для остальных — сине-бело-красная, симметричная относительно нуля |
+| **Cut (m)** | 0,824 | 0–2 м | дальность, с которой начинается изображение; всё ближе отрезается, а ось дальности начинается с нуля в этой точке |
+| **Max depth (m)** | 1,0 | 0,1–20 м | сколько метров дальности показывать после **Cut (m)** |
+| **Gain** | 1,0 | 0–3 | усиление с дальностью: значение умножается на d^Gain, чтобы далёкие слабые отражения были видны рядом с близкими |
+| **Start (MHz)**, **Stop (MHz)** | 100 и 8800, подрезаются по развёртке | в пределах развёртки | полоса частот, по которой строится А-скан |
+| **Scans to show (stopped)** | 50 | 1–1000 | сколько последних развёрток показывать и пересчитывать, когда сбор остановлен |
+| **Subtract mean A-scan** | выключен | — | вычитает из каждого столбца средний по показанным развёрткам А-скан: неподвижные отражения (горизонтальные полосы) пропадают, остаётся то, что меняется |
+
+Во время сбора изображение показывает последние развёртки в пределах истории: не
+больше 50 и не больше ёмкости колец `preprocessed` и `results`. Если истории меньше,
+чем задано, в журнале появляется предупреждение
+`B-scan is set to show W sweeps but only R are retained; the image shows what history there is.`
+Если ось дальности изменилась (другие **Cut (m)**, **Max depth (m)** или полоса),
+изображение начинается заново.
+
+Когда сбор остановлен, изменение настройки B-scan пересчитывает всё изображение:
+через 0,3 с после последнего изменения программа заново отправляет процессору
+сохранённые развёртки (до **Scans to show (stopped)** штук) и собирает картинку
+из ответов. Так одно изображение никогда не смешивает разные настройки. Пересчёт
+возможен, только если конвейер в этом сеансе запускала эта же программа и процессор
+ещё работает. Развёртки, которые процессор не вернул, в картинку не попадают, и в
+журнале появляется `B-scan replay recovered R of S re-sent sweeps; the image leaves the others out.`
+Если не вернулась ни одна, остаётся прежнее изображение из истории.
+
+Если хотя бы один ВЧ-ключ работает с настоящим железом (`driver_mode: "native"`),
+B-scan требует ровно одну пару сбора:
+`B-scan with native switches requires exactly one run combo (now N)`.
+
+## GPR
+
+Строит изображение плоскости земли перед радаром когерентной обратной проекцией по
+всем выбранным парам и находит на нём объекты. Объекты отображаются на картинке и
+уходят клиентам TCP-локатора.
+
+Порядок обработки:
+
+1. Выбор антенн: номера из **Input positions** и **Output positions**, у которых есть
+   строка в таблице геометрии. Пустое поле — все антенны с геометрией.
+2. Вычитание среднего предыдущих коллекций и поправка на движение (раздел «Общие
+   шаги GPR и 3D SAR»).
+3. А-скан каждой пары в полосе **Start (MHz)**–**Stop (MHz)** с окном Ханна.
+4. Выравнивание пар по дальности (**PAIR_DEPTH_EQUALIZE**) и нормировка каждой пары
+   на медиану её А-скана в пределах **Min depth (m)**–**Max depth (m)**; нормировка
+   выполняется всегда.
+5. Сетка 300 × 300 точек на плоскости земли: поперёк — от крайних выбранных антенн
+   с запасом 2 м в обе стороны, вдоль — дальность от 0,1 м до **Max depth (m)**.
+   Положение плоскости земли относительно радара задают **Radar height (m)** и
+   **Look angle (°)**.
+6. В каждой точке — сумма вкладов всех пар с весом компенсации дальности (степень
+   **Range compensation power**, вес не больше 5). Яркость — модуль суммы; точки ближе
+   **Min depth (m)** остаются нулевыми.
+7. Карта сглаживается и нормируется к максимуму, затем на ней ищутся объекты.
+
+Поиск объектов. Программа берёт самый яркий пик и выделяет вокруг него связную
+область ярче 0,75 пика. Область меньше 10 см² отбрасывается. Положение объекта —
+взвешенный центр яркой части. Затем окрестность объекта гасится, и поиск
+повторяется. Он останавливается, когда очередной пик слабее **Object threshold fraction**
+от максимума карты, и не идёт дальше 10 шагов. Для каждого объекта считается оценка:
+
+- `peak` — яркость пика;
+- `combined` — 0,45 × яркость + 0,25 × когерентность (насколько вклады пар совпадают
+  по фазе) + 0,20 × превышение над местным фоном + 0,10 × контраст (отношение к
+  фону). Каждое слагаемое приведено к диапазону 0–1.
+
+Объект считается боковым лепестком более сильного, если он не ярче 0,85 его пика,
+сдвинут поперёк не меньше чем на 0,35 м, по дальности — не больше чем на 0,70 м, а
+среднеквадратичное по парам расхождение путей волны до обоих объектов не больше 0,2 м.
+С включённой **Remove sidelobe objects** такие объекты удаляются из списка и
+стираются с карты.
+
+Какие объекты показываются и уходят локатору:
+
+1. Только внутри окна **Visible X min (m)**–**Visible X max (m)** и
+   **Visible Z min (m)**–**Visible Z max (m)**; то же окно задаёт границы графика.
+2. Отбор по числу: если **Max detected objects** (N) и **Draw top M objects** (M)
+   больше нуля, то при числе объектов больше N не показывается ни один (сцена считается
+   засорённой), иначе показываются M лучших по оценке.
+3. Фильтр приближения: объект показывается, только если он виден в
+   **Approach min frames** коллекциях подряд и смещается так, как должен смещаться
+   неподвижный предмет при движении радара к нему: между соседними коллекциями не
+   больше 2 с, сдвиг поперёк не больше 0,45 м, сдвиг по дальности отличается от
+   ожидаемого (скорость × cos угла обзора × время) не больше чем на 0,12 м или на
+   0,85 ожидаемого, смотря что больше. При значении 1 фильтр выключен.
+
+| Параметр | По умолчанию | Пределы | Что делает |
+| --- | --- | --- | --- |
+| **Tx geometry**, **Rx geometry** | из профиля | — | таблицы положений антенн, см. [Окно программы](desktop.md) |
+| **Input positions** | номера с геометрией, которые есть в парах сбора (если таких нет — все с геометрией) | номера через запятую | приёмные антенны в обработке; пустое поле — все с геометрией |
+| **Output positions** | так же для выходов | номера через запятую | передающие антенны в обработке; пустое поле — все с геометрией |
+| **Min depth (m)** | 2,0 | 0–50 м | ближняя граница дальности изображения и нормировки. Если она не меньше **Max depth (m)**, изображение пустое |
+| **Max depth (m)** | 14,0 | 0,1–50 м | дальняя граница сетки и изображения |
+| **Range compensation power** | 0,1 | 0–5 | степень компенсации ослабления с расстоянием: вклад умножается на ((R_tx·R_rx) / (R_tx,оп·R_rx,оп))^p, где R_tx,оп и R_rx,оп — расстояния от антенн пары до опорной точки на земле под серединой пары, на дальности 5 м; вес не больше 5. 0 — без компенсации |
+| **Object threshold fraction** | 0,7 | 0–1 | поиск объектов останавливается на пике слабее этой доли максимума |
+| **Score mode** | `combined` | `peak`, `combined` | как считать оценку объекта (см. выше) |
+| **Motion mode** | `int_minus` | `int_minus`, `int_focus` | поправка на движение: полная или только расфокусирующая часть, без сдвига по дальности |
+| **Look angle (°)** | 0,0 | от −90 до 90° | наклон радара вниз: задаёт плоскость земли, поправку на движение и фильтр приближения. При ±90° плоскость не определена (`Ground BP is undefined at a look angle of 90 degrees`) |
+| **Direction sign** | 1 | −1 или 1 | знак поправки фазы на движение. Подсказка в программе: +1 — более поздние частоты дальше. В 3D SAR не используется |
+| **Ignore socket speed** | выключен | — | включена — скорость берётся из поля **Speed (m/s)**; выключена — из клиента локатора, а поле подставляется, пока клиент 5 с не присылал скорость |
+| **Speed (m/s)** | 0,0 | от −100 до 100 м/с | скорость радара вдоль земли, положительная — к сцене. 0 — поправки нет. Редактируется при включённой **Ignore socket speed** |
+| **Render mode** | `heatmap` | `heatmap`, `objects_only` | вид: карта с объектами или только объекты (без пересчёта) |
+| **Max detected objects** | 5 | 0–10000 | N в отборе по числу; 0 — без отбора |
+| **Draw top M objects** | 2 | 0–10000 | M в отборе по числу; 0 — без отбора |
+| **Approach min frames** | 3 | 1–100 | длина цепочки коллекций для фильтра приближения; 1 — фильтр выключен |
+| **Start (MHz)**, **Stop (MHz)** | 3000 и 6000 | в пределах развёртки | полоса частот А-сканов |
+| **Radar height (m)** | 1,25 | 0–50 м | высота начала осей радара над землёй |
+| **Visible X min (m)**, **Visible X max (m)** | крайние антенны ± 2 м | от −100 до 100 м | окно объектов и графика поперёк; перепутанные min и max программа меняет местами, ширина не меньше 0,1 м |
+| **Visible Z min (m)**, **Visible Z max (m)** | 0 и 14 | 0–100 м | окно объектов и графика по дальности; так же не уже 0,1 м |
+| **Subtract mean of previous collections** | включён | — | см. «Общие шаги GPR и 3D SAR» |
+| **Mean count** | 10 | 0–10000 | сколько предыдущих коллекций усреднять; 0 — не вычитать |
+| **PAIR_DEPTH_EQUALIZE** | включён | — | выравнивание уровней пар по дальности |
+| **Remove sidelobe objects** | включён | — | удалять объекты, похожие на боковые лепестки |
+
+Изменение **Max detected objects**, **Draw top M objects** и окна видимости
+передаётся процессору, только пока выбран режим GPR.
+
+Изображение (**GPR coherent BP — ground plane**): по горизонтали **X (m)**, по
+вертикали **Range (m)**. В режиме `heatmap` — цветная карта и объекты белыми ромбами
+с оценкой (`0.83`); в режиме `objects_only` — только объекты красными кругами с
+подписью `0.83 | x=1.2 | z=5.4`, а к заголовку добавляется `Objects Only`. Передающие
+антенны показаны красными треугольниками, приёмные —
+синими; они видны, если **Visible Z min (m)** не больше нуля (тогда нижний край
+графика немного опускается ниже нуля).
+
+GPR требует хотя бы двух разных пар сбора и таблиц геометрии, а в парах сбора должны
+быть все сочетания выбранных входов и выходов: для входов 0, 1 и выходов 0, 1 — пары
+`0:0`, `0:1`, `1:0`, `1:1`. Те же требования и сообщения — у 3D SAR. Сообщения при
+отказе:
+`GPR requires at least 2 distinct run combos (now N)`,
+`GPR requires non-empty Tx/Rx geometry in run_config`,
+`GPR input positions are missing from geometry config: [...]`,
+`GPR output positions are missing from geometry config: [...]`,
+`GPR run combos do not cover selected input/output positions: [...]`.
+Трассы коллекции должны идти в порядке списка пар сбора, иначе процессор отбрасывает
+коллекцию с ошибкой в своём журнале.
+
+На рабочей станции с процессором Intel i7-8700 кадр GPR из 16 пар по 1031 точке
+считается примерно за 0,13 с.
+
+## 3D SAR
+
+Считает трёхмерное изображение объёма над землёй перед радаром на видеокарте NVIDIA
+(CUDA). Алгоритм и имена настроек взяты из исследовательского ноутбука
+`Multi_depthnorm_clean.ipynb` (ячейки 1 и 5); ноутбук хранится вне репозитория.
+
+Порядок обработки:
+
+1. Выбор антенн (**INPUT_IDX**, **OUTPUT_IDX**), вычитание среднего предыдущих
+   коллекций и поправка на движение (раздел «Общие шаги GPR и 3D SAR»).
+2. А-скан каждой пары в полосе **F_START MHz**–**F_STOP MHz** с окном Ханна; у всех
+   пар коллекции сетка частот должна совпадать.
+3. Выравнивание пар (**PAIR_DEPTH_EQUALIZE**) и нормировка на медиану
+   (**SAR_NORMALIZE_EACH_FRAME**).
+4. Апертура: текущая коллекция и до **SAR_FRAME_RADIUS** предыдущих. Антенны
+   предыдущих коллекций сдвигаются на путь, который радар проехал со скоростью
+   **SPEED_M_S**; более старые коллекции входят с меньшим весом (от 1 у текущей до 0,8 у
+   самой старой). Коллекции, которые не удалось обработать, пропускаются.
+5. Сетка вокселей с шагами **SAR_VOXEL_M X**, **SAR_VOXEL_M Y**, **SAR_VOXEL_M Z** в осях
+   сцены: поперёк — от
+   крайних выбранных антенн с запасом 2 м, по высоте — **SAR_Y_RANGE_M min**–**SAR_Y_RANGE_M max**,
+   вдоль земли — все точки, расстояние которых по оси обзора лежит в пределах
+   **MIN_DEPTH**–**MAX_DEPTH**. **SAR_X_SIZE_M** и **SAR_Z_SIZE_M** больше нуля
+   меняют ширину и длину сетки относительно того же центра.
+6. Обратная проекция в каждом вокселе с компенсацией дальности
+   (**SAR_USE_COMPENSATION**, степень **COMP_RANGE_POWER**, вес не больше 5).
+   Воксели вне **MIN_DEPTH**–**MAX_DEPTH** по оси обзора остаются нулевыми.
+7. Сглаживание по Z и X (гауссово, 1,5 вокселя) и поиск максимума на опорных
+   плоскостях — тех, что не ближе 0,3 м к верхней и нижней границе высоты.
+8. Фон кадра и CLEAN (см. ниже) и проекции.
+
+Объём при настройках по умолчанию и антеннах примера с переключением стимула — около
+10,6 млн вокселей (232 × 126 × 364). Объём работы растёт обратно пропорционально
+произведению трёх шагов вокселя: если уменьшить все три вдвое, работы станет в восемь
+раз больше.
+
+### Фон кадра (BG_GATE_ENABLE)
+
+Фон — медиана объёма по рабочим вокселям (ненулевым, на опорных плоскостях). Отношение
+максимума кадра к фону показывает, насколько самый сильный отклик выделяется над
+типичным уровнем помех. Пороги 6 и 8,5 — постоянные ноутбука.
+
+Если объектов CLEAN нет, **BG_GATE_ENABLE** управляет яркостью всего кадра: при
+отношении меньше 6 кадр не показывается, при 6 его максимум появляется на уровне
+**SAR_CLOUD_THRESHOLD**, с 8,5 кадр показывается в полную яркость, а между 6 и 8,5
+яркость растёт линейно.
+
+Если CLEAN нашёл объекты, они видны всегда, каждый в своей шкале, при любом отношении
+кадра к фону. **BG_GATE_ENABLE** тогда прячет только остаток после вычитания, если его
+максимум меньше 6 фонов.
+
+### CLEAN (SAR_CLEAN_ENABLE)
+
+CLEAN разделяет сцену на объекты. На каждом шаге он строит изображение остатка на
+отдельной сетке поиска (4 × 10 × 4 см по X, Y и Z, на всю область сцены), находит
+точку, которая сильнее всего превышает порог, и вычитает её отклик из А-сканов всех
+пар. Порог для вокселя — меньшее из двух: 5,5 медианы положительных вокселей
+изображения и 4,5 медианы на той же дальности (по кольцам дальности шириной 0,25 м).
+Вычитание идёт, пока ни один воксель не превышает порог, но не больше 15 шагов.
+Шаги, точки которых лежат не дальше 0,35 м по X, 0,50 м по Y и 0,40 м по Z от первой
+точки группы, объединяются в один объект. Затем каждый объект строится отдельно и
+рисуется в своей шкале от 0 до 1 поверх остатка: слабый объект виден рядом с
+сильным. Уровень объекта — отношение его пика к фону кадра.
+
+CLEAN работает только на апертуре из одного кадра: всегда при
+**SAR_FRAME_RADIUS** = 0, а при большем значении — пока пригодных предыдущих
+коллекций нет (сразу после **Start**, после очистки истории). Иначе статус сообщает,
+что CLEAN пропущен.
+
+Сетка поиска CLEAN охватывает всю область сцены, даже если **SAR_X_SIZE_M** и
+**SAR_Z_SIZE_M** сужают сетку кадра: отражатель сразу за краем кадра вычитается и не
+оставляет внутри кадра боковой лепесток, похожий на объект.
+
+### Рамки (SAR_MARK_ENABLE)
+
+С **SAR_MARK_ENABLE** объекты CLEAN, которые не дальше 0,8 м друг от друга поперёк и
+0,5 м вдоль земли (в том числе цепочкой), объединяются в группу, и вокруг группы рисуется
+рамка. Центр группы — средняя высота её объектов, взвешенная по уровню (учитываются
+объекты не слабее 0,4 сильнейшего), верх — верхняя граница их откликов. Классы
+проверяются по порядку строк таблицы, рамка получает первый подходящий:
+
+| Цвет | Класс | Условие |
+| --- | --- | --- |
+| серый пунктир | at the boundary — у края сцены | сильнейший объект группы у края: по оси обзора не дальше 0,25 м от **MAX_DEPTH** или 0,10 м от **MIN_DEPTH**, поперёк не дальше 0,2 м от края сетки или по высоте не дальше 0,4 м от её верха. Отклик может частично лежать за сценой, класс пока не определить |
+| красный | very low — очень низко (как мина) | центр не выше 0,15 м и верх не выше 0,45 м |
+| оранжевый | on the ground — на земле | центр не выше 0,35 м |
+| синий | above the ground — над землёй | остальные |
+
+Легенда рамок — строкой под видами; она видна, когда включены и
+**SAR_MARK_ENABLE**, и **SAR_CLEAN_ENABLE**. Без рамок объекты пронумерованы и
+подписаны уровнем в фонах: `1: 12 bg`.
+
+### Виды
+
+Четыре вида: **Front (X-Y)**, **Side (Z-Y)**, **Top (X-Z)** — проекции максимума
+объёма спереди, сбоку и сверху — и **3D Projection**, наклонный вид. На видах с осью
+высоты пунктиром показана земля (Y = 0), на трёх плоских видах — положения выбранных
+антенн. Пустой квадрат отмечает максимум; его сторона — наибольшая из ширин отклика
+на половине максимума вдоль осей вида (не меньше одного вокселя). Это размер
+отклика, а не размер предмета. С объектами CLEAN и при пустом кадре квадрата нет.
+
+**SAR_CLOUD_THRESHOLD** скрывает пиксели слабее заданной доли максимума, не меняя
+шкалу. **Zoom (%)** от 100 до 1000 уменьшает окно всех четырёх видов и плавно сдвигает
+его центр к самому яркому отклику; при 100% видна вся сцена.
+
+Строка над видами показывает состояние:
+
+| Текст | Когда |
+| --- | --- |
+| `SAR3D: waiting for measurements` | результатов ещё не было |
+| `SAR3D: waiting for projection data` | результат без изображений |
+| `SAR3D: ready — CUDA …` | изображение посчитано; разбор строки — ниже |
+| `SAR3D: no signal — No signal inside the selected depth range` | в пределах **MIN_DEPTH**–**MAX_DEPTH** нет сигнала |
+| `SAR3D: error — …` | ошибка настроек, данных или расчёта; текст ошибки |
+| `SAR3D: warning — …` | нет подходящей видеокарты или программа собрана без CUDA |
+
+Строка `ready` складывается из частей через `|`, например:
+
+```text
+SAR3D: ready — CUDA | peak 7.2 backgrounds (appears from 6, full scale from 8.5): scale ×0.83 | max X +0.12, Y +0.30, Z 4.85 m | level 0.0412 | zoom 100%
+```
+
+| Часть | Что значит |
+| --- | --- |
+| `CUDA`, `CUDA; CLEAN: …` | расчёт на видеокарте и итог CLEAN: `CLEAN: K objects, each in its own scale (S subtractions, residual maximum R backgrounds)`, `CLEAN: no objects (…)` или `CLEAN skipped: it needs a one-frame aperture, this one has N frames` |
+| `peak N backgrounds` | отношение максимума кадра к фону; без объектов CLEAN дальше — состояние порога: `below the appearance level, frame empty`, `scale ×K` (кадр показан с множителем яркости K) или `full scale` |
+| `boxes: …` | число рамок каждого класса, например `boxes: 1 very low, 0 on the ground, 2 above the ground` (`at the boundary` — только если такие есть) |
+| `max X …, Y …, Z … m` | положение максимума в осях сцены; у X и Y указан знак |
+| `level …` | уровень, на который нормированы виды: максимум объёма до нормировки |
+| `zoom N%` | масштаб из **Zoom (%)** |
+
+### Настройки 3D SAR
+
+| Параметр | По умолчанию | Пределы | Что делает |
+| --- | --- | --- | --- |
+| **INPUT_IDX**, **OUTPUT_IDX** | номера с геометрией, которые есть в парах сбора (если таких нет — все с геометрией) | номера через запятую | приёмные и передающие антенны в обработке; пустое поле — все с геометрией |
+| **F_START MHz**, **F_STOP MHz** | 1500 и 6000 | в пределах развёртки | полоса частот А-сканов |
+| **MIN_DEPTH**, **MAX_DEPTH** | 2,0 и 8,0 | 0–50 и 0,1–50 м | границы расстояния по оси обзора: задают длину сцены вдоль земли и обнуляют воксели вне себя |
+| **SAR_VOXEL_M X**, **SAR_VOXEL_M Y**, **SAR_VOXEL_M Z** | 0,025, 0,02, 0,02 | 0,01–0,1 м | шаги сетки. Сглаживание задано в вокселях, поэтому от шагов зависит и оно, а с ним фон кадра и изображения объектов CLEAN; сетка поиска CLEAN от них не зависит |
+| **LOOK_ANGLE_DEG** | 19,5 | от −90 до 90° | наклон радара вниз: оси сцены, поправка на движение |
+| **Ignore socket speed** | выключен | — | как в GPR |
+| **SPEED_M_S** | 0,0 | от −100 до 100 м/с | скорость радара вдоль земли для поправки на движение и сдвига апертуры |
+| **SAR_FRAME_RADIUS** | 0 | 0–24 | сколько предыдущих коллекций добавлять в апертуру. 0 — только текущая (нужно разнесение антенн по высоте); больше нуля — нужна точная скорость |
+| **BP_GROUND_DEPTH_M** | 1,25 | 0–10 м | высота начала осей радара (строки Y = 0 таблиц антенн) над землёй |
+| **COMP_RANGE_POWER** | 0,3 | 0–2 | степень компенсации ослабления с расстоянием |
+| **SAR_USE_COMPENSATION** | включён | — | включает компенсацию дальности |
+| **SAR_NORMALIZE_EACH_FRAME** | включён | — | нормирует каждую пару на медиану её А-скана в пределах **MIN_DEPTH**–**MAX_DEPTH** |
+| **PAIR_DEPTH_EQUALIZE** | включён | — | выравнивание уровней пар по дальности |
+| **Subtract mean of previous collections**, **Mean count** | включён, 10 | 0–10000 | вычитание среднего предыдущих коллекций |
+| **BG_GATE_ENABLE** | включён | — | фон кадра (см. выше) |
+| **SAR_CLEAN_ENABLE** | включён | — | CLEAN (см. выше) |
+| **SAR_X_SIZE_M (0 = auto)** | 0 | 0–100 м | ширина сетки кадра поперёк; 0 — от антенн с запасом 2 м |
+| **SAR_Y_RANGE_M min**, **SAR_Y_RANGE_M max** | −0,5 и 2,0 | от −50 до 50 м | границы высоты; max должно быть больше min |
+| **SAR_Z_SIZE_M (0 = auto)** | 0 | 0–100 м | длина сетки кадра вдоль земли; 0 — по MIN_DEPTH–MAX_DEPTH |
+| **SAR_CLOUD_THRESHOLD** | 0,65 | 0–1 | только вид: скрыть пиксели слабее этой доли |
+| **Zoom (%)** | 100 | 100–1000 | только вид: приближение к самому яркому отклику |
+| **SAR_MARK_ENABLE** | включён | — | только вид: рамки вместо номеров |
+
+Время расчёта на GTX 1060 при сцене по умолчанию: около 0,1–0,2 с на кадр, фон кадра
+добавляет около 0,1 с, CLEAN — ещё 0,4–0,5 с в зависимости от числа шагов.
+
+Результат 3D SAR должен поместиться в слот кольца `results`. Если не помещается,
+статус сообщает, сколько нужно места, и советует увеличить шаги вокселя, сузить
+дальность или увеличить `rings.results.slot_size_bytes`.
+
+### Видеокарта
+
+3D SAR нужна видеокарта NVIDIA с драйвером. Ядра расчёта компилируются при запуске
+библиотекой NVRTC под установленную карту. Если при сборке не нашлись заголовки и
+библиотеки CUDA, программа собирается без 3D SAR, и в этом режиме над видами висит
+предупреждение
+`SAR3D requires an NVIDIA GPU with CUDA; this program was built without nvrtc.h, cuda.h, libnvrtc or libcuda. Install CUDA and rebuild.`
+Для карты старее, чем умеет установленная NVRTC, предупреждение советует собрать
+программу с NVRTC 12 (как это сделать — в главе [Разработка](development.md)).
+Остальные режимы видеокарты не требуют.
+
+## Общие шаги GPR и 3D SAR
+
+### Вычитание среднего предыдущих коллекций
+
+Из S21 каждой пары вычитается
+комплексное среднее этой пары за до **Mean count** предыдущих коллекций. Остаётся то,
+что изменилось: неподвижные отражения и прямая связь антенн гасятся, движущиеся
+относительно радара предметы остаются. Процессор хранит столько коллекций, сколько
+нужно для среднего и апертуры, независимо от ёмкости колец.
+
+### Поправка на движение
+
+Время каждой частотной точки программа берёт из окна съёма
+развёртки: точки идут равномерно от начала окна до конца, а в режиме переключения
+стимула стадии одной частоты идут по очереди в порядке номеров выходов. Фаза каждой
+точки поворачивается на 4π·f·v·cos(p)·t / c (v — скорость, p — угол обзора, t —
+время точки относительно середины коллекции; в GPR ещё со знаком
+**Direction sign**), и вся коллекция приводится к одному моменту. При нулевой
+скорости поправки нет. В GPR с **Motion mode** = `int_focus` из поправки убирается
+её постоянная и линейная по частоте часть — чистый сдвиг по дальности. Скорость берётся из
+клиента локатора,
+если он присылал её в последние 5 с и флажок **Ignore socket speed** выключен,
+иначе — из поля скорости.
+
+### Выравнивание пар по дальности (PAIR_DEPTH_EQUALIZE)
+
+Для каждой пары считается
+плавный уровень А-скана по дальности: медиана в окне 1,5 м по блокам 0,10 м. Каждая
+пара умножается на положительный коэффициент, зависящий от дальности, так что её
+уровень становится средним геометрическим уровней всех пар. Различия между парами
+уходят, общий спад с дальностью и фаза сохраняются. Нужно хотя бы две пары.
+
+### Нормировка на медиану
+
+Каждая пара делится на медиану модуля своего А-скана в
+пределах границ дальности. В GPR выполняется всегда, в 3D SAR — с
+**SAR_NORMALIZE_EACH_FRAME**.
+
+### Компенсация дальности
+
+Отражение слабеет с расстоянием примерно как 1/(R_tx·R_rx). Вклад пары в точку
+умножается на ((R_tx·R_rx) / (R_tx,оп·R_rx,оп))^p, где R_tx,оп и R_rx,оп — расстояния от
+антенн пары до опорной точки на земле под серединой пары, на дальности 5 м; вес
+ограничен пятью.
+
+## Геометрия
+
+Антенны задаются в осях радара (X, Y, Z), изображения 3D SAR — в осях сцены (X, Y —
+высота над землёй, Z — вдоль земли); см. рисунок в главе
+[Как работает радар](principles.md). Ось X у обеих систем общая. Переход из осей
+сцены в оси радара при высоте h и угле обзора p:
+
+Y_радар = (Y − h)·cos p + Z·sin p,
+Z_радар = −(Y − h)·sin p + Z·cos p.
+
+Плоскость земли (Y = 0) в осях радара: Y_радар = (−h + Z_радар·sin p) / cos p. На ней
+лежит сетка GPR; при p = ±90° плоскость не определена, и программа отказывает
+(`Ground BP is undefined at a look angle of 90 degrees`).
+
+«Глубина» в разных режимах означает разное:
+
+| Где | Что означает |
+| --- | --- |
+| B-scan, **Cut (m)** и **Max depth (m)** | половина пути волны, отсчитанная от **Cut (m)** |
+| GPR, **Min depth (m)** и **Max depth (m)** | координата Z_радар точки на плоскости земли |
+| 3D SAR, **MIN_DEPTH** и **MAX_DEPTH** | координата Z_радар вокселя |
+| Нормировка А-скана | половина пути волны |
+
+Волна в GPR и 3D SAR считается идущей со скоростью 3·10⁸ м/с (воздух), в B-scan —
+299 792 458 м/с.