# Режимы обработки

Процессор (`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 м/с.