deploy examples

# Conflicts:
#	device_firmware/cart_firmware/docs/protocol.md

.gitignore

@@ -3,6 +3,8 @@ __pycache__/
 *.py[codz]
 *$py.class
 build*
+# build* иначе прячет скрипт сборки вендоренного gpr_cpp (его build/ остаётся игнорируемым)
+!data_acq_and_processing/gpr_cpp/build_cmake.sh
 .codex
 .DS_Store
 # C extensions
@@ -86,7 +88,7 @@ target/
 
 # Jupyter Notebook
 .ipynb_checkpoints
-
+202609144
 # IPython
 profile_default/
 ipython_config.py

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "cmake.sourceDirectory": "/home/awe/Documents/radar_system/data_acq_and_processing/gpr_cpp"
+}

Makefile

@@ -8,7 +8,43 @@ VISA_LDFLAGS := $(LDFLAGS) -lvisa
 BUILD_DIR := build
 BIN_DIR := $(BUILD_DIR)/bin
 
+# --- gpr_cpp: vendored C++/CUDA 3D SAR library (originally from VNA_AlGo).
+# Built automatically by the $(GPR_CPP_LIB) rule below via its own CMake
+# (build_cmake.sh). CUDA headers and libnvrtc come from the pip nvidia-*
+# packages inside this repo's venv (same detection as build_cmake.sh); when
+# those are absent (e.g. Jetson, where CUDA comes with JetPack) the system
+# toolkit at /usr/local/cuda is used. libcuda is always the system driver.
+GPR_CPP_DIR ?= data_acq_and_processing/gpr_cpp
+GPR_CPP_LIB ?= $(GPR_CPP_DIR)/build/libgpr_core_cpp.a
+# Absolute so the derived -rpath (libnvrtc dir) survives running the binary
+# from outside the repo root.
+GPR_VENV ?= $(CURDIR)/.venv
+GPR_CUDA_INC_DIR ?= $(dir $(firstword $(wildcard $(GPR_VENV)/lib/python*/site-packages/nvidia/*/include/nvrtc.h)))
+# cuda.h can live in a DIFFERENT pip package than nvrtc.h (Jetson: cuda_runtime
+# vs cuda_nvrtc); the unified cu13 package on dev machines has both in one dir.
+GPR_CUDA_RT_INC_DIR ?= $(dir $(firstword $(wildcard $(GPR_VENV)/lib/python*/site-packages/nvidia/*/include/cuda.h)))
+GPR_NVRTC_LIB ?= $(firstword $(wildcard $(GPR_VENV)/lib/python*/site-packages/nvidia/*/lib/libnvrtc.so*))
+# System-CUDA fallback. An empty GPR_CUDA_INC_DIR would also corrupt the compile
+# command: a bare `-I` swallows the next argument.
+ifeq ($(strip $(GPR_CUDA_INC_DIR)),)
+GPR_CUDA_INC_DIR := /usr/local/cuda/include
+endif
+ifeq ($(strip $(GPR_CUDA_RT_INC_DIR)),)
+GPR_CUDA_RT_INC_DIR := /usr/local/cuda/include
+endif
+ifeq ($(strip $(GPR_NVRTC_LIB)),)
+GPR_NVRTC_LIB := $(firstword $(wildcard /usr/local/cuda/lib64/libnvrtc.so*))
+endif
+# Deduplicated CUDA include flags (a single dir on dev machines).
+GPR_CUDA_INC_FLAGS := $(addprefix -I,$(sort $(GPR_CUDA_INC_DIR) $(GPR_CUDA_RT_INC_DIR)))
+GPR_CUDA_LIB_DIR := $(dir $(GPR_NVRTC_LIB))
+# libnvrtc from pip ships only as libnvrtc.so.N (no .so symlink), so link the
+# full path; the rpath makes the binary find it without LD_LIBRARY_PATH.
+DATA_PROCESSOR_LDFLAGS := $(LDFLAGS) $(GPR_CPP_LIB) $(GPR_NVRTC_LIB) -lcuda -Wl,-rpath,$(GPR_CUDA_LIB_DIR)
+
 INCLUDES := \
+	-I$(GPR_CPP_DIR)/include \
+	$(GPR_CUDA_INC_FLAGS) \
 	-Idata_acq_and_processing/common_cpp/ipc/include \
 	-Idata_acq_and_processing/common_cpp/config/include \
 	-Idata_acq_and_processing/third_party \
@@ -55,6 +91,7 @@ PROCESSOR_SOURCES := \
 	data_acq_and_processing/processing/processors/src/bscan_processor.cpp \
 	data_acq_and_processing/processing/processors/src/gpr_processor.cpp \
 	data_acq_and_processing/processing/processors/src/passthrough_processor.cpp \
+	data_acq_and_processing/processing/processors/src/sar3d_processor.cpp \
 	data_acq_and_processing/processing/data_processor/src/processing_live_config.cpp \
 	data_acq_and_processing/processing/data_processor/src/data_processor.cpp \
 	data_acq_and_processing/processing/data_processor/src/main.cpp \
@@ -102,12 +139,27 @@ TARGETS := \
 	$(BIN_DIR)/data_preprocessor \
 	$(BIN_DIR)/data_processor
 
-.PHONY: all clean kamil_adc_collector
+.PHONY: all clean kamil_adc_collector sar3d_parity
 
 all: $(TARGETS)
 
 kamil_adc_collector: $(BIN_DIR)/kamil_adc_collector
 
+# On-demand parity check of the sar3d processor against the reference notebook
+# volumes (scripts/sar3d_volume_compare.py diffs the dumped volume against a
+# *_volume.npz export). Not part of `all`.
+SAR3D_PARITY_OBJS := $(addprefix $(BUILD_DIR)/, \
+	data_acq_and_processing/processing/tools/sar3d_parity_main.o \
+	data_acq_and_processing/processing/processors/src/sar3d_processor.o \
+	data_acq_and_processing/common_cpp/config/src/run_config.o \
+	data_acq_and_processing/common_cpp/ipc/src/shared_types.o)
+
+sar3d_parity: $(BIN_DIR)/sar3d_parity
+
+$(BIN_DIR)/sar3d_parity: $(SAR3D_PARITY_OBJS) $(GPR_CPP_LIB)
+	@mkdir -p $(BIN_DIR)
+	$(CXX) $(SAR3D_PARITY_OBJS) -o $@ $(DATA_PROCESSOR_LDFLAGS)
+
 $(BIN_DIR)/sweep_orchestrator: $(SWEEP_ORCH_OBJS)
 	@mkdir -p $(BIN_DIR)
 	$(CXX) $(SWEEP_ORCH_OBJS) -o $@ $(ORCH_LDFLAGS)
@@ -116,9 +168,17 @@ $(BIN_DIR)/data_preprocessor: $(PREPROCESSOR_OBJS)
 	@mkdir -p $(BIN_DIR)
 	$(CXX) $(PREPROCESSOR_OBJS) -o $@ $(LDFLAGS)
 
-$(BIN_DIR)/data_processor: $(DATA_PROCESSOR_OBJS)
+$(BIN_DIR)/data_processor: $(DATA_PROCESSOR_OBJS) $(GPR_CPP_LIB)
 	@mkdir -p $(BIN_DIR)
-	$(CXX) $(DATA_PROCESSOR_OBJS) -o $@ $(LDFLAGS)
+	$(CXX) $(DATA_PROCESSOR_OBJS) -o $@ $(DATA_PROCESSOR_LDFLAGS)
+
+# Vendored gpr_cpp static lib: delegate to its CMake build (also produces the
+# standalone_bp example used by sar3d_parity cross-checks).
+GPR_CPP_SRC_FILES := $(wildcard $(GPR_CPP_DIR)/src/*) $(wildcard $(GPR_CPP_DIR)/include/gpr/*) \
+	$(wildcard $(GPR_CPP_DIR)/examples/*) $(GPR_CPP_DIR)/CMakeLists.txt $(GPR_CPP_DIR)/build_cmake.sh
+
+$(GPR_CPP_LIB): $(GPR_CPP_SRC_FILES)
+	GPR_BUILD_PYTHON=OFF VENV=$(abspath $(GPR_VENV)) bash $(GPR_CPP_DIR)/build_cmake.sh
 
 # The collector compiles into its own build/kamil/ tree with collector-only
 # includes (no VISA), so the shared driver/config sources it reuses never collide
@@ -141,4 +201,4 @@ $(BUILD_DIR)/%.o: %.cpp
 -include $(DEPFILES)
 
 clean:
-	rm -rf $(BUILD_DIR)
+	rm -rf $(BUILD_DIR) $(GPR_CPP_DIR)/build

README.md

@@ -60,7 +60,7 @@ controls plus a pixel-identical live plot through an embedded web UI.
 
 | Path | Contents |
 | --- | --- |
-| `data_acq_and_processing/` | C++ pipeline: `sweep_orchestrator/`, `preprocessing/`, `processing/` (including `locator/`), shared `common_cpp/` (config, IPC rings), and vendored `third_party/` (Eigen, nlohmann/json). |
+| `data_acq_and_processing/` | C++ pipeline: `sweep_orchestrator/`, `preprocessing/`, `processing/` (including `locator/`), shared `common_cpp/` (config, IPC rings), the vendored `gpr_cpp/` C++/CUDA 3D SAR library, and vendored `third_party/` (Eigen, nlohmann/json). |
 | `python_app/` | Python application: `gui/`, `orchestration/` (process supervisor, shared-memory readers, config), `hardware_full/` (device drivers and services), `webui/`, `storage/`, `models/`, `workflows/`, `scripts/` (producers and tools), and `tests/`. |
 | `run_config_examples/` | Ready-made configuration profiles, one per hardware setup. |
 | `deploy/` | systemd daemon installer for Raspberry Pi appliances. |
@@ -74,6 +74,13 @@ controls plus a pixel-identical live plot through an embedded web UI.
   specific (GPIO12/13/18/19, `dtoverlay=pwm-2chan`).
 - A C++20 compiler and `make` — Eigen and nlohmann/json are vendored, so no extra C++ dependencies are needed.
 - **Python 3.10 or newer**, in a virtual environment.
+- For the `sar3d` processor (3D SAR): an NVIDIA GPU with the driver installed
+  (`libcuda`) and `cmake` (the vendored `gpr_cpp` library at
+  `data_acq_and_processing/gpr_cpp/` builds via its own CMake, invoked
+  automatically by `make`). CUDA headers/libnvrtc are taken from the pip
+  `nvidia-*` packages in this repo's venv (installed by `requirements.txt` on
+  x86_64), otherwise from the system toolkit at `/usr/local/cuda`
+  (Jetson/JetPack, apt `cuda-toolkit`).
 
 ## Build and run
 
@@ -86,6 +93,21 @@ python3 -m venv .venv
 make                     # build the C++ binaries into build/bin/
 ```
 
+`make` also builds the vendored 3D SAR library
+(`data_acq_and_processing/gpr_cpp/`, CMake + NVRTC — needs `cmake`; CUDA
+headers come from the pip `nvidia-*` packages in `.venv`, or `/usr/local/cuda`
+as a fallback).
+
+To verify the sar3d processor against the gpr_cpp reference on the recorded
+dataset, build and run the on-demand parity tool:
+
+```bash
+make sar3d_parity
+./build/bin/sar3d_parity <preprocessed_dataset_dir> <center_snapshot_name>
+# compare the printed peak/argmax with
+# ./data_acq_and_processing/gpr_cpp/build/standalone_bp on the same arguments
+```
+
 Run the desktop GUI:
 
 ```bash
@@ -99,6 +121,69 @@ Run the desktop GUI:
 `./start.sh --help`. The acquisition device (LibreVNA, Kamil ADC, …) is detected
 automatically from the active config's `radar.model` — there is no per-device flag.
 
+## Jetson (aarch64) bring-up
+
+Ubuntu 22.04 on Jetson has glibc 2.35, and PyQt6 6.8+ ships only
+`manylinux_2_39` aarch64 wheels — `requirements.txt` therefore pins PyQt6 to
+`<6.8` on aarch64 (6.7.1 is the last release with a compatible wheel). With
+that pin the stock `./start.sh` provisioning works; the extra steps are only
+for the CUDA-backed `sar3d` processor:
+
+```bash
+# 1. copy the replay dataset (for dataset-replay profiles) and point
+#    radar.replay.dataset_dir in the profile at the local copy — the path in
+#    run_config_examples/*.json is machine-specific.
+
+# 2. normal launch; the vendored gpr_cpp builds against the JetPack system CUDA
+#    (requirements.txt installs no pip nvidia-* packages on aarch64, and
+#    build_cmake.sh falls back to /usr/local/cuda automatically; override with
+#    CUDA_INC=... CUDA_LIB=... if the toolkit lives elsewhere):
+./start.sh --profile run_config_examples/run_config_replay_vna.example.json
+```
+
+If linking fails with `cannot find -lcuda`, the driver stub lives at
+`/usr/local/cuda/lib64/stubs/libcuda.so`; on JetPack the real driver is
+`/usr/lib/aarch64-linux-gnu/nvidia/libcuda.so.1` (present after boot).
+
+## Running without hardware (emulation)
+
+Two ways to run the full pipeline with no radar attached:
+
+**Mock producer (synthetic data).** The default `run_config.json` already sets
+`radar.driver_mode: "mock"`, so the producer generates synthetic S-parameters.
+The preprocessor still requires S21 calibration/reference sets; create them once:
+
+```bash
+.venv/bin/python -m python_app.scripts.manual_smoke_run --duration 1.0  # creates smoke_cal/smoke_ref
+./start.sh   # then in the GUI: Preprocessing Panel -> pick the sets -> Start
+```
+
+(Alternatively use the GUI's "Create neutral sets" button, which makes
+identity calibration + zero reference so preprocessing is a pass-through.)
+
+**Dataset replay (recorded scene, meaningful sar3d picture).** When
+`radar.replay.dataset_dir` is set in the profile, the supervisor launches
+`python_app.scripts.replay_raw_producer` instead of the normal producer: it
+replays recorded snapshots into the raw ring at the recorded cadence, looping
+forever with a monotonic timeline. Pair it with NEUTRAL preprocess sets so the
+already-preprocessed recording passes through the preprocessor bit-exactly.
+A ready profile for the VNA_AlGo tank005 dataset is provided:
+
+```bash
+# one-time: neutral sets for this profile (or use the GUI button)
+.venv/bin/python -m python_app.scripts.create_neutral_preprocess_sets \
+    --config run_config_examples/run_config_replay_vna.example.json
+# interactive GUI (mode sar3d is pre-selected by the profile's gui section):
+./start.sh --profile run_config_examples/run_config_replay_vna.example.json
+# or a fully headless end-to-end check:
+.venv/bin/python -m python_app.scripts.replay_smoke_run --duration 30
+```
+
+Note: the sar3d processor allocates GPU memory; if the desktop (e.g. a browser)
+has filled the GPU, sar3d logs `out of memory` and publishes empty results until
+memory frees. Reduce `sar3d_grid_nx/ny/nz` in the processing panel to shrink
+the footprint.
+
 The web interface is served in-process at `http://<host>:8080`. It mirrors the live
 plot and offers Start / Stop / Capture controls and the active processor settings.
 

data_acq_and_processing/gpr_cpp/CMakeLists.txt

@@ -0,0 +1,78 @@
+# 3.22 = apt cmake на Ubuntu 22.04 (Jetson/JetPack); фич новее здесь нет.
+cmake_minimum_required(VERSION 3.22)
+project(gpr_cpp LANGUAGES CXX)   # CXX-only: CUDA компилируется в рантайме через NVRTC
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+set(CMAKE_CXX_FLAGS_RELEASE "-O3")
+
+# bindings/pymodule.cpp не вендорен в radar_system — включение потребует вернуть его из VNA_AlGo
+option(GPR_BUILD_PYTHON "Build pybind11 module" OFF)
+option(GPR_BUILD_TESTS  "Build C++ parity tests" OFF)
+option(GPR_BUILD_EXAMPLES "Build standalone C++ example" ON)
+
+# Python окружение (venv) — источник pybind11 и pip CUDA-библиотек (nvrtc, cudart).
+if(NOT DEFINED PYTHON_EXECUTABLE)
+  set(PYTHON_EXECUTABLE python3)
+endif()
+
+# CUDA include/lib из pip-пакетов nvidia-*; задаются -DGPR_CUDA_INC / -DGPR_CUDA_LIB
+# (детект делает build_cmake.sh). Заголовки: nvrtc.h, cuda.h (Driver API).
+# GPR_CUDA_INC может быть СПИСКОМ каталогов (через ';'): в раздельных pip-пакетах
+# (Jetson: cuda_nvrtc + cuda_runtime) nvrtc.h и cuda.h лежат в разных include/.
+if(NOT DEFINED GPR_CUDA_INC OR NOT DEFINED GPR_CUDA_LIB)
+  message(FATAL_ERROR "Задайте -DGPR_CUDA_INC=<dir(ы) с nvrtc.h,cuda.h; ';'-список> и -DGPR_CUDA_LIB=<dir с libnvrtc.so*>")
+endif()
+
+# libcuda (драйвер) — системный
+find_library(CUDA_DRIVER_LIB cuda PATHS /usr/lib/x86_64-linux-gnu /usr/lib/aarch64-linux-gnu
+             /usr/lib REQUIRED)
+# libnvrtc из pip
+find_library(NVRTC_LIB NAMES nvrtc libnvrtc.so.13 libnvrtc.so.12 nvrtc.so
+             PATHS ${GPR_CUDA_LIB} REQUIRED NO_DEFAULT_PATH)
+
+# PocketFFT (header-only, vendored)
+add_library(pocketfft INTERFACE)
+target_include_directories(pocketfft INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/third_party/pocketfft)
+
+# --- ядро библиотеки (usable без Python) ---
+add_library(gpr_core_cpp STATIC
+  src/geometry.cpp
+  src/ascan.cpp
+  src/device.cpp
+  src/nvrtc_kernel.cpp
+  src/sar3d.cpp)
+target_include_directories(gpr_core_cpp PUBLIC
+  ${CMAKE_CURRENT_SOURCE_DIR}/include
+  ${GPR_CUDA_INC})
+target_link_libraries(gpr_core_cpp PUBLIC pocketfft ${NVRTC_LIB} ${CUDA_DRIVER_LIB})
+# rpath на каталог pip libnvrtc — чтобы бинарник/модуль грузились без LD_LIBRARY_PATH
+set_target_properties(gpr_core_cpp PROPERTIES POSITION_INDEPENDENT_CODE ON
+  BUILD_RPATH "${GPR_CUDA_LIB}" INSTALL_RPATH "${GPR_CUDA_LIB}")
+
+if(GPR_BUILD_PYTHON)
+  execute_process(COMMAND ${PYTHON_EXECUTABLE} -m pybind11 --cmakedir
+                  OUTPUT_VARIABLE PB11_DIR OUTPUT_STRIP_TRAILING_WHITESPACE RESULT_VARIABLE PB11_RC)
+  if(PB11_RC EQUAL 0)
+    find_package(pybind11 CONFIG REQUIRED HINTS ${PB11_DIR})
+  else()
+    find_package(pybind11 CONFIG REQUIRED)
+  endif()
+  pybind11_add_module(_gpr_cpp bindings/pymodule.cpp)
+  target_link_libraries(_gpr_cpp PRIVATE gpr_core_cpp)
+  set_target_properties(_gpr_cpp PROPERTIES BUILD_RPATH "${GPR_CUDA_LIB}" INSTALL_RPATH "${GPR_CUDA_LIB}")
+endif()
+
+if(GPR_BUILD_TESTS)
+  add_executable(gpr_test_parity tests/cpp/test_parity.cpp)
+  target_link_libraries(gpr_test_parity PRIVATE gpr_core_cpp)
+endif()
+
+if(GPR_BUILD_EXAMPLES)
+  add_executable(standalone_bp examples/standalone_bp.cpp)
+  target_link_libraries(standalone_bp PRIVATE gpr_core_cpp)
+  set_target_properties(standalone_bp PROPERTIES BUILD_RPATH "${GPR_CUDA_LIB}" INSTALL_RPATH "${GPR_CUDA_LIB}")
+endif()

data_acq_and_processing/gpr_cpp/README.md

@@ -0,0 +1,85 @@
+# gpr_cpp — C++/CUDA счёт-ядро MIMO GPR 3D SAR
+
+> Инфраструктура (сборка, NVRTC, PocketFFT, npy) вендорена из репозитория
+> VNA_AlGo (`gpr_cpp/`, коммит `544dc59`) без python-биндингов
+> (`GPR_BUILD_PYTHON=OFF`). АЛГОРИТМ с сентября 2026 переписан: это порт
+> эталонного ноутбука `Multi_antenna_3D_clean_v1.ipynb` (ячейки 0 и 4), а не
+> старого `gpr_core`/Horns_3D. Паритет с ноутбуком проверяется инструментом
+> `sar3d_parity` + `python_app/scripts/sar3d_volume_compare.py` по
+> референсным `*_volume.npz`. Собирается из корневого Makefile radar_system
+> (цель `$(GPR_CPP_LIB)` вызывает `build_cmake.sh`).
+
+## Что внутри
+
+**В C++ (`libgpr_core_cpp`):** сегментированный тайминг кадра по per-trace
+меткам захвата (`compute_pair_timestamps`), препроцессинг A-сканов (bg-subtract,
+полная фазовая коррекция движения intra+pair до IFFT, k0-вставка + Ханн + IFFT
+через PocketFFT, нормировка пар), полнообластная ground-сетка
+(`build_full_region_grid`), 3D SAR апертурный объём (одно CUDA-ядро на всю
+апертуру; геометрия в double, A-сканы float32) и финализация
+(`finish_volume`: |acc/cnt| → маска глубины → нормировка без Y-краёв → гаусс
+по (Z,X) → нормировка; возвращает объём [0,1] + level).
+
+## Ключевое решение: CUDA без nvcc (NVRTC + Driver API)
+
+На целевых машинах (x86+T600, Jetson) нет полного CUDA toolkit — только runtime +
+**NVRTC** (как у cupy). Поэтому ядро **не компилируется nvcc'ом**: его исходник
+встроен строкой ([src/kernel_src.hpp](src/kernel_src.hpp)), компилируется в рантайме
+через NVRTC в **cubin под точную арх устройства** (запрос compute capability →
+`sm_XY`, без JIT PTX), грузится и запускается через **CUDA Driver API**. Хост-часть
+собирается обычным g++. Плюс: без toolkit и без привязки к SM — один код для
+x86 (sm_75) и Jetson (sm_87).
+
+## Сборка
+
+```bash
+bash build_cmake.sh            # авто-детект pip CUDA-путей; собирает всё
+# артефакты в build/: libgpr_core_cpp.a, _gpr_cpp*.so, standalone_bp
+```
+Требуется: g++ ≥13, cmake ≥3.24, pybind11 (`pip install pybind11`), pip-пакеты
+`nvidia-*` (nvrtc+cudart, идут с cupy), системный `libcuda`. rpath на каталог
+libnvrtc прописан — бинарники/модуль грузятся без `LD_LIBRARY_PATH`.
+
+## Публичный C++ API ([include/gpr/](include/gpr/))
+
+```cpp
+#include "gpr/config.hpp"    // GeometryConfig/BPConfig/MotionConfig/SARConfig (дефолты = ноутбук)
+#include "gpr/ascan.hpp"     // compute_pair_timestamps, preprocess_snapshot(...) -> AScanSet
+#include "gpr/sar3d.hpp"     // SarEngine::aperture_volume -> VolumeRaw; finish_volume -> FinishedVolume
+#include "gpr/geometry.hpp"  // frame_offsets, frame_weights, build_full_region_grid
+
+gpr::SarEngine engine(geom, bp, mot, sar);          // компилит ядро под устройство
+auto raw = engine.aperture_volume(frames, grid);    // один запуск ядра на апертуру
+auto fin = gpr::finish_volume(raw, grid, mot.pitch_deg, bp, sar);  // объём [0,1] + level
+```
+Пример без Python: [examples/standalone_bp.cpp](examples/standalone_bp.cpp) — грузит
+S21 из `.npy`, строит объём, печатает максимум.
+```bash
+./build/standalone_bp <preprocessed_dir> 0038_id39_ns11361438137486
+```
+
+## Python-модуль
+
+```python
+import _gpr_cpp                     # из gpr_cpp/build
+eng = _gpr_cpp.SarEngine(_gpr_cpp.GeometryConfig(), _gpr_cpp.BPConfig(),
+                         _gpr_cpp.MotionConfig(), _gpr_cpp.SARConfig())
+a = _gpr_cpp.preprocess_snapshot(s21, freq, background, mot, geom, bp, True)  # -> AScanSet
+acc, cnt = eng.aperture_volume([(a, dx, dy, dz, w), ...], gx, gy, gz)         # numpy
+```
+
+## Паритет с ноутбуком (проверено на x86 T600, датасет 20260922_mine_fast_true)
+
+Кадры 0034/0035/0036 против референсных `*_volume.npz` ноутбука
+(`make sar3d_parity` + `python_app/scripts/sar3d_volume_compare.py`):
+max|Δ| ≤ 1.6e-6 вне ножевой границы маски глубины, argmax и level совпадают
+(level rel ≤ 7e-7). Python-эталон той же цепочки:
+`python_app/scripts/sar3d_reference_check.py`.
+
+## Статус
+
+- [x] x86 (T600, sm_75, CUDA 13): собрано, паритет, standalone работает.
+- [ ] Jetson (Orin NX, sm_87, CUDA 12.6): порт тривиален (NVRTC сам берёт sm_87);
+      собрать `build_cmake.sh` на Jetson с его venv.
+- Опц.: ветка `impl='cpp'` в `gpr_core/sar3d.py` (адаптер `gpr_cpp_backend.py`),
+      кэш device-A-сканов (сейчас каждый вызов грузит стек на GPU).

data_acq_and_processing/gpr_cpp/build_cmake.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# CMake-сборка libgpr_core_cpp + standalone (без nvcc; NVRTC/driver).
+#
+# Источник CUDA (nvrtc.h / libnvrtc), по убыванию приоритета:
+#   1. env CUDA_INC / CUDA_LIB — заданы явно;
+#   2. pip-пакеты nvidia-* в venv ($VENV, по умолчанию ../../.venv — venv
+#      radar_system) — дев-машина;
+#   3. системный toolkit /usr/local/cuda — Jetson/JetPack, apt cuda-toolkit.
+#
+# GPR_BUILD_PYTHON=ON вернул бы pybind-модуль, но bindings/ не вендорен в
+# radar_system (см. README) — по умолчанию OFF.
+set -eu
+HERE="$(cd "$(dirname "$0")" && pwd)"
+VENV="${VENV:-$HERE/../../.venv}"
+PY="$VENV/bin/python"
+GPR_BUILD_PYTHON="${GPR_BUILD_PYTHON:-OFF}"
+
+CUDA_INC="${CUDA_INC:-}"
+CUDA_LIB="${CUDA_LIB:-}"
+
+if [ -z "$CUDA_INC" ] || [ -z "$CUDA_LIB" ]; then
+    if [ -x "$PY" ]; then
+        # Печатается только когда найдены nvrtc.h, cuda.h И библиотека — частичная
+        # детекция не может подсунуть мусорный путь. nvrtc.h и cuda.h могут лежать
+        # в РАЗНЫХ каталогах (раздельные pip-пакеты cuda_nvrtc/cuda_runtime на
+        # Jetson) — тогда CUDA_INC становится ';'-списком для CMake.
+        PIP_CUDA=$("$PY" - <<'P' 2>/dev/null || true
+import glob, os, site
+sp = site.getsitepackages()[0]
+nvrtc_hdr = glob.glob(os.path.join(sp, 'nvidia', '**', 'include', 'nvrtc.h'), recursive=True)
+cuda_hdr = glob.glob(os.path.join(sp, 'nvidia', '**', 'include', 'cuda.h'), recursive=True)
+lib = sorted(glob.glob(os.path.join(sp, 'nvidia', '**', 'lib', 'libnvrtc.so*'), recursive=True))
+if nvrtc_hdr and cuda_hdr and lib:
+    inc_dirs = []
+    for hdr in (nvrtc_hdr[0], cuda_hdr[0]):
+        d = os.path.dirname(hdr)
+        if d not in inc_dirs:
+            inc_dirs.append(d)
+    print(';'.join(inc_dirs))
+    print(os.path.dirname(lib[0]))
+P
+)
+        if [ -n "$PIP_CUDA" ]; then
+            CUDA_INC=$(printf '%s\n' "$PIP_CUDA" | sed -n 1p)
+            CUDA_LIB=$(printf '%s\n' "$PIP_CUDA" | sed -n 2p)
+        fi
+    fi
+fi
+
+if [ -z "$CUDA_INC" ] || [ -z "$CUDA_LIB" ]; then
+    if [ -e /usr/local/cuda/include/nvrtc.h ]; then
+        CUDA_INC=/usr/local/cuda/include
+        CUDA_LIB=/usr/local/cuda/lib64
+        echo "[build_cmake] pip nvidia-* не найдены; использую системный CUDA: $CUDA_INC"
+    else
+        echo "[build_cmake] CUDA не найден: нет ни pip nvidia-* в $VENV, ни /usr/local/cuda." >&2
+        echo "[build_cmake] Задайте CUDA_INC=<dir с nvrtc.h,cuda.h> и CUDA_LIB=<dir с libnvrtc.so*>." >&2
+        exit 1
+    fi
+fi
+
+PYTHON_ARG=()
+if [ "$GPR_BUILD_PYTHON" = "ON" ] && [ -x "$PY" ]; then
+    PYTHON_ARG=(-DPYTHON_EXECUTABLE="$PY")
+fi
+
+# cmake: сначала из venv (pip install cmake — свежий без sudo), потом системный.
+CMAKE="$VENV/bin/cmake"
+if [ ! -x "$CMAKE" ]; then
+    CMAKE=$(command -v cmake || true)
+fi
+if [ -z "$CMAKE" ]; then
+    echo "[build_cmake] cmake не найден. Поставьте его в venv: \"$VENV/bin/pip\" install cmake" >&2
+    echo "[build_cmake] (или системно: sudo apt install cmake)" >&2
+    exit 1
+fi
+
+"$CMAKE" -S "$HERE" -B "$HERE/build" \
+  ${PYTHON_ARG[@]+"${PYTHON_ARG[@]}"} \
+  -DGPR_BUILD_PYTHON="$GPR_BUILD_PYTHON" \
+  -DGPR_CUDA_INC="$CUDA_INC" \
+  -DGPR_CUDA_LIB="$CUDA_LIB" \
+  -DCMAKE_BUILD_TYPE=Release "$@" 2>&1 | tail -8
+"$CMAKE" --build "$HERE/build" -j4 2>&1 | tail -15
+echo "--- артефакты ---"
+ls -la "$HERE/build/libgpr_core_cpp.a" "$HERE/build/standalone_bp" "$HERE"/build/_gpr_cpp*.so 2>/dev/null | awk '{print $5,$9}'
+echo "CUDA_LIB=$CUDA_LIB  (для LD_LIBRARY_PATH при запуске)"

data_acq_and_processing/gpr_cpp/examples/standalone_bp.cpp

@@ -0,0 +1,159 @@
+// Автономный пример: C++ без Python. Грузит S21 снапшота из .npy,
+// строит A-сканы и 3D SAR-объём апертуры, печатает максимум |acc/cnt|.
+//
+// Использование:
+//   standalone_bp <preprocessed_dir> <center_snapshot_name>
+// где preprocessed_dir содержит папки снапшотов с i{rx}_o{tx}_s21.npy и _freq.npy.
+#include <algorithm>
+#include <cmath>
+#include <complex>
+#include <cstdint>
+#include <cstdio>
+#include <dirent.h>
+#include <fstream>
+#include <map>
+#include <string>
+#include <vector>
+
+#include "gpr/ascan.hpp"
+#include "gpr/config.hpp"
+#include "gpr/geometry.hpp"
+#include "gpr/sar3d.hpp"
+
+using namespace gpr;
+
+// --- минимальный загрузчик numpy .npy (v1.0, 1-D complex128 или float64) ---
+struct NpyArray { std::vector<double> f64; std::vector<c128> c128v; bool is_complex = false; };
+
+static NpyArray load_npy(const std::string& path) {
+    std::ifstream in(path, std::ios::binary);
+    if (!in) throw std::runtime_error("не открыть " + path);
+    char magic[6]; in.read(magic, 6);
+    uint8_t ver[2]; in.read((char*)ver, 2);
+    uint16_t hlen; in.read((char*)&hlen, 2);
+    std::string hdr(hlen, '\0'); in.read(&hdr[0], hlen);
+    auto sp = hdr.find("'shape':");
+    auto lp = hdr.find('(', sp), rp = hdr.find(')', sp);
+    long n = std::stol(hdr.substr(lp + 1, rp - lp - 1));
+    NpyArray a;
+    auto has = [&](const char* s) { return hdr.find(s) != std::string::npos; };
+    if (has("c8")) {  // complex64 → c128
+        a.is_complex = true; a.c128v.resize(n);
+        std::vector<std::complex<float>> tmp(n);
+        in.read((char*)tmp.data(), n * sizeof(std::complex<float>));
+        for (long i = 0; i < n; ++i) a.c128v[i] = c128(tmp[i].real(), tmp[i].imag());
+    } else if (has("c16")) {  // complex128
+        a.is_complex = true; a.c128v.resize(n);
+        in.read((char*)a.c128v.data(), n * sizeof(c128));
+    } else if (has("f4")) {  // float32 → double
+        a.f64.resize(n);
+        std::vector<float> tmp(n); in.read((char*)tmp.data(), n * sizeof(float));
+        for (long i = 0; i < n; ++i) a.f64[i] = tmp[i];
+    } else {  // float64
+        a.f64.resize(n); in.read((char*)a.f64.data(), n * sizeof(double));
+    }
+    return a;
+}
+
+int main(int argc, char** argv) {
+    if (argc < 3) { printf("usage: %s <preprocessed_dir> <center_snapshot>\n", argv[0]); return 1; }
+    std::string root = argv[1], center = argv[2];
+
+    GeometryConfig geom; geom.finalize();
+    BPConfig bp; MotionConfig mot; SARConfig sar;
+    auto pairs = geom.pair_keys();
+    auto tx = geom.output_idx, rx = geom.input_idx;
+    std::sort(tx.begin(), tx.end()); std::sort(rx.begin(), rx.end());
+
+    // список снапшотов, выбор апертуры вокруг center
+    std::vector<std::string> snaps;
+    if (DIR* d = opendir(root.c_str())) {
+        for (dirent* e; (e = readdir(d));) {
+            std::string n = e->d_name;
+            if (!n.empty() && isdigit(n[0])) snaps.push_back(n);
+        }
+        closedir(d);
+    }
+    std::sort(snaps.begin(), snaps.end());
+    int ci = -1; for (int i = 0; i < (int)snaps.size(); ++i) if (snaps[i] == center) ci = i;
+    if (ci < 0) { printf("центр %s не найден\n", center.c_str()); return 1; }
+    int lo = std::max(0, ci - sar.frame_radius), hi = std::min((int)snaps.size(), ci + sar.frame_radius + 1);
+    std::vector<std::string> aperture(snaps.begin() + lo, snaps.begin() + hi);
+    printf("апертура: %d кадров вокруг %s\n", (int)aperture.size(), center.c_str());
+
+    auto load_snapshot = [&](const std::string& snap,
+                             std::map<PairKey, std::vector<c128>>& s21,
+                             std::map<PairKey, std::vector<double>>& freq) {
+        for (int p = 0; p < (int)pairs.size(); ++p) {
+            int i_tx = pairs[p].first, i_rx = pairs[p].second;
+            int phys_tx = tx[i_tx], phys_rx = rx[i_rx];
+            char fn[512];
+            snprintf(fn, sizeof(fn), "%s/%s/i%d_o%d_s21.npy", root.c_str(), snap.c_str(), phys_rx, phys_tx);
+            s21[{i_tx, i_rx}] = load_npy(fn).c128v;
+            snprintf(fn, sizeof(fn), "%s/%s/i%d_o%d_freq.npy", root.c_str(), snap.c_str(), phys_rx, phys_tx);
+            freq[{i_tx, i_rx}] = load_npy(fn).f64;
+        }
+    };
+
+    // Демо без чтения meta.json: равномерные сегменты по интервалу между
+    // соседними снапшотами (реальные per-trace окна читает sar3d_parity).
+    double acq_s = 0.0;
+    {
+        std::vector<double> stamps;
+        for (auto& s : snaps) {
+            auto pos = s.rfind("_ns");
+            if (pos != std::string::npos) stamps.push_back(std::stod(s.substr(pos + 3)) * 1e-9);
+        }
+        std::sort(stamps.begin(), stamps.end());
+        if (stamps.size() >= 2) acq_s = stamps[1] - stamps[0];
+    }
+    auto windows = uniform_tx_windows(geom.output_idx, acq_s, mot.tx_per_segment);
+    auto ts = compute_pair_timestamps(windows, acq_s, geom.output_idx, geom, mot);
+    SarEngine engine(geom, bp, mot, sar);
+
+    // держим AScanSet живыми
+    std::vector<std::shared_ptr<AScanSet>> keep;
+    std::vector<ApertureFrame> frames;
+    std::vector<double> frame_times;
+    for (auto& snap : aperture) {
+        // время из суффикса _nsNNNN
+        auto pos = snap.rfind("_ns");
+        double t = (pos != std::string::npos) ? std::stod(snap.substr(pos + 3)) * 1e-9 : 0.0;
+        frame_times.push_back(t);
+    }
+    double t_ref = frame_times[ci - lo];
+    auto offs = frame_offsets(frame_times, t_ref, mot);
+    auto wts = frame_weights(offs, sar.edge_frame_weight);
+
+    for (int f = 0; f < (int)aperture.size(); ++f) {
+        std::map<PairKey, std::vector<c128>> s21;
+        std::map<PairKey, std::vector<double>> freq;
+        load_snapshot(aperture[f], s21, freq);
+        auto a = std::make_shared<AScanSet>(
+            preprocess_snapshot(s21, freq, nullptr, mot, geom, bp, ts, true));
+        keep.push_back(a);
+        frames.push_back(ApertureFrame{a.get(), offs[f], wts[f]});
+    }
+
+    // ноутбучные границы сцены (размах антенн ±2 м, полоса глубин) вместо
+    // фиксированного окна по умолчанию
+    notebook_grid_bounds(geom, bp, sar, mot.pitch_deg, 2.0,
+                         sar.x_min_m, sar.x_max_m, sar.z_min_m, sar.z_max_m);
+    Grid grid = build_full_region_grid(sar);
+    printf("сетка %dx%dx%d, счёт объёма...\n", grid.NX(), grid.NY(), grid.NZ());
+
+    VolumeRaw vol = engine.aperture_volume(frames, grid);
+    FinishedVolume fin = finish_volume(vol, grid, mot.pitch_deg, bp, sar);
+
+    double vmax = 0; size_t amax = 0;
+    for (size_t i = 0; i < fin.volume.size(); ++i)
+        if (fin.volume[i] > vmax) { vmax = fin.volume[i]; amax = i; }
+    int NX = vol.NX, NZ = vol.NZ;
+    int ix = amax % NX, iz = (amax / NX) % NZ, iy = amax / ((size_t)NX * NZ);
+    printf("МАКСИМУМ объёма: %.4f (level %.4e) в вокселе (ix=%d,iy=%d,iz=%d)\n",
+           vmax, fin.level, ix, iy, iz);
+    printf("  X=%.1f см, Y=%.1f см, Z=%.1f см\n",
+           grid.x[ix] * 100, grid.y[iy] * 100, grid.z[iz] * 100);
+    printf("OK: автономный C++ путь отработал без Python.\n");
+    return 0;
+}

data_acq_and_processing/gpr_cpp/include/gpr/ascan.hpp

@@ -0,0 +1,81 @@
+// Препроцессинг S21 → комплексные A-сканы (host, float64).
+// Порт ячейки 0 Multi_antenna_3D_clean_v1.ipynb (segmented_interleaved тайминг,
+// frequency-domain коррекция движения, k0-IFFT, нормировка пар).
+#pragma once
+#include <map>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "gpr/config.hpp"
+#include "gpr/types.hpp"
+
+namespace gpr {
+
+using PairKey = std::pair<int, int>;
+
+// Тайминг пары в модели segmented_interleaved: пара живёт в сегменте своего Tx
+// (окно [segment_start, segment_start+segment_time] от начала акквизиции),
+// внутри сегмента передатчики чередуются по частоте (slot из n_slots).
+struct PairTiming {
+    int tx_interleave_slot = 0;
+    int tx_interleave_slots = 1;
+    double segment_start_s = 0.0;
+    double segment_time_s = 0.0;
+    double t_center_s = 0.0;   // центр окна сегмента
+    // Грубый межсегментный сдвиг: dtau центра сегмента относительно центра
+    // акквизиции кадра (2*dz/v, dz = dir*speed*dt*cos(look)).
+    double dtau_pair_s = 0.0;
+};
+using PairTimestamps = std::map<PairKey, PairTiming>;
+
+// Окна захвата по Tx (output_pos → [start,end] сек от начала акквизиции).
+using TxWindows = std::map<int, std::pair<double, double>>;
+
+// Fallback без per-trace меток: сегменты по tx_per_segment штук делят кадр
+// [0, acq_s] поровну (медианная модель ноутбука compute_pair_timestamps).
+TxWindows uniform_tx_windows(const std::vector<int>& tx_order, double acq_s, int tx_per_segment);
+
+// Порт compute_pair_timestamps_for_snapshot: Tx с одинаковым окном — один
+// сегмент (сегменты по возрастанию окна), слот — порядок в tx_order (полный
+// аппаратный порядок из run.combos; выбранные каналы его не меняют).
+PairTimestamps compute_pair_timestamps(const TxWindows& tx_windows_s, double acq_s,
+                                       const std::vector<int>& tx_order,
+                                       const GeometryConfig&, const MotionConfig&);
+
+// A-сканы одного снапшота, общая ось времени у всех пар (assert).
+struct AScanSet {
+    int n_pairs = 0;
+    int n_fft = 0;
+    double t0 = 0.0, dt = 0.0;               // общая ось: t_k = t0 + k*dt
+    std::vector<PairKey> pairs;              // порядок как в geom.pair_keys()
+    std::vector<c128> H;                     // [n_pairs * n_fft] float64
+    const c128* pair_ptr(int p) const { return H.data() + (size_t)p * n_fft; }
+};
+
+// Порт sar_pair_ascans: bg-subtract → phase correction → k0-IFFT → норма.
+// s21/freq/background — по ключам (i_tx,i_rx); background может быть nullptr.
+AScanSet preprocess_snapshot(
+    const std::map<PairKey, std::vector<c128>>& s21,
+    const std::map<PairKey, std::vector<double>>& freq,
+    const std::map<PairKey, std::vector<c128>>* background,
+    const MotionConfig&, const GeometryConfig&, const BPConfig&,
+    const PairTimestamps&, bool normalize = true);
+
+// Отдельные шаги (для тестов/переиспользования):
+// Полная фазовая модель движения до IFFT: dtau_intra(f) + dtau_pair одной
+// фазой exp(sign*j*2*pi*f*dtau_total) (порт apply_intra_sweep_phase_correction).
+std::vector<c128> apply_intra_sweep_phase_correction(
+    const std::vector<c128>& s21, const std::vector<double>& freq_full,
+    const PairTiming&, const MotionConfig&, double wave_speed,
+    double f_start, double f_stop);
+
+// Возвращает t (ось), h (комплексный A-скан). n_fft через out-параметр.
+void compute_ascan_bp(const std::vector<c128>& s21, const std::vector<double>& freq,
+                      double f_start, double f_stop, bool window, int oversample,
+                      std::vector<double>& t_out, std::vector<c128>& h_out);
+
+double pair_norm_scale(const std::vector<c128>& h, const std::vector<double>& t,
+                       double wave_speed, const BPConfig&);
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/include/gpr/config.hpp

@@ -0,0 +1,114 @@
+// Конфигурация счёт-ядра. Дефолты 1:1 повторяют Multi_antenna_3D_clean_v1.ipynb
+// (ячейки 0 и 4) — эталонный ноутбук 3D SAR.
+#pragma once
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <utility>
+#include <vector>
+
+namespace gpr {
+
+struct GeometryConfig {
+    std::vector<int> input_idx{0, 1, 2, 3};
+    std::vector<int> output_idx{0, 1, 2, 3};
+    // (x,y,z) метры; порядок соответствует input_idx/output_idx
+    std::vector<std::array<double, 3>> tx_positions{
+        {-0.88, 0.0, 0.0}, {0.89, 0.0, 0.0}, {-0.33, 0.445, 0.0}, {0.33, 0.445, 0.0}};
+    std::vector<std::array<double, 3>> rx_positions{
+        {0.23, 0.0, 0.0}, {0.54, 0.15, 0.0}, {-0.55, 0.3, 0.0}, {-0.23, 0.0, 0.0}};
+    double eps_r = 1.0;
+
+    // --- производные (заполняются finalize) ---
+    std::vector<double> x_tx, y_tx, z_tx;   // отсортированы по phys-индексу
+    std::vector<double> x_rx, y_rx, z_rx;
+    int n_tx = 0, n_rx = 0;
+    double v = 0.0;
+
+    void finalize() {
+        auto sort_xyz = [](std::vector<int> idx, const std::vector<std::array<double, 3>>& pos,
+                           std::vector<double>& X, std::vector<double>& Y, std::vector<double>& Z) {
+            std::vector<int> order(idx.size());
+            for (size_t i = 0; i < idx.size(); ++i) order[i] = (int)i;
+            std::sort(order.begin(), order.end(), [&](int a, int b) { return idx[a] < idx[b]; });
+            X.clear(); Y.clear(); Z.clear();
+            for (int o : order) { X.push_back(pos[o][0]); Y.push_back(pos[o][1]); Z.push_back(pos[o][2]); }
+        };
+        sort_xyz(output_idx, tx_positions, x_tx, y_tx, z_tx);
+        sort_xyz(input_idx, rx_positions, x_rx, y_rx, z_rx);
+        n_tx = (int)output_idx.size();
+        n_rx = (int)input_idx.size();
+        v = 3e8 / std::sqrt(eps_r);
+    }
+
+    std::vector<std::pair<int, int>> pair_keys() const {
+        std::vector<std::pair<int, int>> p;
+        for (int i = 0; i < n_tx; ++i)
+            for (int j = 0; j < n_rx; ++j) p.emplace_back(i, j);
+        return p;
+    }
+};
+
+struct BPConfig {
+    double f_start = 2.0e9;
+    double f_stop = 6.0e9;
+    double min_depth = 2.5;
+    double max_depth = 8.0;
+    int oversample = 8;
+    bool window = true;                 // окно Ханна на полосе
+    bool pair_normalize = true;
+    double pair_norm_percentile = 50.0;
+    double pair_norm_depth_min = 2.5;
+    double pair_norm_depth_max = 8.0;
+    double pair_norm_eps = 1e-15;
+    // Компенсация геометрического расхождения 1/(Rtx*Rrx), нормированная на
+    // точку под виртуальным центром пары на глубине comp_ref_depth НА ПЛОСКОСТИ
+    // ЗЕМЛИ (высота (-ground_depth + d*sin p)/cos p).
+    double comp_range_power = 0.3;
+    double comp_weight_max = 5.0;
+    double comp_ref_depth = 5.0;
+};
+
+struct MotionConfig {
+    double speed_m_s = 1.45;
+    double look_angle_deg = 17.5;
+    // Наклон рамы для ground-координат и смещений кадров; в ноутбуке
+    // BP_GROUND_PITCH_DEG=None означает «равен look_angle».
+    double pitch_deg = 17.5;
+    double direction_sign = +1.0;
+    // Внутрисвиповая (по частоте) фазовая коррекция движения.
+    bool apply_freq_phase_correction = true;
+    // Грубая межсегментная коррекция (dtau сегмента относительно центра кадра),
+    // вносится той же фазовой моделью до IFFT (режим 'frequency_domain').
+    bool apply_pair_motion_correction = true;
+    double motion_phase_sign = -1.0;
+    // Fallback-разбиение кадра на сегменты, когда per-trace меток захвата нет.
+    int tx_per_segment = 2;
+};
+
+struct SARConfig {
+    int frame_radius = 0;                 // 0 = один снимок (физическая вертикальная база)
+    double edge_frame_weight = 0.8;       // вес крайнего кадра апертуры
+    bool coord_mode_ground = true;        // 'ground' vs 'radar_local'
+    bool use_compensation = true;
+    // Высота НИЖНЕГО ряда антенн над землёй; Y=0 сцены — поверхность земли.
+    double ground_depth_m = 1.25;
+    // Явные границы сцены [м]: X — поперёк, Y — высота над землёй, Z — вдаль.
+    // Воксели с радарной глубиной вне [min_depth, max_depth] всё равно
+    // обнуляются маской, так что Z-окно шире полосы глубин безопасно.
+    double x_min_m = -2.0;
+    double x_max_m = 2.0;
+    double y_min_m = -0.5;
+    double y_max_m = 2.0;
+    double z_min_m = 0.0;
+    double z_max_m = 8.0;
+    std::array<double, 3> voxel_m{0.025, 0.02, 0.02};   // шаг (X, Y, Z)
+    // Финализация объёма: нормировка без верхних/нижних norm_edge_margin_m по Y
+    // (там ложный гребень постоянной дальности), сглаживание по (Z,X) в каждом
+    // Y-плане.
+    double norm_edge_margin_m = 0.3;
+    double smooth_sigma = 1.5;
+};
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/include/gpr/device.hpp

@@ -0,0 +1,52 @@
+// CUDA Driver API RAII: контекст, поток, буфер устройства.
+#pragma once
+#include <cuda.h>
+
+#include <cstddef>
+#include <stdexcept>
+#include <string>
+
+namespace gpr {
+
+void cu_check(CUresult r, const char* what);
+
+// Инициализация драйвера + primary context на device 0. Возвращает (major,minor) CC.
+struct CudaContext {
+    CUdevice dev = 0;
+    CUcontext ctx = nullptr;
+    int cc_major = 0, cc_minor = 0;
+    CudaContext();
+    ~CudaContext();
+    std::string arch_flag() const;  // "--gpu-architecture=sm_XY"
+};
+
+template <class T>
+class DeviceBuffer {
+    CUdeviceptr ptr_ = 0;
+    size_t n_ = 0;
+
+   public:
+    DeviceBuffer() = default;
+    explicit DeviceBuffer(size_t n) { alloc(n); }
+    ~DeviceBuffer() { free(); }
+    DeviceBuffer(const DeviceBuffer&) = delete;
+    DeviceBuffer& operator=(const DeviceBuffer&) = delete;
+    DeviceBuffer(DeviceBuffer&& o) noexcept : ptr_(o.ptr_), n_(o.n_) { o.ptr_ = 0; o.n_ = 0; }
+
+    void alloc(size_t n) {
+        free();
+        if (n) cu_check(cuMemAlloc(&ptr_, n * sizeof(T)), "cuMemAlloc");
+        n_ = n;
+    }
+    void free() {
+        if (ptr_) cuMemFree(ptr_);
+        ptr_ = 0; n_ = 0;
+    }
+    void upload(const T* host, size_t n) { cu_check(cuMemcpyHtoD(ptr_, host, n * sizeof(T)), "HtoD"); }
+    void download(T* host, size_t n) const { cu_check(cuMemcpyDtoH(host, ptr_, n * sizeof(T)), "DtoH"); }
+    CUdeviceptr ptr() const { return ptr_; }
+    CUdeviceptr* addr() { return &ptr_; }
+    size_t size() const { return n_; }
+};
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/include/gpr/geometry.hpp

@@ -0,0 +1,41 @@
+// Геометрия: опорное расхождение пары, смещения/веса кадров, построение сетки.
+#pragma once
+#include <vector>
+
+#include "gpr/config.hpp"
+#include "gpr/types.hpp"
+
+namespace gpr {
+
+// 1/geo_ref пары (порт pair_geo_ref, скаляр float64).
+double pair_geo_ref(const GeometryConfig&, const BPConfig&, int i_tx, int i_rx, double yy);
+
+// Смещения кадров относительно опорного (порт sar_frame_offsets).
+// frame_times[k] — время кадра (сек, от ns-таймстемпа); t_ref — время опорного.
+std::vector<FrameOffset> frame_offsets(const std::vector<double>& frame_times, double t_ref,
+                                       const MotionConfig&);
+
+// Косинусные веса апертуры (порт sar_frame_weights); dt берётся относительно центра.
+std::vector<double> frame_weights(const std::vector<FrameOffset>& offsets, double edge_weight);
+
+// Высота плоскости земли (радарные оси) на радарной глубине depth:
+// y = (-ground_depth + depth*sin(pitch)) / cos(pitch)  (порт bp_plane_y).
+double ground_plane_y(double depth, double ground_depth_m, double pitch_rad);
+
+// Сетка сцены по явным границам SARConfig (x/y/z_min..max, шаг voxel_m);
+// оси — linspace c числом точек round(span/step)+1, как в ноутбуке.
+Grid build_full_region_grid(const SARConfig&);
+
+// Ноутбучные границы (sar_build_full_region_grid): X — размах антенн ±margin,
+// Z — полоса, покрывающая радарные глубины [min_depth, max_depth] на всех
+// высотах Y. Используются parity-инструментом для сверки с эталонными npz.
+void notebook_grid_bounds(const GeometryConfig&, const BPConfig&, const SARConfig&,
+                          double pitch_deg, double x_margin_m,
+                          double& x_min, double& x_max, double& z_min, double& z_max);
+
+// point_to_scene: оси радара → сцена (поворот на pitch + подъём на ground_depth,
+// если ground; Y=0 сцены — земля).
+std::array<double, 3> point_to_scene(double x, double y, double z, const MotionConfig&,
+                                     const SARConfig&);
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/include/gpr/nvrtc_kernel.hpp

@@ -0,0 +1,25 @@
+// Компиляция строки CUDA-ядра через NVRTC → cubin под арх устройства → CUfunction.
+#pragma once
+#include <cuda.h>
+
+#include <string>
+
+namespace gpr {
+
+class NvrtcKernel {
+    CUmodule module_ = nullptr;
+    CUfunction func_ = nullptr;
+
+   public:
+    NvrtcKernel() = default;
+    ~NvrtcKernel();
+    NvrtcKernel(const NvrtcKernel&) = delete;
+    NvrtcKernel& operator=(const NvrtcKernel&) = delete;
+
+    // Компилирует src в cubin под arch_flag ("--gpu-architecture=sm_XY"),
+    // загружает модуль и берёт функцию func_name.
+    void compile(const char* src, const std::string& arch_flag, const char* func_name);
+    CUfunction func() const { return func_; }
+};
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/include/gpr/sar3d.hpp

@@ -0,0 +1,55 @@
+// 3D SAR: сборка взвешенного объёма апертуры за один запуск ядра.
+#pragma once
+#include <memory>
+#include <vector>
+
+#include "gpr/ascan.hpp"
+#include "gpr/config.hpp"
+#include "gpr/device.hpp"
+#include "gpr/geometry.hpp"
+#include "gpr/nvrtc_kernel.hpp"
+#include "gpr/types.hpp"
+
+namespace gpr {
+
+// Один кадр апертуры: A-сканы + смещение + вес.
+struct ApertureFrame {
+    const AScanSet* ascans;
+    FrameOffset offset;
+    double weight;
+};
+
+// Сырой результат объёма (до finish_volume).
+struct VolumeRaw {
+    std::vector<c64> acc;    // [NY*NZ*NX]
+    std::vector<float> cnt;  // [NY*NZ*NX]
+    int NX = 0, NY = 0, NZ = 0;
+};
+
+// Финальный объём (порт sar_finish_volume): |acc/cnt| → маска глубины →
+// нормировка по Y-планам без краёв → гаусс по (Z,X) → нормировка → clip.
+struct FinishedVolume {
+    std::vector<float> volume;   // [NY*NZ*NX], нормирован на ~[0,1]
+    double level = 0.0;          // масштаб, на который поделён объём
+    int NX = 0, NY = 0, NZ = 0;
+};
+
+FinishedVolume finish_volume(const VolumeRaw&, const Grid&, double pitch_deg,
+                             const BPConfig&, const SARConfig&);
+
+class SarEngine {
+   public:
+    SarEngine(const GeometryConfig&, const BPConfig&, const MotionConfig&, const SARConfig&);
+    // Весь объём апертуры за один запуск ядра; возвращает сырые acc/cnt (host).
+    VolumeRaw aperture_volume(const std::vector<ApertureFrame>& frames, const Grid&);
+
+   private:
+    GeometryConfig geom_;
+    BPConfig bp_;
+    MotionConfig mot_;
+    SARConfig sar_;
+    std::unique_ptr<CudaContext> ctx_;
+    std::unique_ptr<NvrtcKernel> kernel_;
+};
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/include/gpr/types.hpp

@@ -0,0 +1,25 @@
+// Базовые типы счёт-ядра.
+#pragma once
+#include <complex>
+#include <cstdint>
+#include <vector>
+
+namespace gpr {
+
+using c64 = std::complex<float>;    // complex64, layout == cuComplex (2×float)
+using c128 = std::complex<double>;  // float64 для препроцессинга/IFFT
+
+// Ground-scene сетка (порт dict из geometry.py: x,y,z оси в метрах).
+struct Grid {
+    std::vector<double> x, y, z;
+    int NX() const { return (int)x.size(); }
+    int NY() const { return (int)y.size(); }
+    int NZ() const { return (int)z.size(); }
+};
+
+// Смещение антенн кадра апертуры (порт sar_frame_offsets).
+struct FrameOffset {
+    double dx_m = 0.0, dy_m = 0.0, dz_m = 0.0, dt_s = 0.0, horizontal_m = 0.0;
+};
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/src/ascan.cpp

@@ -0,0 +1,250 @@
+#include "gpr/ascan.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <numeric>
+#include <stdexcept>
+
+#include "pocketfft_hdronly.h"
+
+namespace gpr {
+
+TxWindows uniform_tx_windows(const std::vector<int>& tx_order, double acq_s, int tx_per_segment) {
+    TxWindows windows;
+    if (tx_order.empty()) return windows;
+    int per_seg = std::max(1, tx_per_segment);
+    int n_seg = std::max(1, (int)((tx_order.size() + per_seg - 1) / per_seg));
+    double t_seg = acq_s / n_seg;
+    for (size_t k = 0; k < tx_order.size(); ++k) {
+        int seg = (int)k / per_seg;
+        windows[tx_order[k]] = {seg * t_seg, seg * t_seg + t_seg};
+    }
+    return windows;
+}
+
+PairTimestamps compute_pair_timestamps(const TxWindows& tx_windows_s, double acq_s,
+                                       const std::vector<int>& tx_order,
+                                       const GeometryConfig& geom, const MotionConfig& mot) {
+    // Аппаратный порядок: сперва tx_order (run.combos), затем прочие ключи окон.
+    std::vector<int> hw_order;
+    for (int tx : tx_order)
+        if (tx_windows_s.count(tx) && std::find(hw_order.begin(), hw_order.end(), tx) == hw_order.end())
+            hw_order.push_back(tx);
+    for (auto& [tx, _] : tx_windows_s)
+        if (std::find(hw_order.begin(), hw_order.end(), tx) == hw_order.end())
+            hw_order.push_back(tx);
+
+    // Tx с одинаковым окном — один сегмент; сегменты по возрастанию окна,
+    // слот — порядок появления в hw_order (порт группировки ноутбука).
+    std::vector<std::pair<std::pair<double, double>, std::vector<int>>> groups;
+    for (int tx : hw_order) {
+        auto win = tx_windows_s.at(tx);
+        auto found = std::find_if(groups.begin(), groups.end(),
+                                  [&](const auto& g) { return g.first == win; });
+        if (found == groups.end())
+            groups.push_back({win, {tx}});
+        else
+            found->second.push_back(tx);
+    }
+    std::sort(groups.begin(), groups.end(),
+              [](const auto& a, const auto& b) { return a.first < b.first; });
+
+    struct SegSlot { double t0, t1; int slot, n_slots; };
+    std::map<int, SegSlot> seg_of;
+    for (auto& [win, txs] : groups)
+        for (size_t slot = 0; slot < txs.size(); ++slot)
+            seg_of[txs[slot]] = {win.first, win.second, (int)slot, (int)txs.size()};
+
+    double cos_theta = std::cos(mot.look_angle_deg * M_PI / 180.0);
+    double t_ref = 0.5 * acq_s;
+    PairTimestamps ts;
+    for (int i = 0; i < geom.n_tx; ++i) {
+        auto it = seg_of.find(geom.output_idx[i]);
+        if (it == seg_of.end())
+            throw std::runtime_error("pair timestamps: нет окна для Tx");
+        const SegSlot& s = it->second;
+        PairTiming timing;
+        timing.tx_interleave_slot = s.slot;
+        timing.tx_interleave_slots = s.n_slots;
+        timing.segment_start_s = s.t0;
+        timing.segment_time_s = s.t1 - s.t0;
+        timing.t_center_s = 0.5 * (s.t0 + s.t1);
+        double dz = mot.direction_sign * mot.speed_m_s * (timing.t_center_s - t_ref) * cos_theta;
+        timing.dtau_pair_s = 2.0 * dz / geom.v;
+        for (int j = 0; j < geom.n_rx; ++j) ts[{i, j}] = timing;
+    }
+    return ts;
+}
+
+static double median_of_diff(const std::vector<double>& f) {
+    std::vector<double> d(f.size() - 1);
+    for (size_t i = 0; i + 1 < f.size(); ++i) d[i] = f[i + 1] - f[i];
+    std::sort(d.begin(), d.end());
+    size_t n = d.size();
+    return (n % 2) ? d[n / 2] : 0.5 * (d[n / 2 - 1] + d[n / 2]);
+}
+
+std::vector<c128> apply_intra_sweep_phase_correction(
+    const std::vector<c128>& s21, const std::vector<double>& freq_full,
+    const PairTiming& info, const MotionConfig& cfg, double wave_speed,
+    double f_start, double f_stop) {
+    std::vector<c128> out = s21;
+    int n_full = (int)freq_full.size();
+    // индексы в полосе
+    std::vector<int> idx;
+    for (int i = 0; i < n_full; ++i)
+        if (freq_full[i] >= f_start && freq_full[i] <= f_stop) idx.push_back(i);
+    if (idx.empty()) throw std::runtime_error("phase corr: пустая полоса");
+    if (n_full < 2) return out;
+
+    // Сегмент проходит все n_full частот за своё окно; на каждой частоте по
+    // очереди работают его n_slots передатчиков, поэтому событие частоты i для
+    // слота slot имеет номер (n_slots*i + slot) из (n_slots*n_full).
+    int n_slots = std::max(1, info.tx_interleave_slots);
+    int slot = info.tx_interleave_slot;
+    double dt_event = info.segment_time_s / ((double)n_slots * n_full);
+    double cos_theta = std::cos(cfg.look_angle_deg * M_PI / 180.0);
+    double pair_dtau = cfg.apply_pair_motion_correction ? info.dtau_pair_s : 0.0;
+    if (!cfg.apply_freq_phase_correction && pair_dtau == 0.0) return out;
+    for (int i : idx) {
+        double dtau_intra = 0.0;
+        if (cfg.apply_freq_phase_correction) {
+            double t_abs = info.segment_start_s + (double)(n_slots * i + slot) * dt_event;
+            double dt_intra = t_abs - info.t_center_s;
+            dtau_intra = 2.0 * cfg.direction_sign * cfg.speed_m_s * cos_theta * dt_intra / wave_speed;
+        }
+        double phi = 2.0 * M_PI * freq_full[i] * (dtau_intra + pair_dtau);
+        double ang = cfg.motion_phase_sign * phi;
+        out[i] *= c128(std::cos(ang), std::sin(ang));
+    }
+    return out;
+}
+
+static int next_pow2(int x) {
+    int p = 1;
+    while (p < x) p <<= 1;
+    return p;
+}
+
+void compute_ascan_bp(const std::vector<c128>& s21, const std::vector<double>& freq,
+                      double f_start, double f_stop, bool window, int oversample,
+                      std::vector<double>& t_out, std::vector<c128>& h_out) {
+    std::vector<double> freq_cut;
+    std::vector<c128> s_cut;
+    for (size_t i = 0; i < freq.size(); ++i)
+        if (freq[i] >= f_start && freq[i] <= f_stop) {
+            freq_cut.push_back(freq[i]);
+            s_cut.push_back(s21[i]);
+        }
+    if (freq_cut.size() < 2) throw std::runtime_error("ascan: <2 точек в полосе");
+
+    double df = median_of_diff(freq_cut);
+    int n = (int)freq_cut.size();
+    int k0 = (int)std::nearbyint(freq_cut[0] / df);  // round-half-to-even как python round
+    int min_len = 2 * (k0 + n - 1);
+    int n_fft_base = next_pow2(min_len);
+    int n_fft = n_fft_base * oversample;
+    double dt = 1.0 / ((double)n_fft * df);
+
+    // окно Ханна (numpy np.hanning: 0.5 - 0.5*cos(2*pi*i/(N-1)))
+    std::vector<c128> H(n_fft, c128(0.0, 0.0));
+    for (int i = 0; i < n; ++i) {
+        c128 v = s_cut[i];
+        if (window) {
+            double w = 0.5 - 0.5 * std::cos(2.0 * M_PI * i / (n - 1));
+            v *= w;
+        }
+        H[k0 + i] = v;
+    }
+
+    // IFFT через pocketfft (backward + 1/n_fft == numpy ifft)
+    h_out.assign(n_fft, c128(0.0, 0.0));
+    pocketfft::shape_t shape{(size_t)n_fft};
+    pocketfft::stride_t stride{(ptrdiff_t)sizeof(c128)};
+    pocketfft::c2c(shape, stride, stride, {0}, pocketfft::BACKWARD,
+                   H.data(), h_out.data(), (double)(1.0 / n_fft));
+
+    t_out.resize(n_fft);
+    for (int i = 0; i < n_fft; ++i) t_out[i] = i * dt;
+}
+
+double pair_norm_scale(const std::vector<c128>& h, const std::vector<double>& t,
+                       double wave_speed, const BPConfig& bp) {
+    std::vector<double> vals;
+    vals.reserve(h.size());
+    for (size_t i = 0; i < h.size(); ++i) {
+        double z = t[i] * wave_speed / 2.0;
+        if (z >= bp.pair_norm_depth_min && z <= bp.pair_norm_depth_max)
+            vals.push_back(std::abs(h[i]));
+    }
+    if (vals.empty())
+        for (auto& c : h) vals.push_back(std::abs(c));
+    std::sort(vals.begin(), vals.end());
+    // numpy.percentile linear interpolation
+    double q = bp.pair_norm_percentile / 100.0;
+    double pos = q * (vals.size() - 1);
+    int lo = (int)std::floor(pos);
+    int hi = std::min(lo + 1, (int)vals.size() - 1);
+    double scale = vals[lo] + (pos - lo) * (vals[hi] - vals[lo]);
+    if (!std::isfinite(scale) || scale <= bp.pair_norm_eps) scale = 1.0;
+    return scale;
+}
+
+AScanSet preprocess_snapshot(
+    const std::map<PairKey, std::vector<c128>>& s21,
+    const std::map<PairKey, std::vector<double>>& freq,
+    const std::map<PairKey, std::vector<c128>>* background,
+    const MotionConfig& mot, const GeometryConfig& geom, const BPConfig& bp,
+    const PairTimestamps& ts, bool normalize) {
+    AScanSet out;
+    out.pairs = geom.pair_keys();
+    out.n_pairs = (int)out.pairs.size();
+
+    std::vector<std::vector<c128>> Hs;
+    std::vector<std::vector<double>> Ts;
+    for (auto& key : out.pairs) {
+        auto its = s21.find(key);
+        if (its == s21.end()) throw std::runtime_error("preprocess: нет пары в s21");
+        std::vector<c128> s = its->second;  // копия
+        if (background) {
+            auto ib = background->find(key);
+            if (ib != background->end())
+                for (size_t i = 0; i < s.size(); ++i) s[i] -= ib->second[i];
+        }
+        const std::vector<double>& fr = freq.at(key);
+        auto itt = ts.find(key);
+        if (itt != ts.end())
+            s = apply_intra_sweep_phase_correction(s, fr, itt->second, mot, geom.v,
+                                                   bp.f_start, bp.f_stop);
+        std::vector<double> t;
+        std::vector<c128> h;
+        compute_ascan_bp(s, fr, bp.f_start, bp.f_stop, bp.window, bp.oversample, t, h);
+        Hs.push_back(std::move(h));
+        Ts.push_back(std::move(t));
+    }
+
+    // общая ось времени — проверка
+    int n_fft = (int)Ts[0].size();
+    double t0 = Ts[0][0];
+    double dt = (Ts[0].back() - t0) / (n_fft - 1);
+    for (auto& t : Ts)
+        if ((int)t.size() != n_fft || std::abs(t[0] - t0) > 1e-18)
+            throw std::runtime_error("A-сканы: разная ось времени у пар");
+
+    if (normalize) {
+        for (int p = 0; p < out.n_pairs; ++p) {
+            double scale = pair_norm_scale(Hs[p], Ts[p], geom.v, bp);
+            for (auto& c : Hs[p]) c /= (scale + bp.pair_norm_eps);
+        }
+    }
+
+    out.n_fft = n_fft;
+    out.t0 = t0;
+    out.dt = dt;
+    out.H.resize((size_t)out.n_pairs * n_fft);
+    for (int p = 0; p < out.n_pairs; ++p)
+        std::copy(Hs[p].begin(), Hs[p].end(), out.H.begin() + (size_t)p * n_fft);
+    return out;
+}
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/src/device.cpp

@@ -0,0 +1,34 @@
+#include "gpr/device.hpp"
+
+#include <cstdio>
+
+namespace gpr {
+
+void cu_check(CUresult r, const char* what) {
+    if (r != CUDA_SUCCESS) {
+        const char* s = nullptr;
+        cuGetErrorString(r, &s);
+        throw std::runtime_error(std::string("CUDA error in ") + what + ": " + (s ? s : "?"));
+    }
+}
+
+CudaContext::CudaContext() {
+    cu_check(cuInit(0), "cuInit");
+    cu_check(cuDeviceGet(&dev, 0), "cuDeviceGet");
+    cu_check(cuDeviceGetAttribute(&cc_major, CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MAJOR, dev),
+             "cc_major");
+    cu_check(cuDeviceGetAttribute(&cc_minor, CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MINOR, dev),
+             "cc_minor");
+    cu_check(cuDevicePrimaryCtxRetain(&ctx, dev), "primaryCtxRetain");
+    cu_check(cuCtxSetCurrent(ctx), "ctxSetCurrent");
+}
+
+CudaContext::~CudaContext() {
+    if (ctx) cuDevicePrimaryCtxRelease(dev);
+}
+
+std::string CudaContext::arch_flag() const {
+    return "--gpu-architecture=sm_" + std::to_string(cc_major) + std::to_string(cc_minor);
+}
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/src/geometry.cpp

@@ -0,0 +1,104 @@
+#include "gpr/geometry.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace gpr {
+
+double pair_geo_ref(const GeometryConfig& g, const BPConfig& bp, int i_tx, int i_rx, double yy) {
+    double xc = (g.x_tx[i_tx] + g.x_rx[i_rx]) / 2.0;
+    double Rtx = std::sqrt(std::pow(xc - g.x_tx[i_tx], 2) + std::pow(yy - g.y_tx[i_tx], 2) +
+                           std::pow(bp.comp_ref_depth - g.z_tx[i_tx], 2));
+    double Rrx = std::sqrt(std::pow(xc - g.x_rx[i_rx], 2) + std::pow(yy - g.y_rx[i_rx], 2) +
+                           std::pow(bp.comp_ref_depth - g.z_rx[i_rx], 2));
+    return 1.0 / (Rtx * Rrx + 1e-12) + 1e-30;
+}
+
+std::vector<FrameOffset> frame_offsets(const std::vector<double>& frame_times, double t_ref,
+                                       const MotionConfig& cfg) {
+    std::vector<FrameOffset> out(frame_times.size());
+    double pitch = cfg.pitch_deg * M_PI / 180.0;
+    for (size_t k = 0; k < frame_times.size(); ++k) {
+        double t = frame_times[k] - t_ref;
+        double h = cfg.direction_sign * cfg.speed_m_s * t;
+        out[k].dx_m = 0.0;
+        out[k].dy_m = h * std::sin(pitch);
+        out[k].dz_m = h * std::cos(pitch);
+        out[k].dt_s = t;
+        out[k].horizontal_m = h;
+    }
+    return out;
+}
+
+std::vector<double> frame_weights(const std::vector<FrameOffset>& offs, double edge_weight) {
+    size_t n = offs.size();
+    std::vector<double> w(n, 1.0);
+    double edge = std::min(std::max(edge_weight, 0.0), 1.0);
+    if (n == 0 || edge >= 1.0) return w;
+    double dmax = 0.0;
+    for (auto& o : offs) dmax = std::max(dmax, std::abs(o.dt_s));
+    if (dmax <= 1e-12) return w;
+    for (size_t i = 0; i < n; ++i) {
+        double r = std::min(std::abs(offs[i].dt_s) / dmax, 1.0);
+        w[i] = edge + (1.0 - edge) * 0.5 * (1.0 + std::cos(M_PI * r));
+    }
+    return w;
+}
+
+std::array<double, 3> point_to_scene(double x, double y, double z, const MotionConfig& mot,
+                                     const SARConfig& sar) {
+    if (!sar.coord_mode_ground) return {x, y, z};
+    double p = mot.pitch_deg * M_PI / 180.0;
+    double ys = y * std::cos(p) - z * std::sin(p) + sar.ground_depth_m;
+    double zs = y * std::sin(p) + z * std::cos(p);
+    return {x, ys, zs};
+}
+
+double ground_plane_y(double depth, double ground_depth_m, double pitch_rad) {
+    return (-ground_depth_m + depth * std::sin(pitch_rad)) / std::cos(pitch_rad);
+}
+
+Grid build_full_region_grid(const SARConfig& sar) {
+    // numpy: linspace(lo, hi, max(round(span/step)+1, 2)); nearbyint = банковское
+    // округление python round()
+    auto axis = [](double lo, double hi, double step, std::vector<double>& out) {
+        int n = std::max((int)std::nearbyint((hi - lo) / step) + 1, 2);
+        out.resize(n);
+        for (int i = 0; i < n; ++i) out[i] = lo + (hi - lo) * i / (double)(n - 1);
+    };
+    Grid g;
+    axis(sar.x_min_m, sar.x_max_m, sar.voxel_m[0], g.x);
+    axis(sar.y_min_m, sar.y_max_m, sar.voxel_m[1], g.y);
+    axis(sar.z_min_m, sar.z_max_m, sar.voxel_m[2], g.z);
+    return g;
+}
+
+void notebook_grid_bounds(const GeometryConfig& geom, const BPConfig& bp, const SARConfig& sar,
+                          double pitch_deg, double x_margin_m,
+                          double& x_min, double& x_max, double& z_min, double& z_max) {
+    double x_lo = geom.x_tx[0], x_hi = geom.x_tx[0];
+    for (double x : geom.x_tx) { x_lo = std::min(x_lo, x); x_hi = std::max(x_hi, x); }
+    for (double x : geom.x_rx) { x_lo = std::min(x_lo, x); x_hi = std::max(x_hi, x); }
+    x_min = x_lo - x_margin_m;
+    x_max = x_hi + x_margin_m;
+
+    // Радарная z линейна по Z сцены при фиксированной высоте:
+    // z_rad(Y, Z=0) = -(Y - ground_depth)*sin(p), z = (depth - z_rad)/cos(p).
+    double p = pitch_deg * M_PI / 180.0;
+    double cos_p = std::cos(p), sin_p = std::sin(p);
+    double z_lo = 0.0, z_hi = 0.0;
+    bool first = true;
+    for (double y : {sar.y_min_m, sar.y_max_m}) {
+        for (double depth : {bp.min_depth, bp.max_depth}) {
+            double z_rad0 = -(y - sar.ground_depth_m) * sin_p;
+            double z = (depth - z_rad0) / cos_p;
+            if (first) { z_lo = z_hi = z; first = false; }
+            z_lo = std::min(z_lo, z);
+            z_hi = std::max(z_hi, z);
+        }
+    }
+    z_min = z_lo;
+    z_max = z_hi;
+}
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/src/kernel_src.hpp

@@ -0,0 +1,83 @@
+// Исходник CUDA-ядра для NVRTC (порт sar_frame_contribution из
+// Multi_antenna_3D_clean_v1.ipynb). Self-contained complex<float>.
+//
+// Геометрия (координаты, дальности, tau, вес компенсации) считается в double:
+// эталон ноутбука — float64, а в float32 позиция выборки A-скана (тысячи
+// отсчётов) теряет ~3e-4 отсчёта и расходится с эталоном на ~1e-4. A-сканы
+// остаются float32 — их значения O(1) и линейная интерполяция не теряет.
+#pragma once
+
+namespace gpr {
+
+inline const char* APERTURE_KERNEL_SRC = R"CUDA(
+struct cf { float x, y; };
+
+// Взвешенный объём апертуры: один поток на воксель, внутренний цикл по
+// n_contrib = n_frames*n_pairs. Обрабатывается диапазон вокселей
+// [gid_begin, gid_end) — хост запускает ядро чанками, переиспользуя небольшие
+// acc/cnt-буферы (полный объём в VRAM не обязан помещаться: на десктопе с
+// занятой другими процессами картой свободных может быть <200 МБ).
+extern "C" __global__ void bp_aperture_contribution(
+    const cf* __restrict__ H,
+    const double t0, const double inv_dt, const int n_fft, const double inv_v,
+    const double* __restrict__ xt, const double* __restrict__ yt, const double* __restrict__ zt,
+    const double* __restrict__ xr, const double* __restrict__ yr, const double* __restrict__ zr,
+    const double* __restrict__ inv_geo_ref, const float* __restrict__ wgt,
+    const double* __restrict__ gx, const double* __restrict__ gy, const double* __restrict__ gz,
+    const int NX, const int NY, const int NZ, const int n_contrib,
+    const long gid_begin, const long gid_end,
+    const double cos_p, const double sin_p, const double ground_depth,
+    const double min_depth, const double max_depth,
+    const double comp_pow, const double w_max, const int use_comp,
+    cf* __restrict__ acc, float* __restrict__ cnt)
+{
+    for (long gid = gid_begin + blockIdx.x * blockDim.x + threadIdx.x;
+         gid < gid_end; gid += (long)gridDim.x * blockDim.x) {
+        int ix = gid % NX;
+        int iz = (gid / NX) % NZ;
+        int iy = gid / ((long)NX * NZ);
+        double x = gx[ix];
+        double zs = gz[iz];
+        // Сцена → оси радара: Y=0 сцены — земля, ground_depth ниже нижнего ряда
+        // антенн (порт sar_scene_to_radar_yz).
+        double y0 = gy[iy] - ground_depth;
+        double y_rad = y0 * cos_p + zs * sin_p;
+        double z_rad = -y0 * sin_p + zs * cos_p;
+        bool depth_ok = (z_rad >= min_depth) && (z_rad <= max_depth);
+
+        double ax = 0.0, ay = 0.0;
+        float c = 0.f;
+        for (int i = 0; i < n_contrib; ++i) {
+            double dxt = x - xt[i], dyt = y_rad - yt[i], dzt = z_rad - zt[i];
+            double dxr = x - xr[i], dyr = y_rad - yr[i], dzr = z_rad - zr[i];
+            double Rt = sqrt(dxt*dxt + dyt*dyt + dzt*dzt);
+            double Rr = sqrt(dxr*dxr + dyr*dyr + dzr*dzr);
+            double pos = ((Rt + Rr) * inv_v - t0) * inv_dt;
+            bool inside = (pos >= 0.0) && (pos <= (double)(n_fft - 1));
+            if (!inside || !depth_ok) continue;
+            int k = (int)floor(pos);
+            if (k < 0) k = 0;
+            if (k > n_fft - 2) k = n_fft - 2;
+            float f = (float)(pos - (double)k);
+            const cf* h = H + (long)i * n_fft;
+            float hx = h[k].x + f * (h[k+1].x - h[k].x);
+            float hy = h[k].y + f * (h[k+1].y - h[k].y);
+            double w = (double)wgt[i];
+            if (use_comp) {
+                double ratio = (1.0/(Rt*Rr + 1e-12) + 1e-30) * inv_geo_ref[i];
+                double ww = 1.0/(pow(ratio, comp_pow) + 1e-12);
+                ww = fmin(fmax(ww, 0.0), w_max);
+                w *= ww;
+            }
+            ax += w * (double)hx;
+            ay += w * (double)hy;
+            c += wgt[i];
+        }
+        acc[gid - gid_begin].x = (float)ax;
+        acc[gid - gid_begin].y = (float)ay;
+        cnt[gid - gid_begin] = c;
+    }
+}
+)CUDA";
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/src/nvrtc_kernel.cpp

@@ -0,0 +1,48 @@
+#include "gpr/nvrtc_kernel.hpp"
+
+#include <nvrtc.h>
+
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "gpr/device.hpp"
+
+namespace gpr {
+
+static void nvrtc_check(nvrtcResult r, const char* what) {
+    if (r != NVRTC_SUCCESS)
+        throw std::runtime_error(std::string("NVRTC error in ") + what + ": " +
+                                 nvrtcGetErrorString(r));
+}
+
+NvrtcKernel::~NvrtcKernel() {
+    if (module_) cuModuleUnload(module_);
+}
+
+void NvrtcKernel::compile(const char* src, const std::string& arch_flag, const char* func_name) {
+    nvrtcProgram prog;
+    nvrtc_check(nvrtcCreateProgram(&prog, src, "gpr_kernel.cu", 0, nullptr, nullptr),
+                "createProgram");
+    std::vector<const char*> opts{arch_flag.c_str()};
+    nvrtcResult cr = nvrtcCompileProgram(prog, (int)opts.size(), opts.data());
+    if (cr != NVRTC_SUCCESS) {
+        size_t logsz = 0;
+        nvrtcGetProgramLogSize(prog, &logsz);
+        std::string log(logsz, '\0');
+        if (logsz) nvrtcGetProgramLog(prog, &log[0]);
+        nvrtcDestroyProgram(&prog);
+        throw std::runtime_error("NVRTC compile failed:\n" + log);
+    }
+    // cubin под точную арх (без JIT PTX — драйвер грузит SASS напрямую)
+    size_t cubsz = 0;
+    nvrtc_check(nvrtcGetCUBINSize(prog, &cubsz), "getCUBINSize");
+    std::string cubin(cubsz, '\0');
+    nvrtc_check(nvrtcGetCUBIN(prog, &cubin[0]), "getCUBIN");
+    nvrtcDestroyProgram(&prog);
+
+    cu_check(cuModuleLoadDataEx(&module_, cubin.data(), 0, nullptr, nullptr), "moduleLoad");
+    cu_check(cuModuleGetFunction(&func_, module_, func_name), "getFunction");
+}
+
+}  // namespace gpr

data_acq_and_processing/gpr_cpp/src/sar3d.cpp

@@ -0,0 +1,233 @@
+#include "gpr/sar3d.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <stdexcept>
+
+#include "kernel_src.hpp"
+
+namespace gpr {
+
+SarEngine::SarEngine(const GeometryConfig& g, const BPConfig& bp, const MotionConfig& mot,
+                     const SARConfig& sar)
+    : geom_(g), bp_(bp), mot_(mot), sar_(sar) {
+    geom_.finalize();
+    ctx_ = std::make_unique<CudaContext>();
+    kernel_ = std::make_unique<NvrtcKernel>();
+    kernel_->compile(APERTURE_KERNEL_SRC, ctx_->arch_flag(), "bp_aperture_contribution");
+}
+
+VolumeRaw SarEngine::aperture_volume(const std::vector<ApertureFrame>& frames, const Grid& grid) {
+    if (frames.empty()) throw std::runtime_error("aperture_volume: нет кадров");
+    auto pairs = geom_.pair_keys();
+    int n_pairs = (int)pairs.size();
+    int n_frames = (int)frames.size();
+    int n_contrib = n_frames * n_pairs;
+
+    const AScanSet& a0 = *frames[0].ascans;
+    int n_fft = a0.n_fft;
+    double t0 = a0.t0, dt = a0.dt;
+
+    int NX = grid.NX(), NY = grid.NY(), NZ = grid.NZ();
+    size_t nvox = (size_t)NX * NY * NZ;
+
+    double pitch = mot_.pitch_deg * M_PI / 180.0;
+    // Опорное расхождение пары — на плоскости земли на глубине comp_ref_depth.
+    double geo_ref_y = sar_.coord_mode_ground
+                           ? ground_plane_y(bp_.comp_ref_depth, sar_.ground_depth_m, pitch)
+                           : 0.0;
+
+    // Плоские массивы по (кадр, пара)
+    std::vector<c64> H_stack((size_t)n_contrib * n_fft);
+    std::vector<double> xt(n_contrib), yt(n_contrib), zt(n_contrib);
+    std::vector<double> xr(n_contrib), yr(n_contrib), zr(n_contrib);
+    std::vector<double> igr(n_contrib);
+    std::vector<float> wgt(n_contrib);
+    int idx = 0;
+    for (int f = 0; f < n_frames; ++f) {
+        const AScanSet& a = *frames[f].ascans;
+        if (a.n_fft != n_fft || std::abs(a.t0 - t0) > 1e-18)
+            throw std::runtime_error("кадры апертуры: разная ось времени");
+        double dx = frames[f].offset.dx_m, dy = frames[f].offset.dy_m, dz = frames[f].offset.dz_m;
+        float w = (float)frames[f].weight;
+        for (int p = 0; p < n_pairs; ++p) {
+            int i = pairs[p].first, j = pairs[p].second;
+            // A-скан пары p → в стек (каст c128→c64)
+            const c128* src = a.pair_ptr(p);
+            c64* dst = H_stack.data() + (size_t)idx * n_fft;
+            for (int k = 0; k < n_fft; ++k) dst[k] = c64((float)src[k].real(), (float)src[k].imag());
+            xt[idx] = geom_.x_tx[i] + dx; yt[idx] = geom_.y_tx[i] + dy;
+            zt[idx] = geom_.z_tx[i] + dz;
+            xr[idx] = geom_.x_rx[j] + dx; yr[idx] = geom_.y_rx[j] + dy;
+            zr[idx] = geom_.z_rx[j] + dz;
+            igr[idx] = 1.0 / pair_geo_ref(geom_, bp_, i, j, geo_ref_y);
+            wgt[idx] = w;
+            ++idx;
+        }
+    }
+
+    double cos_p = 1.0, sin_p = 0.0, ground_depth = 0.0;
+    if (sar_.coord_mode_ground) {
+        cos_p = std::cos(pitch);
+        sin_p = std::sin(pitch);
+        ground_depth = sar_.ground_depth_m;
+    }
+
+    // Заливка на устройство
+    DeviceBuffer<c64> dH(H_stack.size()); dH.upload(H_stack.data(), H_stack.size());
+    DeviceBuffer<double> dxt(n_contrib), dyt(n_contrib), dzt(n_contrib);
+    DeviceBuffer<double> dxr(n_contrib), dyr(n_contrib), dzr(n_contrib);
+    DeviceBuffer<double> digr(n_contrib);
+    DeviceBuffer<float> dwgt(n_contrib);
+    dxt.upload(xt.data(), n_contrib); dyt.upload(yt.data(), n_contrib); dzt.upload(zt.data(), n_contrib);
+    dxr.upload(xr.data(), n_contrib); dyr.upload(yr.data(), n_contrib); dzr.upload(zr.data(), n_contrib);
+    digr.upload(igr.data(), n_contrib); dwgt.upload(wgt.data(), n_contrib);
+    DeviceBuffer<double> dgx(NX), dgy(NY), dgz(NZ);
+    dgx.upload(grid.x.data(), NX); dgy.upload(grid.y.data(), NY); dgz.upload(grid.z.data(), NZ);
+
+    // Объём считается чанками с переиспользуемыми acc/cnt-буферами: полные
+    // буферы (~115 МБ на сетку 9.6 млн вокселей) могут не влезать в остаток
+    // VRAM, когда карту делят десктоп-процессы.
+    const size_t chunk_vox = std::min<size_t>(nvox, 2'000'000);
+    DeviceBuffer<c64> dacc(chunk_vox);
+    DeviceBuffer<float> dcnt(chunk_vox);
+
+    double inv_dt = 1.0 / dt, inv_v = 1.0 / geom_.v;
+    double min_d = bp_.min_depth, max_d = bp_.max_depth;
+    double comp_pow = bp_.comp_range_power, w_max = bp_.comp_weight_max;
+    int use_comp = sar_.use_compensation ? 1 : 0;
+
+    VolumeRaw out;
+    out.NX = NX; out.NY = NY; out.NZ = NZ;
+    out.acc.resize(nvox); out.cnt.resize(nvox);
+    int block = 256;
+    for (size_t begin = 0; begin < nvox; begin += chunk_vox) {
+        const size_t end = std::min(nvox, begin + chunk_vox);
+        long gid_begin = (long)begin, gid_end = (long)end;
+        void* args[] = {
+            dH.addr(), &t0, &inv_dt, &n_fft, &inv_v,
+            dxt.addr(), dyt.addr(), dzt.addr(), dxr.addr(), dyr.addr(), dzr.addr(),
+            digr.addr(), dwgt.addr(), dgx.addr(), dgy.addr(), dgz.addr(),
+            &NX, &NY, &NZ, &n_contrib, &gid_begin, &gid_end,
+            &cos_p, &sin_p, &ground_depth, &min_d, &max_d,
+            &comp_pow, &w_max, &use_comp, dacc.addr(), dcnt.addr()};
+        int gridDim = (int)std::min<long>(65535, ((long)(end - begin) + block - 1) / block);
+        cu_check(cuLaunchKernel(kernel_->func(), gridDim, 1, 1, block, 1, 1, 0, 0, args, nullptr),
+                 "launch aperture");
+        cu_check(cuCtxSynchronize(), "sync");
+        dacc.download(out.acc.data() + begin, end - begin);
+        dcnt.download(out.cnt.data() + begin, end - begin);
+    }
+    return out;
+}
+
+namespace {
+
+// scipy.ndimage.gaussian_filter: ядро радиуса int(truncate*sigma+0.5), reflect.
+std::vector<double> gaussian_kernel_1d(double sigma, int radius) {
+    std::vector<double> w(2 * radius + 1);
+    double sum = 0.0;
+    for (int i = -radius; i <= radius; ++i) {
+        w[i + radius] = std::exp(-0.5 * i * i / (sigma * sigma));
+        sum += w[i + radius];
+    }
+    for (auto& v : w) v /= sum;
+    return w;
+}
+
+// Корреляция вдоль оси с reflect-границами ('d c b a | a b c d').
+inline int reflect_index(int i, int n) {
+    while (i < 0 || i >= n) {
+        if (i < 0) i = -i - 1;
+        if (i >= n) i = 2 * n - i - 1;
+    }
+    return i;
+}
+
+}  // namespace
+
+FinishedVolume finish_volume(const VolumeRaw& raw, const Grid& grid, double pitch_deg,
+                             const BPConfig& bp, const SARConfig& sar) {
+    int NX = raw.NX, NY = raw.NY, NZ = raw.NZ;
+    size_t nvox = (size_t)NX * NY * NZ;
+    FinishedVolume out;
+    out.NX = NX; out.NY = NY; out.NZ = NZ;
+
+    std::vector<double> vol(nvox);
+    for (size_t i = 0; i < nvox; ++i)
+        vol[i] = std::abs(c128(raw.acc[i].real(), raw.acc[i].imag())) / ((double)raw.cnt[i] + 1e-12);
+
+    // Маска глубины в радарных осях (в ядре невалидные вкладов не получали,
+    // но |0/(0+eps)| уже 0; обнуление здесь повторяет ноутбук буквально).
+    if (sar.coord_mode_ground) {
+        double p = pitch_deg * M_PI / 180.0;
+        double cos_p = std::cos(p), sin_p = std::sin(p);
+        for (int iy = 0; iy < NY; ++iy) {
+            double y0 = grid.y[iy] - sar.ground_depth_m;
+            for (int iz = 0; iz < NZ; ++iz) {
+                double z_rad = -y0 * sin_p + grid.z[iz] * cos_p;
+                if (z_rad >= bp.min_depth && z_rad <= bp.max_depth) continue;
+                double* row = vol.data() + ((size_t)iy * NZ + iz) * NX;
+                std::fill(row, row + NX, 0.0);
+            }
+        }
+    }
+
+    // Плоскости Y для нормировки: без верхних/нижних norm_edge_margin_m.
+    std::vector<bool> ref_plane(NY, true);
+    double margin = sar.norm_edge_margin_m;
+    double y_span = grid.y.back() - grid.y.front();
+    if (margin > 0.0 && y_span > 2.5 * margin) {
+        for (int iy = 0; iy < NY; ++iy)
+            ref_plane[iy] = grid.y[iy] >= grid.y.front() + margin &&
+                            grid.y[iy] <= grid.y.back() - margin;
+    }
+    auto ref_max = [&](const std::vector<double>& v) {
+        double m = 0.0;
+        for (int iy = 0; iy < NY; ++iy) {
+            if (!ref_plane[iy]) continue;
+            const double* plane = v.data() + (size_t)iy * NZ * NX;
+            for (size_t i = 0; i < (size_t)NZ * NX; ++i) m = std::max(m, plane[i]);
+        }
+        return m + 1e-12;
+    };
+
+    double level_raw = ref_max(vol);
+    for (auto& v : vol) v /= level_raw;
+
+    // Гаусс sigma=(0, s, s): сглаживание по Z и X внутри каждого Y-плана
+    // (порядок осей как у scipy: сначала ось 1, затем ось 2).
+    if (sar.smooth_sigma > 0.0) {
+        int radius = (int)(4.0 * sar.smooth_sigma + 0.5);
+        const auto kernel = gaussian_kernel_1d(sar.smooth_sigma, radius);
+        std::vector<double> tmp((size_t)NZ * NX);
+        for (int iy = 0; iy < NY; ++iy) {
+            double* plane = vol.data() + (size_t)iy * NZ * NX;
+            // вдоль Z (ось 1)
+            for (int iz = 0; iz < NZ; ++iz)
+                for (int ix = 0; ix < NX; ++ix) {
+                    double s = 0.0;
+                    for (int k = -radius; k <= radius; ++k)
+                        s += kernel[k + radius] * plane[(size_t)reflect_index(iz + k, NZ) * NX + ix];
+                    tmp[(size_t)iz * NX + ix] = s;
+                }
+            // вдоль X (ось 2)
+            for (int iz = 0; iz < NZ; ++iz)
+                for (int ix = 0; ix < NX; ++ix) {
+                    double s = 0.0;
+                    for (int k = -radius; k <= radius; ++k)
+                        s += kernel[k + radius] * tmp[(size_t)iz * NX + reflect_index(ix + k, NX)];
+                    plane[(size_t)iz * NX + ix] = s;
+                }
+        }
+    }
+
+    double level_smooth = ref_max(vol);
+    out.volume.resize(nvox);
+    for (size_t i = 0; i < nvox; ++i)
+        out.volume[i] = (float)std::max(vol[i] / level_smooth, 0.0);
+    out.level = level_raw * level_smooth;
+    return out;
+}
+
+}  // namespace gpr

data_acq_and_processing/processing/data_processor/include/processing_live_config.hpp

@@ -90,6 +90,51 @@ struct ProcessingLiveConfig {
     float gpr_visible_x_max_m = 2.0F;
     float gpr_visible_z_min_m = 0.0F;
     float gpr_visible_z_max_m = 14.0F;
+    // 3D SAR (sar3d processor) parameters; defaults mirror the reference
+    // notebook Multi_antenna_3D_clean_v1.ipynb (cells 0/4). Frequency band,
+    // depth gate, antenna selection and motion (speed, look angle, direction,
+    // phase correction) are shared with the gpr_* fields.
+    std::uint32_t sar3d_frame_radius = 0U;
+    float sar3d_edge_frame_weight = 0.8F;
+    // Frame pitch for ground coordinates and inter-frame offsets. Override
+    // disabled -> the pitch follows gpr_look_angle_deg (notebook
+    // BP_GROUND_PITCH_DEG = None).
+    bool sar3d_pitch_override_enabled = false;
+    float sar3d_pitch_deg = 17.5F;
+    // Height of the LOWER antenna row above the ground; scene Y=0 is the ground.
+    float sar3d_ground_depth_m = 1.25F;
+    // Scene grid bounds (metres): X across, Y height above the ground, Z along
+    // the ground away from the radar. Voxels whose radar depth falls outside
+    // [gpr_min_depth, gpr_max_depth] are zeroed by the mask regardless.
+    // Doubles, not floats: the parity tool feeds the notebook-derived bounds
+    // through here and a float roundtrip shifts the grid by ~1e-7 m, flipping
+    // knife-edge voxels of the depth mask against the reference volumes.
+    double sar3d_x_min_m = -2.0;
+    double sar3d_x_max_m = 2.0;
+    double sar3d_y_min_m = -0.5;
+    double sar3d_y_max_m = 2.0;
+    double sar3d_z_min_m = 0.0;
+    double sar3d_z_max_m = 8.0;
+    float sar3d_voxel_x_m = 0.025F;
+    float sar3d_voxel_y_m = 0.02F;
+    float sar3d_voxel_z_m = 0.02F;
+    // Volume finalization: normalization ignores this much of the grid's Y
+    // edges (constant-range ridge), then Gaussian smoothing over (Z, X).
+    float sar3d_norm_edge_margin_m = 0.3F;
+    float sar3d_smooth_sigma = 1.5F;
+    // Geometric spreading compensation 1/(Rtx*Rrx)^power, capped.
+    float sar3d_comp_range_power = 0.3F;
+    // Fallback frame segmentation when per-trace capture stamps are absent.
+    std::uint32_t sar3d_tx_per_segment = 2U;
+    bool sar3d_use_compensation = true;
+    bool sar3d_normalize_pairs = true;
+    // Debug: when non-empty, the processor dumps every finished volume to this
+    // directory (raw float32 + json header). Used by the parity tool only.
+    std::string sar3d_volume_dump_dir{};
+    // Bottom-view projection angle around the vertical Y axis, degrees:
+    // 0 = front view (X horizontal), 90 = side view (Z horizontal),
+    // intermediate values project along the rotated horizontal direction.
+    float sar3d_bottom_view_deg = 0.0F;
     // When true, the data_processor ignores socket-supplied `vlc` updates and
     // keeps using `gpr_speed_m_s` from this file. Mirrored from the GUI's
     // "ignore socket speed" checkbox.

data_acq_and_processing/processing/data_processor/src/data_processor.cpp

@@ -13,6 +13,7 @@
 #include "bscan_processor.hpp"
 #include "gpr_processor.hpp"
 #include "passthrough_processor.hpp"
+#include "sar3d_processor.hpp"
 
 namespace radar::processing {
 namespace {
@@ -280,6 +281,10 @@ auto create_default_processors() -> ProcessorRegistry {
         auto processor = std::make_unique<LegacyGprProcessor>();
         processors.emplace(processor->name(), std::move(processor));
     }
+    {
+        auto processor = std::make_unique<Sar3dProcessor>();
+        processors.emplace(processor->name(), std::move(processor));
+    }
     return processors;
 }
 

data_acq_and_processing/processing/data_processor/src/processing_live_config.cpp

@@ -386,6 +386,61 @@ void apply_legacy_gpr_algorithm_alias(ProcessingLiveConfig& config, const std::s
         config.gpr_object_approach_min_frames =
             parse_u32_number(*found, "processing.gpr_object_approach_min_frames");
     }
+    if (const auto found = root.find("sar3d_frame_radius"); found != root.end()) {
+        config.sar3d_frame_radius = parse_u32_number(*found, "processing.sar3d_frame_radius");
+    }
+    for (const auto& [key, target] : {
+             std::pair{"sar3d_edge_frame_weight", &config.sar3d_edge_frame_weight},
+             std::pair{"sar3d_pitch_deg", &config.sar3d_pitch_deg},
+             std::pair{"sar3d_ground_depth_m", &config.sar3d_ground_depth_m},
+             std::pair{"sar3d_voxel_x_m", &config.sar3d_voxel_x_m},
+             std::pair{"sar3d_voxel_y_m", &config.sar3d_voxel_y_m},
+             std::pair{"sar3d_voxel_z_m", &config.sar3d_voxel_z_m},
+             std::pair{"sar3d_norm_edge_margin_m", &config.sar3d_norm_edge_margin_m},
+             std::pair{"sar3d_smooth_sigma", &config.sar3d_smooth_sigma},
+             std::pair{"sar3d_comp_range_power", &config.sar3d_comp_range_power},
+             std::pair{"sar3d_bottom_view_deg", &config.sar3d_bottom_view_deg},
+         }) {
+        if (const auto found = root.find(key); found != root.end()) {
+            if (!found->is_number()) {
+                throw std::runtime_error(std::string("processing.") + key + " must be number");
+            }
+            *target = static_cast<float>(found->get<double>());
+        }
+    }
+    for (const auto& [key, target] : {
+             std::pair{"sar3d_x_min_m", &config.sar3d_x_min_m},
+             std::pair{"sar3d_x_max_m", &config.sar3d_x_max_m},
+             std::pair{"sar3d_y_min_m", &config.sar3d_y_min_m},
+             std::pair{"sar3d_y_max_m", &config.sar3d_y_max_m},
+             std::pair{"sar3d_z_min_m", &config.sar3d_z_min_m},
+             std::pair{"sar3d_z_max_m", &config.sar3d_z_max_m},
+         }) {
+        if (const auto found = root.find(key); found != root.end()) {
+            if (!found->is_number()) {
+                throw std::runtime_error(std::string("processing.") + key + " must be number");
+            }
+            *target = found->get<double>();
+        }
+    }
+    if (const auto found = root.find("sar3d_tx_per_segment"); found != root.end()) {
+        config.sar3d_tx_per_segment = parse_u32_number(*found, "processing.sar3d_tx_per_segment");
+        if (config.sar3d_tx_per_segment == 0U) {
+            throw std::runtime_error("processing.sar3d_tx_per_segment must be >= 1");
+        }
+    }
+    for (const auto& [key, target] : {
+             std::pair{"sar3d_pitch_override_enabled", &config.sar3d_pitch_override_enabled},
+             std::pair{"sar3d_use_compensation", &config.sar3d_use_compensation},
+             std::pair{"sar3d_normalize_pairs", &config.sar3d_normalize_pairs},
+         }) {
+        if (const auto found = root.find(key); found != root.end()) {
+            if (!found->is_boolean()) {
+                throw std::runtime_error(std::string("processing.") + key + " must be bool");
+            }
+            *target = found->get<bool>();
+        }
+    }
     if (const auto found = root.find("ignore_socket_speed"); found != root.end()) {
         if (!found->is_boolean()) {
             throw std::runtime_error("processing.ignore_socket_speed must be bool");

data_acq_and_processing/processing/processors/include/sar3d_processor.hpp

@@ -0,0 +1,34 @@
+#pragma once
+
+#include <memory>
+#include <span>
+#include <string>
+
+#include "processor_interface.hpp"
+
+namespace radar::processing {
+
+// 3D SAR over a synthesized aperture, computed by the external gpr_cpp
+// CUDA/NVRTC library (VNA_AlGo). Emits 2D max-projections of the volume
+// (side XZ and top XY views) as ImageF32 collection payloads.
+class Sar3dProcessor final : public ProcessorInterface {
+  public:
+    Sar3dProcessor();
+    ~Sar3dProcessor() override;
+
+    [[nodiscard]] auto name() const -> std::string override;
+    [[nodiscard]] auto process_collection(
+        const config::RunConfig& run_config,
+        const ipc::PreprocessedCollection& collection,
+        std::span<const ipc::PreprocessedCollection> previous_collections,
+        const ProcessingLiveConfig& live_config
+    ) -> ipc::ResultCollection override;
+
+  private:
+    // Pimpl keeps gpr/CUDA headers (cuda.h, nvrtc.h) out of the shared
+    // processor include path; only sar3d_processor.cpp needs them.
+    struct State;
+    std::unique_ptr<State> state_;
+};
+
+}  // namespace radar::processing

data_acq_and_processing/processing/processors/src/sar3d_processor.cpp

@@ -0,0 +1,677 @@
+#include "sar3d_processor.hpp"
+
+#include <algorithm>
+#include <bit>
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <fstream>
+#include <iostream>
+#include <limits>
+#include <map>
+#include <optional>
+#include <stdexcept>
+#include <vector>
+
+#include "gpr/ascan.hpp"
+#include "gpr/config.hpp"
+#include "gpr/geometry.hpp"
+#include "gpr/sar3d.hpp"
+
+namespace radar::processing {
+namespace {
+
+constexpr std::size_t kAscanCacheLimit = 64U;
+
+void hash_mix(std::size_t& seed, std::uint64_t value) {
+    seed ^= value + 0x9e3779b97f4a7c15ULL + (seed << 6U) + (seed >> 2U);
+}
+
+void hash_mix(std::size_t& seed, double value) {
+    hash_mix(seed, std::bit_cast<std::uint64_t>(value));
+}
+
+[[nodiscard]] auto contains_u32(const std::vector<std::uint32_t>& values, std::uint32_t value) -> bool {
+    return std::find(values.begin(), values.end(), value) != values.end();
+}
+
+// Requested positions filtered to the available set; empty request selects all.
+// Mirrors the coherent-BP processor's selection semantics.
+[[nodiscard]] auto selected_positions(
+    const std::vector<std::uint32_t>& requested,
+    std::vector<std::uint32_t> available
+) -> std::vector<std::uint32_t> {
+    std::sort(available.begin(), available.end());
+    available.erase(std::unique(available.begin(), available.end()), available.end());
+    if (requested.empty()) {
+        return available;
+    }
+    std::vector<std::uint32_t> result{};
+    for (const auto value : requested) {
+        if (contains_u32(available, value) && !contains_u32(result, value)) {
+            result.push_back(value);
+        }
+    }
+    std::sort(result.begin(), result.end());
+    return result;
+}
+
+struct Selection {
+    // Sorted ascending switch positions; the logical pair key (i_tx, i_rx) is
+    // the index of a position within these lists.
+    std::vector<std::uint32_t> inputs{};
+    std::vector<std::uint32_t> outputs{};
+};
+
+[[nodiscard]] auto build_selection(
+    const config::RunConfig& run_config,
+    const ProcessingLiveConfig& live_config
+) -> Selection {
+    std::vector<std::uint32_t> available_inputs{};
+    available_inputs.reserve(run_config.gpr.rx_geometry.size());
+    for (const auto& entry : run_config.gpr.rx_geometry) {
+        available_inputs.push_back(entry.input_pos);
+    }
+    std::vector<std::uint32_t> available_outputs{};
+    available_outputs.reserve(run_config.gpr.tx_geometry.size());
+    for (const auto& entry : run_config.gpr.tx_geometry) {
+        available_outputs.push_back(entry.output_pos);
+    }
+    Selection selection{};
+    selection.inputs = selected_positions(live_config.gpr_input_positions, std::move(available_inputs));
+    selection.outputs = selected_positions(live_config.gpr_output_positions, std::move(available_outputs));
+    return selection;
+}
+
+[[nodiscard]] auto build_geometry(
+    const config::RunConfig& run_config,
+    const Selection& selection
+) -> gpr::GeometryConfig {
+    gpr::GeometryConfig geom{};
+    geom.input_idx.clear();
+    geom.output_idx.clear();
+    geom.rx_positions.clear();
+    geom.tx_positions.clear();
+    for (const auto position : selection.inputs) {
+        for (const auto& entry : run_config.gpr.rx_geometry) {
+            if (entry.input_pos == position) {
+                geom.input_idx.push_back(static_cast<int>(position));
+                geom.rx_positions.push_back({
+                    static_cast<double>(entry.x_m),
+                    static_cast<double>(entry.y_m),
+                    static_cast<double>(entry.z_m),
+                });
+                break;
+            }
+        }
+    }
+    for (const auto position : selection.outputs) {
+        for (const auto& entry : run_config.gpr.tx_geometry) {
+            if (entry.output_pos == position) {
+                geom.output_idx.push_back(static_cast<int>(position));
+                geom.tx_positions.push_back({
+                    static_cast<double>(entry.x_m),
+                    static_cast<double>(entry.y_m),
+                    static_cast<double>(entry.z_m),
+                });
+                break;
+            }
+        }
+    }
+    geom.eps_r = static_cast<double>(run_config.gpr.relative_permittivity);
+    geom.finalize();
+    return geom;
+}
+
+[[nodiscard]] auto build_bp_config(const ProcessingLiveConfig& live_config) -> gpr::BPConfig {
+    gpr::BPConfig bp{};
+    bp.f_start = static_cast<double>(live_config.gpr_start_freq_mhz) * 1e6;
+    bp.f_stop = static_cast<double>(live_config.gpr_stop_freq_mhz) * 1e6;
+    bp.min_depth = static_cast<double>(live_config.gpr_min_depth_m);
+    bp.max_depth = static_cast<double>(live_config.gpr_max_depth_m);
+    bp.pair_normalize = live_config.sar3d_normalize_pairs;
+    bp.pair_norm_depth_min = bp.min_depth;
+    bp.pair_norm_depth_max = bp.max_depth;
+    bp.comp_range_power = static_cast<double>(live_config.sar3d_comp_range_power);
+    return bp;
+}
+
+[[nodiscard]] auto build_motion_config(const ProcessingLiveConfig& live_config) -> gpr::MotionConfig {
+    gpr::MotionConfig motion{};
+    motion.speed_m_s = static_cast<double>(live_config.gpr_speed_m_s);
+    motion.look_angle_deg = static_cast<double>(live_config.gpr_look_angle_deg);
+    // Notebook BP_GROUND_PITCH_DEG = None -> the frame pitch follows the look angle.
+    motion.pitch_deg = live_config.sar3d_pitch_override_enabled
+                           ? static_cast<double>(live_config.sar3d_pitch_deg)
+                           : static_cast<double>(live_config.gpr_look_angle_deg);
+    motion.direction_sign = static_cast<double>(live_config.gpr_direction_sign);
+    motion.apply_freq_phase_correction = live_config.gpr_apply_freq_phase_correction;
+    motion.tx_per_segment = static_cast<int>(std::max<std::uint32_t>(1U, live_config.sar3d_tx_per_segment));
+    return motion;
+}
+
+[[nodiscard]] auto build_sar_config(const ProcessingLiveConfig& live_config) -> gpr::SARConfig {
+    gpr::SARConfig sar{};
+    sar.frame_radius = static_cast<int>(std::max<std::uint32_t>(0U, live_config.sar3d_frame_radius));
+    sar.edge_frame_weight = static_cast<double>(live_config.sar3d_edge_frame_weight);
+    sar.ground_depth_m = static_cast<double>(live_config.sar3d_ground_depth_m);
+    sar.x_min_m = static_cast<double>(live_config.sar3d_x_min_m);
+    sar.x_max_m = static_cast<double>(live_config.sar3d_x_max_m);
+    sar.y_min_m = static_cast<double>(live_config.sar3d_y_min_m);
+    sar.y_max_m = static_cast<double>(live_config.sar3d_y_max_m);
+    sar.z_min_m = static_cast<double>(live_config.sar3d_z_min_m);
+    sar.z_max_m = static_cast<double>(live_config.sar3d_z_max_m);
+    sar.voxel_m = {
+        static_cast<double>(live_config.sar3d_voxel_x_m),
+        static_cast<double>(live_config.sar3d_voxel_y_m),
+        static_cast<double>(live_config.sar3d_voxel_z_m),
+    };
+    sar.norm_edge_margin_m = static_cast<double>(live_config.sar3d_norm_edge_margin_m);
+    sar.smooth_sigma = static_cast<double>(live_config.sar3d_smooth_sigma);
+    sar.use_compensation = live_config.sar3d_use_compensation;
+    return sar;
+}
+
+// Hardware Tx order: first occurrence of each output in run_combos. Deliberately
+// ignores the live Tx selection so segment/slot assignment stays a hardware
+// property (notebook tx_order_full).
+[[nodiscard]] auto tx_order_full(const config::RunConfig& run_config) -> std::vector<int> {
+    std::vector<int> order{};
+    for (const auto& combo : run_config.run_combos) {
+        const int output = static_cast<int>(combo.output_pos);
+        if (std::find(order.begin(), order.end(), output) == order.end()) {
+            order.push_back(output);
+        }
+    }
+    return order;
+}
+
+[[nodiscard]] auto ascan_fingerprint(
+    const Selection& selection,
+    const gpr::GeometryConfig& geom,
+    const gpr::BPConfig& bp,
+    const gpr::MotionConfig& motion
+) -> std::size_t {
+    std::size_t seed = 0U;
+    for (const auto position : selection.inputs) {
+        hash_mix(seed, static_cast<std::uint64_t>(position));
+    }
+    for (const auto position : selection.outputs) {
+        hash_mix(seed, static_cast<std::uint64_t>(static_cast<std::uint64_t>(position) | (1ULL << 40U)));
+    }
+    hash_mix(seed, geom.eps_r);
+    hash_mix(seed, bp.f_start);
+    hash_mix(seed, bp.f_stop);
+    hash_mix(seed, bp.pair_norm_depth_min);
+    hash_mix(seed, bp.pair_norm_depth_max);
+    hash_mix(seed, static_cast<std::uint64_t>(bp.pair_normalize ? 1U : 0U));
+    hash_mix(seed, motion.speed_m_s);
+    hash_mix(seed, motion.look_angle_deg);
+    hash_mix(seed, motion.direction_sign);
+    hash_mix(seed, static_cast<std::uint64_t>(motion.apply_freq_phase_correction ? 1U : 0U));
+    hash_mix(seed, static_cast<std::uint64_t>(motion.tx_per_segment));
+    return seed;
+}
+
+[[nodiscard]] auto engine_fingerprint(
+    const gpr::GeometryConfig& geom,
+    const gpr::BPConfig& bp,
+    const gpr::MotionConfig& motion,
+    const gpr::SARConfig& sar
+) -> std::size_t {
+    std::size_t seed = 1U;
+    for (std::size_t index = 0U; index < geom.tx_positions.size(); ++index) {
+        hash_mix(seed, static_cast<std::uint64_t>(geom.output_idx[index]));
+        hash_mix(seed, geom.tx_positions[index][0]);
+        hash_mix(seed, geom.tx_positions[index][1]);
+        hash_mix(seed, geom.tx_positions[index][2]);
+    }
+    for (std::size_t index = 0U; index < geom.rx_positions.size(); ++index) {
+        hash_mix(seed, static_cast<std::uint64_t>(geom.input_idx[index]));
+        hash_mix(seed, geom.rx_positions[index][0]);
+        hash_mix(seed, geom.rx_positions[index][1]);
+        hash_mix(seed, geom.rx_positions[index][2]);
+    }
+    hash_mix(seed, geom.eps_r);
+    hash_mix(seed, bp.f_start);
+    hash_mix(seed, bp.f_stop);
+    hash_mix(seed, bp.min_depth);
+    hash_mix(seed, bp.max_depth);
+    hash_mix(seed, bp.comp_range_power);
+    hash_mix(seed, bp.comp_weight_max);
+    hash_mix(seed, bp.comp_ref_depth);
+    hash_mix(seed, motion.pitch_deg);
+    hash_mix(seed, sar.ground_depth_m);
+    hash_mix(seed, static_cast<std::uint64_t>(sar.use_compensation ? 1U : 0U));
+    return seed;
+}
+
+// Midpoint of the collection's capture window; monotonic_ns is the fallback for
+// producers that never stamped capture times.
+[[nodiscard]] auto collection_time_s(const ipc::PreprocessedCollection& collection) -> double {
+    if (collection.capture_end_ns > collection.capture_start_ns) {
+        return 0.5 * (static_cast<double>(collection.capture_start_ns) + static_cast<double>(collection.capture_end_ns)) * 1e-9;
+    }
+    return static_cast<double>(collection.monotonic_ns) * 1e-9;
+}
+
+// Real frame timing from the per-trace capture stamps: traces measured in one
+// segment share one window on both producers, so the first window seen per Tx
+// reconstructs the segments exactly (notebook snapshot_acquisition_timing).
+// Invalid when any trace carries the zero "unmeasured" sentinel.
+struct SnapshotTiming {
+    gpr::TxWindows windows{};    // seconds relative to the first trace start
+    double acq_s = 0.0;
+    double center_abs_s = 0.0;   // absolute acquisition centre (frame time)
+    bool valid = false;
+};
+
+[[nodiscard]] auto snapshot_timing(const ipc::PreprocessedCollection& collection) -> SnapshotTiming {
+    SnapshotTiming timing{};
+    if (collection.traces.empty()) {
+        return timing;
+    }
+    std::map<int, std::pair<std::uint64_t, std::uint64_t>> by_tx{};
+    std::uint64_t first = std::numeric_limits<std::uint64_t>::max();
+    std::uint64_t last = 0U;
+    for (const auto& trace : collection.traces) {
+        if (trace.capture_end_ns <= trace.capture_start_ns) {
+            return timing;
+        }
+        by_tx.try_emplace(
+            static_cast<int>(trace.combo.output_pos),
+            std::pair{trace.capture_start_ns, trace.capture_end_ns}
+        );
+        first = std::min(first, trace.capture_start_ns);
+        last = std::max(last, trace.capture_end_ns);
+    }
+    for (const auto& [tx, window] : by_tx) {
+        timing.windows[tx] = {
+            static_cast<double>(window.first - first) * 1e-9,
+            static_cast<double>(window.second - first) * 1e-9,
+        };
+    }
+    timing.acq_s = static_cast<double>(last - first) * 1e-9;
+    timing.center_abs_s = 0.5 * (static_cast<double>(first) + static_cast<double>(last)) * 1e-9;
+    timing.valid = true;
+    return timing;
+}
+
+// Debug dump for the parity tool: raw float32 volume [iy][iz][ix] plus a json
+// header with the axes and level.
+void dump_volume(
+    const std::string& dir,
+    std::uint64_t collection_id,
+    const gpr::FinishedVolume& finished,
+    const gpr::Grid& grid
+) {
+    char name[64];
+    std::snprintf(name, sizeof(name), "/sar3d_volume_%llu",
+                  static_cast<unsigned long long>(collection_id));
+    const std::string base = dir + name;
+    std::ofstream bin(base + ".f32", std::ios::binary | std::ios::trunc);
+    bin.write(
+        reinterpret_cast<const char*>(finished.volume.data()),
+        static_cast<std::streamsize>(finished.volume.size() * sizeof(float))
+    );
+    std::ofstream meta(base + ".json", std::ios::trunc);
+    meta.precision(17);
+    meta << "{\"nx\": " << finished.NX << ", \"ny\": " << finished.NY
+         << ", \"nz\": " << finished.NZ << ", \"level\": " << finished.level;
+    const auto write_axis = [&meta](const char* key, const std::vector<double>& axis) {
+        meta << ", \"" << key << "\": [";
+        for (std::size_t index = 0U; index < axis.size(); ++index) {
+            meta << (index > 0U ? "," : "") << axis[index];
+        }
+        meta << "]";
+    };
+    write_axis("x_m", grid.x);
+    write_axis("y_m", grid.y);
+    write_axis("z_m", grid.z);
+    meta << "}\n";
+}
+
+[[nodiscard]] auto build_image_payload(
+    const std::string& processing_name,
+    const std::vector<double>& x_axis,
+    const std::vector<double>& y_axis,
+    std::vector<float> values
+) -> ipc::ResultPayload {
+    ipc::ResultPayload payload{};
+    payload.processing_name = processing_name;
+    payload.kind = ipc::ResultKind::ImageF32;
+    payload.image_x_axis.reserve(x_axis.size());
+    for (const auto value : x_axis) {
+        payload.image_x_axis.push_back(static_cast<float>(value));
+    }
+    payload.image_y_axis.reserve(y_axis.size());
+    for (const auto value : y_axis) {
+        payload.image_y_axis.push_back(static_cast<float>(value));
+    }
+    payload.image_values = std::move(values);
+    return payload;
+}
+
+}  // namespace
+
+struct Sar3dProcessor::State {
+    struct CacheEntry {
+        double time_s = 0.0;
+        // Null when the collection could not be preprocessed (e.g. missing
+        // pairs); cached so a bad collection is not retried every frame.
+        std::shared_ptr<gpr::AScanSet> ascans{};
+    };
+
+    // Keyed by collection_id (monotonically increasing), so evicting from the
+    // front drops the oldest collections.
+    std::map<std::uint64_t, CacheEntry> ascan_cache{};
+    std::size_t ascan_fp = 0U;
+
+    std::unique_ptr<gpr::SarEngine> engine{};
+    std::size_t engine_fp = 0U;
+
+    std::string last_error{};
+    std::uint64_t suppressed_errors = 0U;
+
+    auto get_or_compute_ascans(
+        const ipc::PreprocessedCollection& collection,
+        const Selection& selection,
+        const gpr::GeometryConfig& geom,
+        const gpr::BPConfig& bp,
+        const gpr::MotionConfig& motion,
+        const std::vector<int>& tx_order
+    ) -> const CacheEntry& {
+        if (const auto found = ascan_cache.find(collection.collection_id); found != ascan_cache.end()) {
+            return found->second;
+        }
+
+        CacheEntry entry{};
+        auto timing = snapshot_timing(collection);
+        // The segmented model needs a window for every selected Tx; fall back to
+        // the uniform split otherwise (notebook median model).
+        if (timing.valid) {
+            for (const auto output : geom.output_idx) {
+                if (timing.windows.find(output) == timing.windows.end()) {
+                    timing.valid = false;
+                    break;
+                }
+            }
+        }
+        entry.time_s = timing.valid ? timing.center_abs_s : collection_time_s(collection);
+
+        std::map<gpr::PairKey, std::vector<gpr::c128>> s21{};
+        std::map<gpr::PairKey, std::vector<double>> freq{};
+        for (const auto& trace : collection.traces) {
+            const auto input_it = std::find(selection.inputs.begin(), selection.inputs.end(), trace.combo.input_pos);
+            const auto output_it = std::find(selection.outputs.begin(), selection.outputs.end(), trace.combo.output_pos);
+            if (input_it == selection.inputs.end() || output_it == selection.outputs.end()) {
+                continue;
+            }
+            const gpr::PairKey key{
+                static_cast<int>(output_it - selection.outputs.begin()),
+                static_cast<int>(input_it - selection.inputs.begin()),
+            };
+            auto& samples = s21[key];
+            samples.clear();
+            samples.reserve(trace.s21.size());
+            for (const auto& sample : trace.s21) {
+                samples.emplace_back(static_cast<double>(sample.re), static_cast<double>(sample.im));
+            }
+            auto& axis = freq[key];
+            axis.assign(trace.frequency_hz.begin(), trace.frequency_hz.end());
+        }
+
+        if (s21.size() == selection.inputs.size() * selection.outputs.size()) {
+            gpr::TxWindows windows{};
+            double acq_s = 0.0;
+            if (timing.valid) {
+                windows = std::move(timing.windows);
+                acq_s = timing.acq_s;
+            } else {
+                if (collection.capture_end_ns > collection.capture_start_ns) {
+                    acq_s = static_cast<double>(collection.capture_end_ns - collection.capture_start_ns) * 1e-9;
+                }
+                auto order = tx_order;
+                for (const auto output : geom.output_idx) {
+                    if (std::find(order.begin(), order.end(), output) == order.end()) {
+                        order.push_back(output);
+                    }
+                }
+                windows = gpr::uniform_tx_windows(order, acq_s, motion.tx_per_segment);
+            }
+            try {
+                const auto timestamps = gpr::compute_pair_timestamps(windows, acq_s, tx_order, geom, motion);
+                entry.ascans = std::make_shared<gpr::AScanSet>(gpr::preprocess_snapshot(
+                    s21, freq, /*background=*/nullptr, motion, geom, bp, timestamps, bp.pair_normalize
+                ));
+            } catch (const std::exception& exc) {
+                // A malformed collection (e.g. empty band after a sweep change)
+                // is cached as a skipped frame instead of failing the aperture.
+                report_error(std::string{"preprocess_snapshot: "} + exc.what());
+                entry.ascans = nullptr;
+            }
+        }
+
+        auto [inserted, _] = ascan_cache.emplace(collection.collection_id, std::move(entry));
+        while (ascan_cache.size() > kAscanCacheLimit) {
+            ascan_cache.erase(ascan_cache.begin());
+        }
+        return inserted->second;
+    }
+
+    void report_error(const std::string& message) {
+        if (message == last_error) {
+            ++suppressed_errors;
+            return;
+        }
+        if (suppressed_errors > 0U) {
+            std::cerr << "sar3d: previous error repeated " << suppressed_errors << " times\n";
+        }
+        std::cerr << "sar3d: " << message << '\n';
+        last_error = message;
+        suppressed_errors = 0U;
+    }
+};
+
+Sar3dProcessor::Sar3dProcessor() : state_(std::make_unique<State>()) {}
+
+Sar3dProcessor::~Sar3dProcessor() = default;
+
+auto Sar3dProcessor::name() const -> std::string {
+    return "sar3d";
+}
+
+auto Sar3dProcessor::process_collection(
+    const config::RunConfig& run_config,
+    const ipc::PreprocessedCollection& collection,
+    std::span<const ipc::PreprocessedCollection> previous_collections,
+    const ProcessingLiveConfig& live_config
+) -> ipc::ResultCollection {
+    ipc::ResultCollection results{};
+    results.collection_id = collection.collection_id;
+    results.monotonic_ns = collection.monotonic_ns;
+
+    try {
+        const auto selection = build_selection(run_config, live_config);
+        if (selection.inputs.empty() || selection.outputs.empty()) {
+            return results;
+        }
+        const auto geom = build_geometry(run_config, selection);
+        const auto bp = build_bp_config(live_config);
+        const auto motion = build_motion_config(live_config);
+        const auto sar = build_sar_config(live_config);
+        if (!(bp.max_depth > bp.min_depth) || !(bp.f_stop > bp.f_start)) {
+            return results;
+        }
+
+        const auto ascan_fp = ascan_fingerprint(selection, geom, bp, motion);
+        if (ascan_fp != state_->ascan_fp) {
+            state_->ascan_cache.clear();
+            state_->ascan_fp = ascan_fp;
+        }
+
+        // Aperture window: the newest 2r+1 collections, current one last.
+        const std::size_t window_size = 2U * static_cast<std::size_t>(sar.frame_radius) + 1U;
+        std::vector<const ipc::PreprocessedCollection*> window{};
+        window.reserve(window_size);
+        const std::size_t history_take = std::min(previous_collections.size(), window_size - 1U);
+        for (std::size_t index = previous_collections.size() - history_take; index < previous_collections.size(); ++index) {
+            window.push_back(&previous_collections[index]);
+        }
+        window.push_back(&collection);
+
+        const auto tx_order = tx_order_full(run_config);
+        std::vector<std::shared_ptr<gpr::AScanSet>> ascan_sets{};
+        std::vector<double> frame_times{};
+        ascan_sets.reserve(window.size());
+        frame_times.reserve(window.size());
+        for (const auto* entry_collection : window) {
+            const auto& entry =
+                state_->get_or_compute_ascans(*entry_collection, selection, geom, bp, motion, tx_order);
+            if (entry.ascans == nullptr) {
+                continue;
+            }
+            ascan_sets.push_back(entry.ascans);
+            frame_times.push_back(entry.time_s);
+        }
+        if (ascan_sets.empty()) {
+            return results;
+        }
+
+        // aperture_volume requires one shared time axis; drop frames whose axis
+        // differs from the current collection's (e.g. after a sweep-grid change).
+        const auto& reference = *ascan_sets.back();
+        for (std::size_t index = ascan_sets.size(); index-- > 0U;) {
+            const auto& candidate = *ascan_sets[index];
+            if (candidate.n_fft != reference.n_fft || std::abs(candidate.t0 - reference.t0) > 1e-18 ||
+                candidate.n_pairs != reference.n_pairs) {
+                ascan_sets.erase(ascan_sets.begin() + static_cast<std::ptrdiff_t>(index));
+                frame_times.erase(frame_times.begin() + static_cast<std::ptrdiff_t>(index));
+            }
+        }
+        if (ascan_sets.empty()) {
+            return results;
+        }
+
+        // Symmetric aperture: the reference frame sits `radius` frames before the
+        // newest one, so the published volume lags the input by `radius` frames.
+        const std::size_t center_index =
+            ascan_sets.size() > static_cast<std::size_t>(sar.frame_radius)
+                ? ascan_sets.size() - 1U - static_cast<std::size_t>(sar.frame_radius)
+                : 0U;
+        const auto offsets = gpr::frame_offsets(frame_times, frame_times[center_index], motion);
+        const auto weights = gpr::frame_weights(offsets, sar.edge_frame_weight);
+        std::vector<gpr::ApertureFrame> frames{};
+        frames.reserve(ascan_sets.size());
+        for (std::size_t index = 0U; index < ascan_sets.size(); ++index) {
+            frames.push_back(gpr::ApertureFrame{ascan_sets[index].get(), offsets[index], weights[index]});
+        }
+
+        const auto engine_fp = engine_fingerprint(geom, bp, motion, sar);
+        if (state_->engine == nullptr || state_->engine_fp != engine_fp) {
+            state_->engine = std::make_unique<gpr::SarEngine>(geom, bp, motion, sar);
+            state_->engine_fp = engine_fp;
+        }
+
+        const gpr::Grid grid = gpr::build_full_region_grid(sar);
+        const gpr::VolumeRaw raw = state_->engine->aperture_volume(frames, grid);
+        // Full notebook finalization: |acc/cnt|, depth gate, normalization
+        // without the Y-edge planes, Gaussian smoothing over (Z, X), clip.
+        const gpr::FinishedVolume finished =
+            gpr::finish_volume(raw, grid, motion.pitch_deg, bp, sar);
+
+        if (!live_config.sar3d_volume_dump_dir.empty()) {
+            dump_volume(live_config.sar3d_volume_dump_dir, collection.collection_id, finished, grid);
+        }
+
+        // Two projections match the legacy render conventions (X across,
+        // Z range/"вдаль", Y up):
+        // - top view `sar3d_proj_xz`: max over Y, axes X (horizontal) / Z;
+        // - bottom view `sar3d_proj_bottom`: vertical axis is always Y, the
+        //   horizontal axis u is the ground direction rotated by
+        //   `sar3d_bottom_view_deg` around Y: 0° = front view (u = X, max
+        //   along Z), 90° = side view (u = Z, max along X), intermediate
+        //   angles project along the rotated perpendicular.
+        const int nx = finished.NX;
+        const int ny = finished.NY;
+        const int nz = finished.NZ;
+
+        const double theta_deg = std::clamp(static_cast<double>(live_config.sar3d_bottom_view_deg), 0.0, 90.0);
+        const double theta_rad = theta_deg * M_PI / 180.0;
+        const double cos_t = std::cos(theta_rad);
+        const double sin_t = std::sin(theta_rad);
+        // Exact-axis fast paths keep the front/side views on the native grid.
+        const bool front_view = theta_deg <= 1e-9;
+        const bool side_view = theta_deg >= 90.0 - 1e-9;
+        std::vector<double> u_axis{};
+        if (front_view) {
+            u_axis = grid.x;
+        } else if (side_view) {
+            u_axis = grid.z;
+        } else {
+            const double u_a = grid.x.front() * cos_t + grid.z.front() * sin_t;
+            const double u_b = grid.x.front() * cos_t + grid.z.back() * sin_t;
+            const double u_c = grid.x.back() * cos_t + grid.z.front() * sin_t;
+            const double u_d = grid.x.back() * cos_t + grid.z.back() * sin_t;
+            const double u_min = std::min(std::min(u_a, u_b), std::min(u_c, u_d));
+            const double u_max = std::max(std::max(u_a, u_b), std::max(u_c, u_d));
+            u_axis.resize(static_cast<std::size_t>(nx));
+            for (int iu = 0; iu < nx; ++iu) {
+                u_axis[static_cast<std::size_t>(iu)] = u_min + (u_max - u_min) * iu / static_cast<double>(nx - 1);
+            }
+        }
+        const int nu = static_cast<int>(u_axis.size());
+        const double u_start = u_axis.front();
+        const double inv_du = nu > 1 ? static_cast<double>(nu - 1) / (u_axis.back() - u_start) : 0.0;
+
+        // The volume is already normalized to ~[0, 1] by finish_volume, so the
+        // projections are published as-is; the scalar payload carries `level`
+        // (the absolute scale the volume was divided by).
+        std::vector<float> projection_xz(static_cast<std::size_t>(nz) * nx, 0.0F);
+        std::vector<float> projection_bottom(static_cast<std::size_t>(ny) * nu, 0.0F);
+        for (int iy = 0; iy < ny; ++iy) {
+            for (int iz = 0; iz < nz; ++iz) {
+                const std::size_t row = (static_cast<std::size_t>(iy) * nz + iz) * nx;
+                const std::size_t bottom_row = static_cast<std::size_t>(iy) * nu;
+                const double z_sin_t = grid.z[iz] * sin_t;
+                for (int ix = 0; ix < nx; ++ix) {
+                    const float value = finished.volume[row + static_cast<std::size_t>(ix)];
+                    auto& xz_cell = projection_xz[static_cast<std::size_t>(iz) * nx + ix];
+                    xz_cell = std::max(xz_cell, value);
+                    int bin = ix;
+                    if (side_view) {
+                        bin = iz;
+                    } else if (!front_view) {
+                        const double u = grid.x[ix] * cos_t + z_sin_t;
+                        bin = static_cast<int>(std::lround((u - u_start) * inv_du));
+                        bin = std::clamp(bin, 0, nu - 1);
+                    }
+                    auto& bottom_cell = projection_bottom[bottom_row + static_cast<std::size_t>(bin)];
+                    bottom_cell = std::max(bottom_cell, value);
+                }
+            }
+        }
+
+        results.collection_payloads.push_back(
+            build_image_payload("sar3d_proj_xz", grid.x, grid.z, std::move(projection_xz))
+        );
+        results.collection_payloads.push_back(
+            build_image_payload("sar3d_proj_bottom", u_axis, grid.y, std::move(projection_bottom))
+        );
+        ipc::ResultPayload peak_payload{};
+        peak_payload.processing_name = "sar3d_peak";
+        peak_payload.kind = ipc::ResultKind::ScalarF32;
+        peak_payload.scalar_value = static_cast<float>(finished.level);
+        results.collection_payloads.push_back(std::move(peak_payload));
+    } catch (const std::exception& exc) {
+        // A CUDA/NVRTC or data error must not kill the data_processor loop:
+        // publish an empty result and keep going. Repeated identical errors are
+        // logged once with a suppression count.
+        state_->report_error(exc.what());
+        results.collection_payloads.clear();
+    }
+
+    return results;
+}
+
+}  // namespace radar::processing

data_acq_and_processing/processing/tools/sar3d_parity_main.cpp

@@ -0,0 +1,349 @@
+// Parity check of the sar3d processor against the reference notebook
+// Multi_antenna_3D_clean_v1.ipynb.
+//
+// Feeds a preprocessed snapshot of an extracted replay dataset through
+// Sar3dProcessor exactly the way the live pipeline would (geometry and combo
+// order from the dataset's config_profile.json, per-trace capture windows from
+// the snapshot's meta.json) and dumps the finished volume for comparison with
+// the notebook's *_volume.npz export:
+//
+//   sar3d_parity <dataset_root> <center_snapshot> [--dump-dir <dir>]
+//   python_app/scripts/sar3d_volume_compare.py <dir>/sar3d_volume_<id> <ref.npz>
+//
+// <dataset_root> contains config_profile.json and preprocessed/<snapshot>/.
+// Defaults mirror the parameters the reference volumes were built with
+// (f 2..6 GHz, depth 2.5..8 m, speed 1.45 m/s, look angle 17.5 deg).
+#include <algorithm>
+#include <cctype>
+#include <complex>
+#include <cstdint>
+#include <cstdio>
+#include <dirent.h>
+#include <fstream>
+#include <span>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include <nlohmann/json.hpp>
+
+#include "gpr/config.hpp"
+#include "gpr/geometry.hpp"
+#include "processing_live_config.hpp"
+#include "run_config.hpp"
+#include "sar3d_processor.hpp"
+#include "shared_types.hpp"
+
+namespace {
+
+// Minimal numpy .npy loader (v1.0, 1-D complex128/complex64/float64/float32).
+struct NpyArray {
+    std::vector<double> f64{};
+    std::vector<std::complex<double>> c128{};
+};
+
+NpyArray load_npy(const std::string& path) {
+    std::ifstream in(path, std::ios::binary);
+    if (!in) {
+        throw std::runtime_error("cannot open " + path);
+    }
+    char magic[6];
+    in.read(magic, 6);
+    std::uint8_t version[2];
+    in.read(reinterpret_cast<char*>(version), 2);
+    std::uint16_t header_len = 0;
+    in.read(reinterpret_cast<char*>(&header_len), 2);
+    std::string header(header_len, '\0');
+    in.read(header.data(), header_len);
+    const auto shape_pos = header.find("'shape':");
+    const auto left = header.find('(', shape_pos);
+    const auto right = header.find(')', shape_pos);
+    const long count = std::stol(header.substr(left + 1, right - left - 1));
+
+    NpyArray array{};
+    const auto has = [&header](const char* token) { return header.find(token) != std::string::npos; };
+    if (has("c8")) {
+        array.c128.resize(count);
+        std::vector<std::complex<float>> tmp(count);
+        in.read(reinterpret_cast<char*>(tmp.data()), count * sizeof(std::complex<float>));
+        for (long i = 0; i < count; ++i) {
+            array.c128[i] = std::complex<double>(tmp[i].real(), tmp[i].imag());
+        }
+    } else if (has("c16")) {
+        array.c128.resize(count);
+        in.read(reinterpret_cast<char*>(array.c128.data()), count * sizeof(std::complex<double>));
+    } else if (has("f4")) {
+        array.f64.resize(count);
+        std::vector<float> tmp(count);
+        in.read(reinterpret_cast<char*>(tmp.data()), count * sizeof(float));
+        for (long i = 0; i < count; ++i) {
+            array.f64[i] = tmp[i];
+        }
+    } else {
+        array.f64.resize(count);
+        in.read(reinterpret_cast<char*>(array.f64.data()), count * sizeof(double));
+    }
+    return array;
+}
+
+// Live config matching the reference notebook run (npz meta parameters).
+// The default program grid is a fixed window (X -2..2, Z 0..8), while the
+// notebook derives its bounds from the antenna span and the depth gate — so
+// the notebook bounds are recomputed here and passed explicitly.
+auto build_live_config(const radar::config::RunConfig& run_config)
+    -> radar::processing::ProcessingLiveConfig {
+    radar::processing::ProcessingLiveConfig live{};
+    live.processor_mode = "sar3d";
+    live.gpr_start_freq_mhz = 2000.0F;
+    live.gpr_stop_freq_mhz = 6000.0F;
+    live.gpr_min_depth_m = 2.5F;
+    live.gpr_max_depth_m = 8.0F;
+    live.gpr_speed_m_s = 1.45F;
+    live.gpr_look_angle_deg = 17.5F;
+    live.gpr_direction_sign = 1.0F;
+    live.gpr_apply_freq_phase_correction = true;
+
+    gpr::GeometryConfig geom{};
+    geom.input_idx.clear();
+    geom.output_idx.clear();
+    geom.rx_positions.clear();
+    geom.tx_positions.clear();
+    for (const auto& entry : run_config.gpr.rx_geometry) {
+        geom.input_idx.push_back(static_cast<int>(entry.input_pos));
+        geom.rx_positions.push_back({entry.x_m, entry.y_m, entry.z_m});
+    }
+    for (const auto& entry : run_config.gpr.tx_geometry) {
+        geom.output_idx.push_back(static_cast<int>(entry.output_pos));
+        geom.tx_positions.push_back({entry.x_m, entry.y_m, entry.z_m});
+    }
+    geom.finalize();
+    gpr::BPConfig bp{};
+    bp.min_depth = live.gpr_min_depth_m;
+    bp.max_depth = live.gpr_max_depth_m;
+    gpr::SARConfig sar{};
+    double x_min = 0.0, x_max = 0.0, z_min = 0.0, z_max = 0.0;
+    gpr::notebook_grid_bounds(geom, bp, sar, live.gpr_look_angle_deg, /*x_margin_m=*/2.0,
+                              x_min, x_max, z_min, z_max);
+    live.sar3d_x_min_m = x_min;
+    live.sar3d_x_max_m = x_max;
+    live.sar3d_z_min_m = z_min;
+    live.sar3d_z_max_m = z_max;
+    return live;
+}
+
+auto load_collection(
+    const radar::config::RunConfig& run_config,
+    const std::string& root,
+    const std::string& snapshot,
+    std::uint64_t collection_id
+) -> radar::ipc::PreprocessedCollection {
+    radar::ipc::PreprocessedCollection collection{};
+    collection.collection_id = collection_id;
+
+    // Per-trace capture windows from the snapshot's meta.json; the segmented
+    // timing model is reconstructed from them exactly like in the notebook.
+    std::map<std::pair<std::uint32_t, std::uint32_t>, std::pair<std::uint64_t, std::uint64_t>> windows{};
+    {
+        std::ifstream in(root + "/preprocessed/" + snapshot + "/meta.json");
+        if (in) {
+            nlohmann::json meta{};
+            in >> meta;
+            for (const auto& trace : meta.value("traces", nlohmann::json::array())) {
+                if (!trace.contains("capture_start_ns") || !trace.contains("capture_end_ns")) {
+                    continue;
+                }
+                windows[{trace.at("input").get<std::uint32_t>(), trace.at("output").get<std::uint32_t>()}] = {
+                    trace.at("capture_start_ns").get<std::uint64_t>(),
+                    trace.at("capture_end_ns").get<std::uint64_t>(),
+                };
+            }
+        }
+    }
+
+    std::uint64_t first = 0U;
+    std::uint64_t last = 0U;
+    for (const auto& [key, window] : windows) {
+        if (first == 0U || window.first < first) {
+            first = window.first;
+        }
+        last = std::max(last, window.second);
+    }
+    if (first == 0U) {
+        // No meta labels: fall back to the `_ns<...>` folder suffix.
+        const auto ns_pos = snapshot.rfind("_ns");
+        if (ns_pos == std::string::npos) {
+            throw std::runtime_error("snapshot has no meta.json and no _ns suffix: " + snapshot);
+        }
+        last = static_cast<std::uint64_t>(std::stoull(snapshot.substr(ns_pos + 3)));
+        first = last;
+    }
+    collection.capture_start_ns = first;
+    collection.capture_end_ns = last;
+    collection.monotonic_ns = (first + last) / 2U;
+
+    for (const auto& combo : run_config.run_combos) {
+        char path[512];
+        std::snprintf(path, sizeof(path), "%s/preprocessed/%s/i%u_o%u_s21.npy",
+                      root.c_str(), snapshot.c_str(), combo.input_pos, combo.output_pos);
+        const auto s21 = load_npy(path);
+        std::snprintf(path, sizeof(path), "%s/preprocessed/%s/i%u_o%u_freq.npy",
+                      root.c_str(), snapshot.c_str(), combo.input_pos, combo.output_pos);
+        const auto freq = load_npy(path);
+
+        radar::ipc::SweepTraceBlock trace{};
+        trace.combo = combo;
+        trace.frequency_hz.assign(freq.f64.begin(), freq.f64.end());
+        trace.s21.reserve(s21.c128.size());
+        for (const auto& sample : s21.c128) {
+            trace.s21.push_back(radar::ipc::Complex32{
+                .re = static_cast<float>(sample.real()),
+                .im = static_cast<float>(sample.imag()),
+            });
+        }
+        trace.s11.resize(trace.s21.size());
+        if (const auto found = windows.find({combo.input_pos, combo.output_pos}); found != windows.end()) {
+            trace.capture_start_ns = found->second.first;
+            trace.capture_end_ns = found->second.second;
+        }
+        collection.traces.push_back(std::move(trace));
+    }
+    return collection;
+}
+
+void print_projection_argmax(
+    const radar::ipc::ResultPayload& payload,
+    const char* col_axis_name,
+    const char* row_axis_name
+) {
+    std::size_t argmax = 0U;
+    float best = -1.0F;
+    for (std::size_t index = 0U; index < payload.image_values.size(); ++index) {
+        if (payload.image_values[index] > best) {
+            best = payload.image_values[index];
+            argmax = index;
+        }
+    }
+    const auto nx = payload.image_x_axis.size();
+    const auto col = argmax % nx;
+    const auto row = argmax / nx;
+    std::printf(
+        "%s: max=%.6f at %s=%.1f cm, %s=%.1f cm\n",
+        payload.processing_name.c_str(),
+        static_cast<double>(best),
+        col_axis_name,
+        static_cast<double>(payload.image_x_axis[col]) * 100.0,
+        row_axis_name,
+        static_cast<double>(payload.image_y_axis[row]) * 100.0
+    );
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    if (argc < 3) {
+        std::printf("usage: %s <dataset_root> <center_snapshot> [--dump-dir <dir>]\n", argv[0]);
+        return 1;
+    }
+    const std::string root = argv[1];
+    const std::string center = argv[2];
+    std::string dump_dir{};
+    for (int index = 3; index + 1 < argc; ++index) {
+        if (std::string{argv[index]} == "--dump-dir") {
+            dump_dir = argv[index + 1];
+        }
+    }
+
+    const std::string preprocessed = root + "/preprocessed";
+    std::vector<std::string> snapshots{};
+    if (DIR* dir = opendir(preprocessed.c_str())) {
+        for (dirent* entry = nullptr; (entry = readdir(dir)) != nullptr;) {
+            const std::string name = entry->d_name;
+            if (!name.empty() && (std::isdigit(name[0]) != 0)) {
+                snapshots.push_back(name);
+            }
+        }
+        closedir(dir);
+    }
+    std::sort(snapshots.begin(), snapshots.end());
+    const auto center_it = std::find(snapshots.begin(), snapshots.end(), center);
+    if (center_it == snapshots.end()) {
+        std::printf("center %s not found in %s\n", center.c_str(), preprocessed.c_str());
+        return 1;
+    }
+    const auto center_index = static_cast<std::size_t>(center_it - snapshots.begin());
+
+    const auto run_config = radar::config::load_run_config(root + "/config_profile.json");
+    if (run_config.gpr.tx_geometry.empty() || run_config.gpr.rx_geometry.empty()) {
+        std::printf("FAIL: config_profile.json has no gpr geometry\n");
+        return 1;
+    }
+
+    auto live = build_live_config(run_config);
+    live.sar3d_volume_dump_dir = dump_dir;
+    const auto radius = static_cast<std::size_t>(live.sar3d_frame_radius);
+    if (center_index < radius || center_index + radius >= snapshots.size()) {
+        std::printf("not enough snapshots around center for radius %zu\n", radius);
+        return 1;
+    }
+
+    // The processor centers the aperture `radius` frames before the newest
+    // collection, so feeding [center-r .. center+r] in order reproduces the
+    // symmetric aperture around `center`.
+    std::vector<radar::ipc::PreprocessedCollection> history{};
+    for (std::size_t index = center_index - radius; index <= center_index + radius; ++index) {
+        history.push_back(load_collection(run_config, root, snapshots[index], index));
+    }
+    std::printf("aperture: %zu frames around %s\n", history.size(), center.c_str());
+
+    radar::processing::Sar3dProcessor processor{};
+    radar::ipc::ResultCollection result{};
+    for (std::size_t index = 0U; index < history.size(); ++index) {
+        result = processor.process_collection(
+            run_config,
+            history[index],
+            std::span<const radar::ipc::PreprocessedCollection>(history.data(), index),
+            live
+        );
+    }
+
+    if (result.collection_payloads.empty()) {
+        std::printf("FAIL: sar3d produced no payloads\n");
+        return 1;
+    }
+    for (const auto& payload : result.collection_payloads) {
+        if (payload.kind == radar::ipc::ResultKind::ScalarF32) {
+            std::printf("%s (volume level): %.9e\n",
+                        payload.processing_name.c_str(), static_cast<double>(payload.scalar_value));
+        }
+    }
+    for (const auto& payload : result.collection_payloads) {
+        if (payload.kind == radar::ipc::ResultKind::ImageF32 && payload.processing_name == "sar3d_proj_xz") {
+            print_projection_argmax(payload, "X", "Z");
+        }
+    }
+
+    // Bottom view across the selectable angles: the target's u coordinate must
+    // move smoothly from its X (front, 0 deg) to its Z (side, 90 deg).
+    const auto last_previous =
+        std::span<const radar::ipc::PreprocessedCollection>(history.data(), history.size() - 1U);
+    for (const float angle_deg : {0.0F, 30.0F, 60.0F, 90.0F}) {
+        auto live_angle = live;
+        live_angle.sar3d_volume_dump_dir.clear();
+        live_angle.sar3d_bottom_view_deg = angle_deg;
+        const auto angle_result =
+            processor.process_collection(run_config, history.back(), last_previous, live_angle);
+        for (const auto& payload : angle_result.collection_payloads) {
+            if (payload.kind == radar::ipc::ResultKind::ImageF32 && payload.processing_name == "sar3d_proj_bottom") {
+                std::printf("bottom @ %2.0f deg -> ", static_cast<double>(angle_deg));
+                print_projection_argmax(payload, "u", "Y");
+            }
+        }
+    }
+    if (!dump_dir.empty()) {
+        std::printf("volume dumped to %s/sar3d_volume_%llu.{f32,json}\n",
+                    dump_dir.c_str(),
+                    static_cast<unsigned long long>(history.back().collection_id));
+    }
+    std::printf("OK: sar3d processor path completed\n");
+    return 0;
+}

device_firmware/cart_firmware/.vscode/extensions.json

@@ -5,6 +5,7 @@
         "platformio.platformio-ide"
     ],
     "unwantedRecommendations": [
-        "ms-vscode.cpptools-extension-pack"
+        "ms-vscode.cpptools-extension-pack",
+        "pioarduino.pioarduino-ide"
     ]
 }

device_firmware/cart_firmware/deploy/README.md

@@ -0,0 +1,53 @@
+# systemd-службы сетевого моста
+
+Автозапуск `tools/bridge.py` как служб: `cart-bridge-tx` (отправитель, рядом с
+пультом) и `cart-bridge-rx` (приёмник, рядом с тележкой). На каждой машине
+включается ровно одна роль.
+
+## Установка
+
+На машине-отправителе:
+
+```sh
+sudo ./install-bridge.sh tx
+```
+
+На машине-приёмнике:
+
+```sh
+sudo ./install-bridge.sh rx
+```
+
+Установщик подставляет в юнит реальные пути (python из `.venv` проекта, если
+есть, иначе системный `python3`; `bridge.py`; рабочий каталог) и пользователя
+(того, кто вызвал `sudo`). Юниты кладутся в `/etc/systemd/system/`, конфиги —
+в `/etc/cart-bridge/{tx,rx}.env` (создаются из примеров, существующие не
+перезаписываются). Без аргумента (`none`) — только установка, без включения.
+
+Интерпретатор можно задать явно: `sudo PYTHON=/usr/bin/python3 ./install-bridge.sh rx`.
+В выбранном python должен быть `pyserial`.
+
+## Настройка
+
+Отредактировать конфиг под свою сеть и ключ:
+
+```sh
+sudoedit /etc/cart-bridge/tx.env   # peer = адрес приёмника, общий ключ
+sudoedit /etc/cart-bridge/rx.env   # bind, тот же ключ
+sudo systemctl restart cart-bridge-tx   # применить
+```
+
+Ключ `CART_BRIDGE_KEY` на обеих сторонах должен совпадать (HMAC-аутентификация
+пакетов; обязателен для интернета).
+
+## Эксплуатация
+
+```sh
+systemctl status cart-bridge-tx
+journalctl -u cart-bridge-tx -f      # логи; на отправителе видно «приёмник отвечает/НЕ отвечает»
+sudo systemctl restart cart-bridge-tx
+sudo systemctl disable --now cart-bridge-tx
+```
+
+Служба перезапускается при падении (`Restart=always`). Доступ к USB-порту STM
+даётся группами `dialout`/`plugdev` (прописаны в юните).

device_firmware/cart_firmware/deploy/cart-bridge-rx.env.example

@@ -0,0 +1,19 @@
+# Конфигурация службы приёмника (cart-bridge-rx). Копируется в
+# /etc/cart-bridge/rx.env установщиком. Переменные читает tools/bridge.py.
+
+# Локальный UDP-адрес для приёма HOST:PORT.
+CART_BRIDGE_BIND=0.0.0.0:5005
+
+# Общий ключ HMAC (ОБЯЗАТЕЛЕН для интернета). Должен совпадать с отправителем.
+CART_BRIDGE_KEY=change-me-shared-secret
+
+# Необязательно: принимать пакеты только с этого адреса отправителя (фильтр по
+# хосту). Для интернета за NAT обычно оставляют пустым и полагаются на HMAC.
+#CART_BRIDGE_PEER=10.0.0.1
+
+# Необязательно: путь к порту или подстрока product/serial. По умолчанию порт
+# ищется по USB product string CART-RX.
+#CART_BRIDGE_DEVICE=CART-RX
+
+# Необязательно: уровень логов (DEBUG/INFO/WARNING).
+#CART_BRIDGE_LOG_LEVEL=INFO

device_firmware/cart_firmware/deploy/cart-bridge-rx.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=Cart bridge receiver (role rx): сеть -> USB тележки
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+User=@USER@
+SupplementaryGroups=dialout plugdev
+EnvironmentFile=/etc/cart-bridge/rx.env
+WorkingDirectory=@WORKDIR@
+ExecStart=@PYTHON@ @BRIDGE@ --role rx
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target

device_firmware/cart_firmware/deploy/cart-bridge-tx.env.example

@@ -0,0 +1,15 @@
+# Конфигурация службы отправителя (cart-bridge-tx). Копируется в
+# /etc/cart-bridge/tx.env установщиком. Переменные читает tools/bridge.py.
+
+# Адрес приёмника HOST:PORT — куда слать управление.
+CART_BRIDGE_PEER=10.0.0.2:5005
+
+# Общий ключ HMAC (ОБЯЗАТЕЛЕН для интернета). Должен совпадать с приёмником.
+CART_BRIDGE_KEY=change-me-shared-secret
+
+# Необязательно: путь к порту или подстрока product/serial. По умолчанию порт
+# ищется по USB product string CART-TX.
+#CART_BRIDGE_DEVICE=CART-TX
+
+# Необязательно: уровень логов (DEBUG/INFO/WARNING).
+#CART_BRIDGE_LOG_LEVEL=INFO

device_firmware/cart_firmware/deploy/cart-bridge-tx.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=Cart bridge sender (role tx): пульт USB -> сеть
+After=network-online.target
+Wants=network-online.target
+# не упираться в лимит перезапусков при флапе сети/USB
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+User=@USER@
+# доступ к последовательному порту STM (dialout) и к USB-дескрипторам (plugdev)
+SupplementaryGroups=dialout plugdev
+EnvironmentFile=/etc/cart-bridge/tx.env
+WorkingDirectory=@WORKDIR@
+ExecStart=@PYTHON@ @BRIDGE@ --role tx
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target

device_firmware/cart_firmware/deploy/install-bridge.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Установка systemd-служб сетевого моста тележки.
+#
+#   sudo ./install-bridge.sh [tx|rx|both|none]
+#
+# Аргумент выбирает, какую службу включить и запустить на ЭТОЙ машине
+# (tx — рядом с пультом, rx — рядом с тележкой). Без аргумента юниты только
+# ставятся, но не включаются. Файлы юнитов и шаблоны конфигов берутся из этого
+# каталога; пути к python и bridge.py подставляются автоматически.
+set -euo pipefail
+
+SELF="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TOOLS="$(cd "$SELF/../tools" && pwd)"
+REPO="$(cd "$SELF/../../.." && pwd)"
+BRIDGE="$TOOLS/bridge.py"
+WORKDIR="$TOOLS"
+ENABLE="${1:-none}"
+
+case "$ENABLE" in tx|rx|both|none) ;; *) echo "аргумент: tx|rx|both|none" >&2; exit 2;; esac
+
+if [ "$(id -u)" -ne 0 ]; then
+    echo "нужны права root — перезапускаюсь через sudo"
+    exec sudo -E PYTHON="${PYTHON:-}" bash "$0" "$ENABLE"
+fi
+
+TARGET_USER="${SUDO_USER:-root}"
+
+# интерпретатор: venv проекта, если есть, иначе системный python3
+PYTHON="${PYTHON:-}"
+if [ -z "$PYTHON" ]; then
+    if [ -x "$REPO/.venv/bin/python" ]; then
+        PYTHON="$REPO/.venv/bin/python"
+    else
+        PYTHON="$(command -v python3)"
+    fi
+fi
+
+echo "python : $PYTHON"
+echo "bridge : $BRIDGE"
+echo "user   : $TARGET_USER"
+
+if ! "$PYTHON" -c 'import serial' 2>/dev/null; then
+    echo "ВНИМАНИЕ: в $PYTHON нет pyserial — поставь: $PYTHON -m pip install pyserial" >&2
+fi
+
+gen_unit() {  # <role>
+    local role="$1"
+    sed -e "s|@PYTHON@|$PYTHON|g" -e "s|@BRIDGE@|$BRIDGE|g" \
+        -e "s|@WORKDIR@|$WORKDIR|g" -e "s|@USER@|$TARGET_USER|g" \
+        "$SELF/cart-bridge-$role.service" > "/etc/systemd/system/cart-bridge-$role.service"
+    echo "установлен юнит /etc/systemd/system/cart-bridge-$role.service"
+}
+
+install -d -m 755 /etc/cart-bridge
+for role in tx rx; do
+    gen_unit "$role"
+    conf="/etc/cart-bridge/$role.env"
+    if [ ! -e "$conf" ]; then
+        install -m 600 "$SELF/cart-bridge-$role.env.example" "$conf"
+        echo "создан конфиг $conf (ОТРЕДАКТИРУЙ: peer/bind и ключ)"
+    else
+        echo "конфиг $conf уже есть — не трогаю"
+    fi
+done
+
+systemctl daemon-reload
+
+enable_one() {  # <role>
+    systemctl enable --now "cart-bridge-$1.service"
+    echo "включена и запущена cart-bridge-$1.service"
+}
+case "$ENABLE" in
+    tx) enable_one tx ;;
+    rx) enable_one rx ;;
+    both) enable_one tx; enable_one rx ;;
+    none) echo "юниты установлены, не включены. Включить: systemctl enable --now cart-bridge-tx (или -rx)";;
+esac
+
+echo "готово. Логи: journalctl -u cart-bridge-tx -f   (или -rx)"

device_firmware/cart_firmware/docs/protocol.md

@@ -55,3 +55,187 @@
 - Отправлять 25-байтовый кадр по таймеру каждые 50 мс.
 - Нейтраль: все каналы 1024; управление — каналы 2 и 4 в измеренных
   диапазонах.
+
+# Сетевой мост «пульт → тележка»
+
+Та же команда управления может идти не по проводу рядом, а через локальную
+сеть/интернет, не ломая прежний проводной режим. Цепочка:
+
+```
+[пульт] ADC→ STM(CART-TX) ─USB─► bridge --role tx ─UDP─► bridge --role rx ─USB─► STM(CART-RX) ─SBUS─► драйвер
+```
+
+STM-TX продолжает гнать SBUS на свой локальный провод как раньше и
+дополнительно отдаёт те же значения каналов по USB. STM-RX принимает их по USB
+и выдаёт на свой провод так, будто сигнал пришёл с пульта.
+
+## Роли и идентификация устройства
+
+Роль выбирается на сборке (`platformio.ini`): `pio run -e cart_tx` или
+`-e cart_rx`. Общий код (`sbus`, `usb_link`) собирается в оба env, специфичный —
+через `build_src_filter`, мёртвого кода неактивной роли нет.
+
+Каждая прошивка публикует USB **product string**: `CART-TX` / `CART-RX`. По ней
+`tools/bridge.py` находит нужный порт (`serial.tools.list_ports`). После открытия
+порта ПК шлёт `HELLO` и ждёт `IDENT` — подтверждение роли, версии протокола и
+96-битного UID чипа (на случай неверно прошитого устройства, рассинхрона версий
+или чужого CDC с тем же VID/PID). Serial-дескриптор (UID) различает экземпляры.
+
+## Прошивка STM
+
+Плата — WeAct STM32G431CB. Нужен PlatformIO Core (`pio`); если не установлен:
+`pip install platformio` (в репозитории он лежит в `~/.platformio/penv/bin/pio`).
+Все команды выполняются из каталога прошивки `device_firmware/cart_firmware`.
+
+Две роли — две отдельные прошивки на две платы. По умолчанию загрузчик — ST-Link
+по SWD (`upload_protocol = stlink` в `platformio.ini`).
+
+**1. Подключить ST-Link к плате по SWD** (4 провода):
+
+| ST-Link | WeAct G431CB |
+|---|---|
+| SWDIO | PA13 (SWDIO) |
+| SWCLK | PA14 (SWCLK) |
+| GND | GND |
+| 3V3 | 3V3 |
+
+**2. Собрать и прошить роль** (прошивать по одной плате за раз, один ST-Link):
+
+```
+# плата-передатчик (к ней подключён пульт)
+pio run -e cart_tx -t upload
+# плата-приёмник (к ней подключён провод драйвера колёс)
+pio run -e cart_rx -t upload
+```
+
+- Только собрать без заливки: `pio run -e cart_tx`. Артефакты —
+  `.pio/build/<env>/firmware.{elf,bin}`.
+- Если подключено несколько ST-Link, указать конкретный:
+  `pio run -e cart_tx -t upload --upload-port <serial-ST-Link>`.
+- Сменить роль платы — просто залить другой env, флеш перезаписывается целиком.
+
+**3. Физические подключения по ролям** (распиновка общая, см. выше по документу):
+
+| | CART-TX | CART-RX |
+|---|---|---|
+| Стик X / Y | PA0 / PA1 (АЦП) | — не используется |
+| Выход SBUS | PA9 → локальный драйвер (как раньше) | PA9 → провод драйвера колёс |
+| USB | → ПК (bridge --role tx) | → ПК (bridge --role rx) |
+
+**4. Проверить роль после прошивки.** Подключить плату по USB к ПК и прочитать
+product string (роль зашита в неё):
+
+```
+python3 -c "from serial.tools import list_ports; \
+[print(p.device, p.product, p.serial_number) for p in list_ports.comports()]"
+# ожидаемо: /dev/ttyACM0 CART-TX <UID> либо CART-RX
+```
+
+Либо просто запустить `tools/bridge.py` соответствующей роли — на старте он
+делает handshake и логирует подтверждённые роль, версию прошивки и UID.
+
+> USB CDC теперь несёт **бинарный** протокол, а не текстовый лог. `pio device
+> monitor` покажет «мусор» — это нормально. Отладочный текст идёт кадрами `LOG`,
+> которые печатает `bridge.py`.
+
+## Кадр поверх USB CDC
+
+Единственный источник истины — `src/link_protocol.h`, зеркало на Python —
+`tools/link_proto.py` (сверка: `python3 tools/link_proto.py --selftest`).
+
+```
+[0xA5][0x5A][VER=1][TYPE][LEN][PAYLOAD..LEN][CRC16_LO][CRC16_HI]
+```
+
+- CRC16-CCITT (poly `0x1021`, init `0xFFFF`) по байтам `[VER..конец PAYLOAD]`, LE.
+  Контрольный вектор: `crc16("123456789") = 0x29B1`.
+- Приёмник (STM и Python) — стейт-машина: ищет синхрослово, читает по `LEN`,
+  проверяет CRC; при сбое сдвиг на байт и ресинхронизация (устойчивость к мусору
+  и потере байта).
+- Типы: `0x01 CONTROL`, `0x02 IDENT`, `0x03 HELLO`, `0x04 LOG`. Отладочный текст
+  идёт только кадром `LOG` — «голых» `Serial.print`, ломающих бинарный поток, нет.
+
+Payload `CONTROL` (LE): `seq:u32`, `t_ms:u32`, `flags:u8`, `ch[16]:u16` = 41 байт.
+`ch[]` — значения SBUS-каналов 0..2047, ровно те, что TX кладёт на свой провод.
+Это общая «валюта» всей цепочки: ПК перекладывает payload в UDP и обратно, RX
+распаковывает и пакует в SBUS. `flags` bit0 = failsafe.
+
+## Сетевой слой (между экземплярами bridge)
+
+- Транспорт — **UDP**: для управления 20 Гц свежий кадр ценнее
+  доставленного; TCP при потере встал бы в head-of-line blocking и копил лаг.
+- Полезная нагрузка UDP — тот же `CONTROL` payload. `seq` даёт отбрасывание
+  устаревших/повторных пакетов (защита от переупорядочивания и дубликатов UDP)
+  с корректной арифметикой переполнения uint32. Перезапуск источника (seq снова
+  с 0) распознаётся по пачке подряд «несвежих» пакетов и трактуется как новая
+  сессия — иначе поток завис бы в failsafe навсегда. Это best-effort защита от
+  повтора старых команд, не криптографическая: аутентичность даёт HMAC, против
+  целевого replay на недоверенной сети используй WireGuard.
+- Приём из сети и выдача SBUS на провод — **разные таймеры**: джиттер сети не
+  попадает на провод, STM-RX гонит SBUS строго каждые 50 мс из последнего
+  состояния.
+- **Безопасность.** Для интернета обязателен общий ключ (`--key`): каждый UDP-
+  пакет аутентифицируется усечённым HMAC-SHA256 (8 байт), RX отбрасывает
+  неаутентичные и принимает только с ожидаемого адреса (`--peer`). Рекомендуемый
+  способ наружу — WireGuard-туннель, внутри которого идёт простой UDP. «Голый»
+  неаутентифицированный UDP допустим только в доверенной локальной сети.
+- **Обратный heartbeat.** RX шлёт на адрес источника последнего CONTROL
+  маленький служебный пакет (~5 раз/с): magic `CB 01`, флаг собственного
+  failsafe, последний принятый seq; при включённом ключе — тоже под HMAC. TX
+  принимает их на тот же сокет (сквозь NAT проходит, т.к. он сам инициировал
+  поток) и показывает в логе, **отвечает ли приёмник** и не ушёл ли тот в
+  failsafe. Это чисто служебный PC-трафик, STM в нём не участвует, поэтому он не
+  в зеркале протокола, а в самом `bridge.py`. На выдачу SBUS и на основной поток
+  управления heartbeat не влияет.
+  - **Индикация для оператора.** Если запустить tx в терминале, он показывает одну
+    живую строку, обновляемую на месте: зелёное `● СВЯЗЬ ЕСТЬ`, жёлтое
+    `● СВЯЗЬ ЕСТЬ (приёмник в failsafe)` или красное `● СВЯЗИ НЕТ`. Под systemd
+    (вывод не в терминал) вместо строки идут события в журнал по смене состояния.
+
+## FAILSAFE
+
+Потеря связи никогда не оставляет тележку на последней команде — выход всегда
+нейтраль (все каналы 1024), а не удержание.
+
+- **Главный предохранитель — на самом STM-RX.** Если валидный `CONTROL` по USB
+  не приходил дольше `RX_USB_TIMEOUT_MS = 150` мс (3 кадра), STM-RX сам выдаёт на
+  провод нейтраль с флагом failsafe (SBUS bit3). Срабатывает при обрыве USB,
+  зависании или падении ПК-процесса. SBUS на провод идёт непрерывно 20 Гц в любом
+  случае — драйвер не видит пропажи сигнала.
+- **Сетевой failsafe на ПК-RX.** При тишине из сети дольше 100 мс bridge активно
+  шлёт на STM-RX нейтральные `CONTROL` с флагом `CTRL_FLAG_FAILSAFE` в темпе
+  20 Гц, чтобы причина была явной. STM-RX транслирует этот флаг в бит failsafe
+  SBUS-кадра (byte 23 bit3). Восстановление — по первому свежему валидному пакету.
+
+## Запуск
+
+```
+# сторона пульта
+.venv/bin/python tools/bridge.py --role tx --peer 10.0.0.2:5005 --key SECRET
+# сторона тележки
+.venv/bin/python tools/bridge.py --role rx --bind 0.0.0.0:5005 --peer 10.0.0.1 --key SECRET
+```
+
+Локальная проверка без сети: оба экземпляра на одной машине с `--peer 127.0.0.1`
+и двумя STM по USB; SBUS с RX снять `tools/decode.py` и сверить с осями стика TX.
+
+Параметры можно задавать через env (`CART_BRIDGE_ROLE/PEER/BIND/DEVICE/KEY/
+LOG_LEVEL`), CLI их переопределяет.
+
+## Автозапуск: systemd-службы
+
+Для постоянной работы мост ставится службами: `cart-bridge-tx` (отправитель) и
+`cart-bridge-rx` (приёмник), по одной роли на машину. Юниты, примеры конфигов и
+установщик — в каталоге `deploy/`:
+
+```sh
+cd deploy
+sudo ./install-bridge.sh tx   # на машине у пульта
+sudo ./install-bridge.sh rx   # на машине у тележки
+```
+
+Установщик подставляет реальные пути (python из `.venv`, `bridge.py`, рабочий
+каталог) и пользователя, кладёт конфиги в `/etc/cart-bridge/{tx,rx}.env`. Там
+задаются `CART_BRIDGE_PEER`/`BIND` и общий `CART_BRIDGE_KEY` (должен совпадать на
+обеих сторонах). Логи и индикация «отвечает ли приёмник» — `journalctl -u
+cart-bridge-tx -f`. Подробности — `deploy/README.md`.

device_firmware/cart_firmware/platformio.ini

@@ -1,4 +1,11 @@
-[env:weact_g431cb]
+; Две роли одной прошивки тележки, выбираются на этапе сборки:
+;   pio run -e cart_tx   — пульт -> локальный SBUS + отправка по USB на ПК
+;   pio run -e cart_rx   — приём по USB с ПК -> SBUS на драйвер колёс
+; Роль публикуется в USB product string (CART-TX / CART-RX), по которой ПК-сервер
+; (tools/bridge.py) находит нужный порт. Общий код (sbus, usb_link) собирается в
+; оба env; специфичный — через build_src_filter, без мёртвого кода неактивной роли.
+
+[env]
 platform = ststm32
 board = genericSTM32G431CB
 framework = arduino
@@ -8,3 +15,18 @@ monitor_speed = 115200
 build_flags =
     -DUSBCON
     -DUSBD_USE_CDC
+build_src_filter = -<*> +<sbus.cpp> +<usb_link.cpp>
+
+[env:cart_tx]
+build_flags =
+    ${env.build_flags}
+    -DCART_ROLE_TX
+    -DUSB_PRODUCT_STRING="\"CART-TX\""
+build_src_filter = ${env.build_src_filter} +<stick.cpp> +<app_tx.cpp>
+
+[env:cart_rx]
+build_flags =
+    ${env.build_flags}
+    -DCART_ROLE_RX
+    -DUSB_PRODUCT_STRING="\"CART-RX\""
+build_src_filter = ${env.build_src_filter} +<app_rx.cpp>

device_firmware/cart_firmware/src/app_rx.cpp

@@ -0,0 +1,70 @@
+// Роль RX: принимает CONTROL по USB от ПК и гонит SBUS на провод драйвера так
+// же, как если бы сигнал шёл с пульта. SBUS отправляется строго каждые 50 мс
+// из последнего известного состояния — джиттер сети/USB не попадает на провод.
+// FAILSAFE: если валидный CONTROL не приходил дольше RX_USB_TIMEOUT_MS, провод
+// получает нейтраль (все каналы 1024) с флагом failsafe. Главный предохранитель
+// живёт на самом STM и срабатывает даже при зависшем ПК или оборванном USB.
+#ifdef CART_ROLE_RX
+#include <Arduino.h>
+#include "sbus.h"
+#include "usb_link.h"
+#include "device_id.h"
+
+static uint16_t s_ch[16];      // последнее принятое состояние каналов
+static uint8_t s_ctrlFlags = 0; // флаги последнего CONTROL (CTRL_FLAG_*)
+static bool s_haveData = false;
+static uint32_t s_lastGoodMs = 0;
+
+static void replyIdent() {
+    LinkIdent id;
+    id.role = ROLE_RX;
+    id.proto_ver = LINK_VERSION;
+    id.fw_ver = CART_FW_VERSION;
+    cartReadUid(id.uid);
+    usbSendIdent(&id);
+}
+
+void setup() {
+    usbLinkInit();
+    sbusUartInit();
+    sbusNeutral(s_ch);
+}
+
+void loop() {
+    // приём кадров из USB
+    LinkRxEvent ev;
+    do {
+        usbLinkPoll(&ev);
+        if (ev.type == LINK_HELLO) {
+            replyIdent();
+        } else if (ev.type == LINK_CONTROL) {
+            memcpy(s_ch, ev.control.ch, sizeof(s_ch));
+            s_ctrlFlags = ev.control.flags;
+            s_lastGoodMs = millis();
+            s_haveData = true;
+        }
+    } while (ev.type != 0);
+
+    // выдача SBUS на провод строго по таймеру
+    static uint32_t next = 0;
+    uint32_t now = millis();
+    if (now < next)
+        return;
+    next = now + FRAME_PERIOD_MS;
+
+    bool stale = !s_haveData || (now - s_lastGoodMs > RX_USB_TIMEOUT_MS);
+
+    uint8_t frame[25];
+    if (stale) {
+        // нет свежих данных по USB -> нейтраль + явный failsafe на провод
+        uint16_t neutral[16];
+        sbusNeutral(neutral);
+        sbusPack(frame, neutral, SBUS_FLAG_FAILSAFE | SBUS_FLAG_FRAME_LOST);
+    } else {
+        // транслируем сетевой failsafe (CTRL_FLAG_FAILSAFE от ПК) в бит SBUS
+        uint8_t flags = (s_ctrlFlags & CTRL_FLAG_FAILSAFE) ? SBUS_FLAG_FAILSAFE : 0;
+        sbusPack(frame, s_ch, flags);
+    }
+    sbusSendFrame(frame);
+}
+#endif // CART_ROLE_RX

device_firmware/cart_firmware/src/app_tx.cpp

@@ -0,0 +1,59 @@
+// Роль TX: к STM подключён пульт. Как и раньше, формирует SBUS на локальный
+// провод (старый функционал не изменён), и ДОПОЛНИТЕЛЬНО шлёт те же значения
+// каналов по USB на ПК кадром CONTROL. Отвечает на HELLO кадром IDENT.
+#ifdef CART_ROLE_TX
+#include <Arduino.h>
+#include "sbus.h"
+#include "stick.h"
+#include "usb_link.h"
+#include "device_id.h"
+
+static void replyIdent() {
+    LinkIdent id;
+    id.role = ROLE_TX;
+    id.proto_ver = LINK_VERSION;
+    id.fw_ver = CART_FW_VERSION;
+    cartReadUid(id.uid);
+    usbSendIdent(&id);
+}
+
+void setup() {
+    usbLinkInit();
+    stickInit();
+    sbusUartInit();
+}
+
+void loop() {
+    // обслуживаем входящие кадры (ждём только HELLO от ПК)
+    LinkRxEvent ev;
+    do {
+        usbLinkPoll(&ev);
+        if (ev.type == LINK_HELLO)
+            replyIdent();
+    } while (ev.type != 0);
+
+    static uint32_t next = 0;
+    static uint32_t seq = 0;
+    uint32_t now = millis();
+    if (now < next)
+        return;
+    next = now + FRAME_PERIOD_MS;
+
+    uint16_t ch[16];
+    float fwd, right;
+    stickComputeChannels(ch, &fwd, &right);
+
+    // 1) локальный провод к драйверу — как раньше
+    uint8_t frame[25];
+    sbusPack(frame, ch);
+    sbusSendFrame(frame);
+
+    // 2) те же каналы по USB на ПК
+    LinkControl c;
+    c.seq = seq++;
+    c.t_ms = now;
+    c.flags = 0;
+    memcpy(c.ch, ch, sizeof(c.ch));
+    usbSendControl(&c);
+}
+#endif // CART_ROLE_TX

device_firmware/cart_firmware/src/device_id.h

@@ -0,0 +1,9 @@
+// 96-битный уникальный идентификатор чипа STM32G431 (UID base 0x1FFF7590).
+// Используется в IDENT, чтобы ПК отличал конкретные экземпляры устройств.
+#pragma once
+#include <stdint.h>
+#include <string.h>
+
+static inline void cartReadUid(uint8_t uid[12]) {
+    memcpy(uid, (const void *)0x1FFF7590UL, 12);
+}

device_firmware/cart_firmware/src/link_protocol.h

@@ -0,0 +1,59 @@
+// Единый источник истины для бинарного протокола связи пульт<->ПК<->тележка.
+// Эти же числа зеркалятся в tools/link_proto.py — при любой правке меняй ОБА
+// файла и сверяйся тест-векторами (tools/link_proto.py --selftest).
+//
+// Кадр поверх потока (USB CDC и полезная нагрузка UDP используют общий payload):
+//   [SYNC0][SYNC1][VER][TYPE][LEN][PAYLOAD..LEN][CRC16_LO][CRC16_HI]
+//   CRC16-CCITT (poly 0x1021, init 0xFFFF) по байтам [VER..конец PAYLOAD], LE.
+#pragma once
+#include <stdint.h>
+
+// --- кадрирование ---
+static const uint8_t LINK_SYNC0 = 0xA5;
+static const uint8_t LINK_SYNC1 = 0x5A;
+static const uint8_t LINK_VERSION = 1;   // версия протокола, проверяется в handshake
+static const uint8_t LINK_MAX_PAYLOAD = 64;
+
+// --- типы кадров ---
+enum LinkType : uint8_t {
+    LINK_HELLO   = 0x03, // ПК -> STM: запрос идентификации (payload пуст)
+    LINK_IDENT   = 0x02, // STM -> ПК: ответ на HELLO (LinkIdent)
+    LINK_CONTROL = 0x01, // поток управления в обе стороны (LinkControl)
+    LINK_LOG     = 0x04, // STM -> ПК: отладочный ASCII-текст (вместо голого Serial)
+};
+
+// --- роли устройства (совпадают с продуктовой строкой USB) ---
+enum LinkRole : uint8_t {
+    ROLE_TX = 'T', // к STM подключён пульт
+    ROLE_RX = 'R', // STM гонит SBUS на драйвер колёс
+};
+
+// --- флаги в LinkControl.flags ---
+static const uint8_t CTRL_FLAG_FAILSAFE = 0x01; // источник объявил безопасный стоп
+
+// Полезная нагрузка CONTROL (LE на проводе). Это общая «валюта» всей цепочки:
+// TX кладёт сюда ровно те ch[], что уходят на его локальный провод, ПК
+// перекладывает payload в UDP и обратно, RX распаковывает и пакует в SBUS.
+// Пакуется/распаковывается вручную (без struct-паддинга) в link_pack.*.
+struct LinkControl {
+    uint32_t seq;      // монотонный счётчик кадров источника
+    uint32_t t_ms;     // millis() на источнике (оценка задержки/джиттера)
+    uint8_t  flags;    // CTRL_FLAG_*
+    uint16_t ch[16];   // значения SBUS-каналов 0..2047
+};
+static const uint8_t LINK_CONTROL_LEN = 4 + 4 + 1 + 2 * 16; // 41 байт
+
+// Полезная нагрузка IDENT.
+struct LinkIdent {
+    uint8_t  role;       // LinkRole
+    uint8_t  proto_ver;  // LINK_VERSION на устройстве
+    uint16_t fw_ver;     // версия прошивки
+    uint8_t  uid[12];    // 96-битный UID чипа
+};
+static const uint8_t LINK_IDENT_LEN = 1 + 1 + 2 + 12; // 16 байт
+
+static const uint16_t CART_FW_VERSION = 0x0100; // 1.00
+
+// --- тайминги (мс) ---
+static const uint32_t FRAME_PERIOD_MS = 50;      // 20 Гц, темп старого пульта
+static const uint32_t RX_USB_TIMEOUT_MS = 450;   // нет CONTROL дольше -> нейтраль на проводе

device_firmware/cart_firmware/src/main.cpp

@@ -1,166 +0,0 @@
-// Пульт тележки: стик (АЦП PA0/PA1) -> SBUS на USART1 TX (PA9).
-// Протокол: инвертированный SBUS, 100000 бод 8E2, 25 байт каждые 50 мс
-// (см. docs/protocol.md). USB CDC (Serial) — отладочный вывод.
-#include <Arduino.h>
-
-// ---- калибровка стика (АЦП 12 бит, замерено 2026-08-20) ----
-static const int X_FWD = 650, X_MID = 2014, X_BACK = 3378;   // PA0 (плечи равны: 2014-650 = 3378-2014 = 1364)
-static const int Y_RIGHT = 479, Y_MID = 1981, Y_LEFT = 3586; // PA1
-static const int DEADZONE = 15; // отсечка дребезга вокруг нейтрали
-
-// ---- SBUS-значения старого пульта ----
-static const uint16_t SBUS_MID = 1024;
-static const uint16_t CH2_MIN = 433, CH2_MAX = 1643;  // назад..вперёд
-static const uint16_t CH4_MIN = 446, CH4_MAX = 1654;  // влево..вправо
-
-// ---- expo: 0 = линейно, 1 = максимально мягкая нейтраль ----
-static const float EXPO_K = 0.0f;
-// ---- общий масштаб выхода: 1.0 = диапазон старого пульта ----
-static const float RANGE_SCALE = 0.75f;
-
-// симметричные плечи: вперёд и назад дают одинаковый максимум
-static const uint16_t CH2_SPAN = 591; // min(1643-1024, 1024-433)
-static const uint16_t CH4_SPAN = 578; // min(1654-1024, 1024-446)
-
-// ---- профиль газа/поворота ----
-static const float MOVE_START = 0.15f; // старт движения, доля хода стика
-static const float POWER_FWD  = 0.60f; // потолок «вперёд»
-static const float POWER_BACK = 0.50f; // потолок «назад»
-static const float POWER_TURN = 0.70f; // потолок поворота
-static const uint16_t CH2_DB = 221;    // мёртвая зона приёмника тележки (ЗАМЕРИТЬ по монитору)
-static const uint16_t CH4_DB = 221;
-
-static const uint32_t FRAME_PERIOD_MS = 50;
-static const uint32_t PIN_X = PA0;
-static const uint32_t PIN_Y = PA1;
-
-static UART_HandleTypeDef s_sbusUart;
-
-// USART1 TX = PA9 (AF7), 100000 бод, 8E2, TX инвертирован
-static void sbusUartInit() {
-    __HAL_RCC_GPIOA_CLK_ENABLE();
-    __HAL_RCC_USART1_CLK_ENABLE();
-
-    GPIO_InitTypeDef gpio = {};
-    gpio.Pin = GPIO_PIN_9;
-    gpio.Mode = GPIO_MODE_AF_PP;
-    gpio.Pull = GPIO_NOPULL;
-    gpio.Speed = GPIO_SPEED_FREQ_LOW;
-    gpio.Alternate = GPIO_AF7_USART1;
-    HAL_GPIO_Init(GPIOA, &gpio);
-
-    s_sbusUart.Instance = USART1;
-    s_sbusUart.Init.BaudRate = 100000;
-    s_sbusUart.Init.WordLength = UART_WORDLENGTH_9B; // 8 данных + чётность
-    s_sbusUart.Init.StopBits = UART_STOPBITS_2;
-    s_sbusUart.Init.Parity = UART_PARITY_EVEN;
-    s_sbusUart.Init.Mode = UART_MODE_TX;
-    s_sbusUart.Init.HwFlowCtl = UART_HWCONTROL_NONE;
-    s_sbusUart.Init.OverSampling = UART_OVERSAMPLING_16;
-    s_sbusUart.AdvancedInit.AdvFeatureInit = UART_ADVFEATURE_TXINVERT_INIT;
-    s_sbusUart.AdvancedInit.TxPinLevelInvert = UART_ADVFEATURE_TXINV_ENABLE;
-    HAL_UART_Init(&s_sbusUart);
-}
-
-// нормализация одной оси в [-1..1] с мёртвой зоной и асимметричными плечами
-static float axisNorm(int adc, int lowEnd, int mid, int highEnd) {
-    float x;
-    if (adc < mid - DEADZONE) {
-        x = (float)(mid - adc) / (float)(mid - lowEnd); // к lowEnd -> +1
-    } else if (adc > mid + DEADZONE) {
-        x = -(float)(adc - mid) / (float)(highEnd - mid); // к highEnd -> -1
-    } else {
-        return 0.0f;
-    }
-    return constrain(x, -1.0f, 1.0f);
-}
-
-// expo-кривая: гасит чувствительность у нейтрали, сохраняет края
-static float expo(float x) {
-    return EXPO_K * x * x * x + (1.0f - EXPO_K) * x;
-}
-
-static uint16_t toSbus(float x, uint16_t span) {
-    return (uint16_t)(SBUS_MID + lroundf(x * span));
-}
-
-// стик [-1..1] -> SBUS-значение канала: ниже MOVE_START — нейтраль, выше —
-// линейно от порога срабатывания приёмника (db) до POWER_FRAC*span на полном стике
-static uint16_t driveToSbus(float x, uint16_t span, uint16_t db,
-                            float powerPos, float powerNeg) {
-    float mag = fabsf(x);
-    if (mag <= MOVE_START)
-        return SBUS_MID;
-    float outMax = (x > 0.0f ? powerPos : powerNeg) * span;
-    float t = (mag - MOVE_START) / (1.0f - MOVE_START);
-    long delta = lroundf(db + t * (outMax - db));
-    return (x > 0.0f) ? (uint16_t)(SBUS_MID + delta)
-                      : (uint16_t)(SBUS_MID - delta);
-}
-
-static void sbusPack(uint8_t out[25], const uint16_t ch[16]) {
-    out[0] = 0x0F;
-    memset(out + 1, 0, 22);
-    uint32_t bitpos = 0;
-    for (int n = 0; n < 16; n++) {
-        for (int b = 0; b < 11; b++) {
-            if (ch[n] & (1u << b))
-                out[1 + (bitpos >> 3)] |= 1u << (bitpos & 7);
-            bitpos++;
-        }
-    }
-    out[23] = 0x00; // флаги
-    out[24] = 0x00; // футер
-}
-
-static int readAvg(uint32_t pin) {
-    uint32_t acc = 0;
-    for (int i = 0; i < 16; i++)
-        acc += analogRead(pin);
-    return acc / 16;
-}
-
-void setup() {
-    Serial.begin(115200);
-    analogReadResolution(12);
-    pinMode(PIN_X, INPUT_ANALOG);
-    pinMode(PIN_Y, INPUT_ANALOG);
-    sbusUartInit();
-}
-
-void loop() {
-    static uint32_t next = 0;
-    uint32_t now = millis();
-    if (now < next)
-        return;
-    next = now + FRAME_PERIOD_MS;
-
-    int adcX = readAvg(PIN_X);
-    int adcY = readAvg(PIN_Y);
-    // вперёд = adcX к X_FWD (вниз) -> +1; вправо = adcY к Y_RIGHT -> +1
-    float fwd = axisNorm(adcX, X_FWD, X_MID, X_BACK);
-    float right = axisNorm(adcY, Y_RIGHT, Y_MID, Y_LEFT);
-
-    uint16_t ch[16];
-    for (int i = 0; i < 16; i++)
-        ch[i] = SBUS_MID;
-    ch[1] = driveToSbus(fwd, CH2_SPAN, CH2_DB, POWER_FWD, POWER_BACK);  // канал 2 — газ
-    ch[3] = driveToSbus(right, CH4_SPAN, CH4_DB, POWER_TURN, POWER_TURN); // канал 4 — поворот
-
-    uint8_t frame[25];
-    sbusPack(frame, ch);
-    HAL_UART_Transmit(&s_sbusUart, frame, sizeof(frame), 20);
-
-    Serial.print("adc=");
-    Serial.print(adcX);
-    Serial.print(",");
-    Serial.print(adcY);
-    Serial.print(" fwd=");
-    Serial.print(fwd, 3);
-    Serial.print(" right=");
-    Serial.print(right, 3);
-    Serial.print(" ch2=");
-    Serial.print(ch[1]);
-    Serial.print(" ch4=");
-    Serial.println(ch[3]);
-}

device_firmware/cart_firmware/src/sbus.cpp

@@ -0,0 +1,55 @@
+#include "sbus.h"
+#include <Arduino.h>
+#include <string.h>
+
+static UART_HandleTypeDef s_sbusUart;
+
+void sbusNeutral(uint16_t ch[16]) {
+    for (int i = 0; i < 16; i++)
+        ch[i] = SBUS_MID;
+}
+
+void sbusPack(uint8_t out[25], const uint16_t ch[16], uint8_t flags) {
+    out[0] = 0x0F;
+    memset(out + 1, 0, 22);
+    uint32_t bitpos = 0;
+    for (int n = 0; n < 16; n++) {
+        for (int b = 0; b < 11; b++) {
+            if (ch[n] & (1u << b))
+                out[1 + (bitpos >> 3)] |= 1u << (bitpos & 7);
+            bitpos++;
+        }
+    }
+    out[23] = flags; // флаги: bit2=frame_lost, bit3=failsafe
+    out[24] = 0x00;  // футер
+}
+
+// USART1 TX = PA9 (AF7), 100000 бод, 8E2, TX инвертирован
+void sbusUartInit() {
+    __HAL_RCC_GPIOA_CLK_ENABLE();
+    __HAL_RCC_USART1_CLK_ENABLE();
+
+    GPIO_InitTypeDef gpio = {};
+    gpio.Pin = GPIO_PIN_9;
+    gpio.Mode = GPIO_MODE_AF_PP;
+    gpio.Pull = GPIO_NOPULL;
+    gpio.Speed = GPIO_SPEED_FREQ_LOW;
+    gpio.Alternate = GPIO_AF7_USART1;
+    HAL_GPIO_Init(GPIOA, &gpio);
+
+    s_sbusUart.Instance = USART1;
+    s_sbusUart.Init.BaudRate = 100000;
+    s_sbusUart.Init.WordLength = UART_WORDLENGTH_9B; // 8 данных + чётность
+    s_sbusUart.Init.StopBits = UART_STOPBITS_2;
+    s_sbusUart.Init.Parity = UART_PARITY_EVEN;
+    s_sbusUart.Init.Mode = UART_MODE_TX;
+    s_sbusUart.Init.HwFlowCtl = UART_HWCONTROL_NONE;
+    s_sbusUart.Init.OverSampling = UART_OVERSAMPLING_16;
+    s_sbusUart.AdvancedInit.AdvFeatureInit = UART_ADVFEATURE_TXINVERT_INIT;
+    s_sbusUart.AdvancedInit.TxPinLevelInvert = UART_ADVFEATURE_TXINV_ENABLE;
+    HAL_UART_Init(&s_sbusUart);
+}
+
+void sbusSendFrame(const uint8_t frame[25]) {
+    HAL_UART_Transmit(&s_sbusUart, (uint8_t *)frame, 25, 20);
+}

device_firmware/cart_firmware/src/sbus.h

@@ -0,0 +1,25 @@
+// Общий SBUS-слой: упаковка кадра и вывод инвертированного SBUS на провод
+// (USART1 TX = PA9, 100000 бод, 8E2, TXINV). Единственный владелец всего, что
+// идёт на драйвер колёс — используется и TX (локальный провод), и RX.
+// См. docs/protocol.md.
+#pragma once
+#include <stdint.h>
+
+static const uint16_t SBUS_MID = 1024; // нейтраль всех каналов
+
+// Флаги в байте 23 SBUS-кадра (см. docs/protocol.md).
+static const uint8_t SBUS_FLAG_FRAME_LOST = 0x04; // bit2
+static const uint8_t SBUS_FLAG_FAILSAFE   = 0x08; // bit3
+
+// Заполнить ch[16] нейтралью (все каналы 1024).
+void sbusNeutral(uint16_t ch[16]);
+
+// Упаковать 16 каналов (0..2047) в стандартный 25-байтовый SBUS-кадр.
+// flags идёт в байт 23 (bit2=frame_lost, bit3=failsafe).
+void sbusPack(uint8_t out[25], const uint16_t ch[16], uint8_t flags = 0);
+
+// Инициализация USART1 для вывода инвертированного SBUS.
+void sbusUartInit();
+
+// Передать готовый 25-байтовый кадр на провод (блокирующе, таймаут 20 мс).
+void sbusSendFrame(const uint8_t frame[25]);

device_firmware/cart_firmware/src/stick.cpp

@@ -0,0 +1,80 @@
+#include "stick.h"
+#include "sbus.h"
+#include <Arduino.h>
+
+// ---- калибровка стика (АЦП 12 бит, замерено 2026-08-20) ----
+static const int X_FWD = 650, X_MID = 2014, X_BACK = 3378;   // PA0 (плечи равны: 2014-650 = 3378-2014 = 1364)
+static const int Y_RIGHT = 479, Y_MID = 1981, Y_LEFT = 3586; // PA1
+static const int DEADZONE = 15; // отсечка дребезга вокруг нейтрали
+
+// симметричные плечи: вперёд и назад дают одинаковый максимум
+static const uint16_t CH2_SPAN = 591; // min(1643-1024, 1024-433)
+static const uint16_t CH4_SPAN = 578; // min(1654-1024, 1024-446)
+
+// ---- профиль газа/поворота ----
+static const float MOVE_START = 0.15f; // старт движения, доля хода стика
+static const float POWER_FWD  = 0.60f; // потолок «вперёд»
+static const float POWER_BACK = 0.50f; // потолок «назад»
+static const float POWER_TURN = 0.70f; // потолок поворота
+static const uint16_t CH2_DB = 221;    // мёртвая зона приёмника тележки
+static const uint16_t CH4_DB = 221;
+
+static const uint32_t PIN_X = PA0;
+static const uint32_t PIN_Y = PA1;
+
+// нормализация одной оси в [-1..1] с мёртвой зоной и асимметричными плечами
+static float axisNorm(int adc, int lowEnd, int mid, int highEnd) {
+    float x;
+    if (adc < mid - DEADZONE) {
+        x = (float)(mid - adc) / (float)(mid - lowEnd); // к lowEnd -> +1
+    } else if (adc > mid + DEADZONE) {
+        x = -(float)(adc - mid) / (float)(highEnd - mid); // к highEnd -> -1
+    } else {
+        return 0.0f;
+    }
+    return constrain(x, -1.0f, 1.0f);
+}
+
+// стик [-1..1] -> SBUS-значение канала: ниже MOVE_START — нейтраль, выше —
+// линейно от порога срабатывания приёмника (db) до POWER_FRAC*span на полном стике
+static uint16_t driveToSbus(float x, uint16_t span, uint16_t db,
+                            float powerPos, float powerNeg) {
+    float mag = fabsf(x);
+    if (mag <= MOVE_START)
+        return SBUS_MID;
+    float outMax = (x > 0.0f ? powerPos : powerNeg) * span;
+    float t = (mag - MOVE_START) / (1.0f - MOVE_START);
+    long delta = lroundf(db + t * (outMax - db));
+    return (x > 0.0f) ? (uint16_t)(SBUS_MID + delta)
+                      : (uint16_t)(SBUS_MID - delta);
+}
+
+static int readAvg(uint32_t pin) {
+    uint32_t acc = 0;
+    for (int i = 0; i < 16; i++)
+        acc += analogRead(pin);
+    return acc / 16;
+}
+
+void stickInit() {
+    analogReadResolution(12);
+    pinMode(PIN_X, INPUT_ANALOG);
+    pinMode(PIN_Y, INPUT_ANALOG);
+}
+
+void stickComputeChannels(uint16_t ch[16], float *fwdOut, float *rightOut) {
+    int adcX = readAvg(PIN_X);
+    int adcY = readAvg(PIN_Y);
+    // вперёд = adcX к X_FWD (вниз) -> +1; вправо = adcY к Y_RIGHT -> +1
+    float fwd = axisNorm(adcX, X_FWD, X_MID, X_BACK);
+    float right = axisNorm(adcY, Y_RIGHT, Y_MID, Y_LEFT);
+
+    sbusNeutral(ch);
+    ch[1] = driveToSbus(fwd, CH2_SPAN, CH2_DB, POWER_FWD, POWER_BACK);    // канал 2 — газ
+    ch[3] = driveToSbus(right, CH4_SPAN, CH4_DB, POWER_TURN, POWER_TURN); // канал 4 — поворот
+
+    if (fwdOut)
+        *fwdOut = fwd;
+    if (rightOut)
+        *rightOut = right;
+}

device_firmware/cart_firmware/src/stick.h

@@ -0,0 +1,12 @@
+// Пульт: чтение стика (АЦП PA0/PA1), калибровка, профиль газа/поворота и
+// формирование значений SBUS-каналов. Вся «логика пульта» живёт здесь.
+// Компилируется только для роли TX (см. build_src_filter в platformio.ini).
+#pragma once
+#include <stdint.h>
+
+// Инициализация АЦП-входов стика.
+void stickInit();
+
+// Прочитать стик и заполнить ch[16] значениями SBUS-каналов (нейтраль + ch2/ch4).
+// Возвращает по ссылкам нормализованные оси для отладки.
+void stickComputeChannels(uint16_t ch[16], float *fwdOut, float *rightOut);

device_firmware/cart_firmware/src/usb_link.cpp

@@ -0,0 +1,148 @@
+#include "usb_link.h"
+#include <Arduino.h>
+#include <string.h>
+
+uint16_t linkCrc16(const uint8_t *data, uint16_t len) {
+    uint16_t crc = 0xFFFF;
+    for (uint16_t i = 0; i < len; i++) {
+        crc ^= (uint16_t)data[i] << 8;
+        for (int b = 0; b < 8; b++)
+            crc = (crc & 0x8000) ? (uint16_t)((crc << 1) ^ 0x1021) : (uint16_t)(crc << 1);
+    }
+    return crc;
+}
+
+// ---- сериализация payload (little-endian, без struct-паддинга) ----
+static void put_u16(uint8_t *p, uint16_t v) { p[0] = v & 0xFF; p[1] = v >> 8; }
+static void put_u32(uint8_t *p, uint32_t v) {
+    p[0] = v & 0xFF; p[1] = (v >> 8) & 0xFF; p[2] = (v >> 16) & 0xFF; p[3] = (v >> 24) & 0xFF;
+}
+static uint16_t get_u16(const uint8_t *p) { return (uint16_t)p[0] | ((uint16_t)p[1] << 8); }
+static uint32_t get_u32(const uint8_t *p) {
+    return (uint32_t)p[0] | ((uint32_t)p[1] << 8) | ((uint32_t)p[2] << 16) | ((uint32_t)p[3] << 24);
+}
+
+static uint8_t packControl(const LinkControl *c, uint8_t *out) {
+    put_u32(out + 0, c->seq);
+    put_u32(out + 4, c->t_ms);
+    out[8] = c->flags;
+    for (int i = 0; i < 16; i++)
+        put_u16(out + 9 + 2 * i, c->ch[i]);
+    return LINK_CONTROL_LEN;
+}
+static void unpackControl(const uint8_t *in, LinkControl *c) {
+    c->seq = get_u32(in + 0);
+    c->t_ms = get_u32(in + 4);
+    c->flags = in[8];
+    for (int i = 0; i < 16; i++)
+        c->ch[i] = get_u16(in + 9 + 2 * i);
+}
+
+// ---- отправка кадра ----
+static void sendFrame(uint8_t type, const uint8_t *payload, uint8_t len) {
+    uint8_t buf[3 + LINK_MAX_PAYLOAD + 2];
+    buf[0] = LINK_VERSION;
+    buf[1] = type;
+    buf[2] = len;
+    if (len)
+        memcpy(buf + 3, payload, len);
+    uint16_t crc = linkCrc16(buf, 3 + len);
+    uint8_t hdr[2] = {LINK_SYNC0, LINK_SYNC1};
+    Serial.write(hdr, 2);
+    Serial.write(buf, 3 + len);
+    uint8_t crcb[2] = {(uint8_t)(crc & 0xFF), (uint8_t)(crc >> 8)};
+    Serial.write(crcb, 2);
+}
+
+void usbSendControl(const LinkControl *c) {
+    uint8_t pl[LINK_CONTROL_LEN];
+    uint8_t n = packControl(c, pl);
+    sendFrame(LINK_CONTROL, pl, n);
+}
+
+void usbSendIdent(const LinkIdent *id) {
+    uint8_t pl[LINK_IDENT_LEN];
+    pl[0] = id->role;
+    pl[1] = id->proto_ver;
+    put_u16(pl + 2, id->fw_ver);
+    memcpy(pl + 4, id->uid, 12);
+    sendFrame(LINK_IDENT, pl, LINK_IDENT_LEN);
+}
+
+void usbSendLog(const char *msg) {
+    uint8_t len = (uint8_t)strnlen(msg, LINK_MAX_PAYLOAD);
+    sendFrame(LINK_LOG, (const uint8_t *)msg, len);
+}
+
+void usbLinkInit() {
+    Serial.begin(115200);
+}
+
+// ---- стейт-машина приёма ----
+enum RxState { WAIT_S0, WAIT_S1, READ_HDR, READ_PAYLOAD, READ_CRC };
+static RxState s_state = WAIT_S0;
+static uint8_t s_hdr[3];     // VER, TYPE, LEN
+static uint8_t s_hdrGot;
+static uint8_t s_payload[LINK_MAX_PAYLOAD];
+static uint8_t s_payGot;
+static uint8_t s_crc[2];
+static uint8_t s_crcGot;
+
+static void resync() { s_state = WAIT_S0; s_hdrGot = s_payGot = s_crcGot = 0; }
+
+void usbLinkPoll(LinkRxEvent *ev) {
+    ev->type = 0;
+    while (Serial.available() > 0) {
+        uint8_t b = (uint8_t)Serial.read();
+        switch (s_state) {
+        case WAIT_S0:
+            if (b == LINK_SYNC0) s_state = WAIT_S1;
+            break;
+        case WAIT_S1:
+            s_state = (b == LINK_SYNC1) ? READ_HDR : WAIT_S0;
+            s_hdrGot = 0;
+            break;
+        case READ_HDR:
+            s_hdr[s_hdrGot++] = b;
+            if (s_hdrGot == 3) {
+                // s_hdr: VER, TYPE, LEN
+                if (s_hdr[0] != LINK_VERSION || s_hdr[2] > LINK_MAX_PAYLOAD) {
+                    resync(); // неверная версия/длина — сдвиг и поиск заново
+                    break;
+                }
+                s_payGot = 0;
+                s_state = (s_hdr[2] == 0) ? READ_CRC : READ_PAYLOAD;
+            }
+            break;
+        case READ_PAYLOAD:
+            s_payload[s_payGot++] = b;
+            if (s_payGot == s_hdr[2])
+                s_state = READ_CRC;
+            break;
+        case READ_CRC:
+            s_crc[s_crcGot++] = b;
+            if (s_crcGot == 2) {
+                uint8_t chk[3 + LINK_MAX_PAYLOAD];
+                chk[0] = s_hdr[0]; chk[1] = s_hdr[1]; chk[2] = s_hdr[2];
+                memcpy(chk + 3, s_payload, s_hdr[2]);
+                uint16_t want = (uint16_t)s_crc[0] | ((uint16_t)s_crc[1] << 8);
+                uint16_t got = linkCrc16(chk, 3 + s_hdr[2]);
+                uint8_t type = s_hdr[1];
+                uint8_t len = s_hdr[2];
+                resync();
+                if (want == got) {
+                    if (type == LINK_CONTROL && len == LINK_CONTROL_LEN) {
+                        unpackControl(s_payload, &ev->control);
+                        ev->type = LINK_CONTROL;
+                        return;
+                    } else if (type == LINK_HELLO || type == LINK_IDENT || type == LINK_LOG) {
+                        ev->type = type;
+                        return;
+                    }
+                }
+                // битый CRC или неизвестный тип — молча ищем следующий кадр
+            }
+            break;
+        }
+    }
+}

device_firmware/cart_firmware/src/usb_link.h

@@ -0,0 +1,23 @@
+// Бинарный протокол поверх USB CDC (Serial): кадрирование, CRC16, сериализация
+// CONTROL/IDENT/LOG и стейт-машина приёма с ресинхронизацией. Общий для TX и RX.
+#pragma once
+#include "link_protocol.h"
+
+// Результат опроса входящего потока.
+struct LinkRxEvent {
+    uint8_t type;        // 0 = в этот вызов целого кадра нет; иначе LinkType
+    LinkControl control; // валидно при type == LINK_CONTROL
+};
+
+void usbLinkInit();
+
+// Разобрать доступные байты. Возвращает максимум один полный валидный кадр за
+// вызов (type != 0). Вызывать в цикле, пока event.type != 0, затем дальше.
+void usbLinkPoll(LinkRxEvent *ev);
+
+void usbSendControl(const LinkControl *c);
+void usbSendIdent(const LinkIdent *id);
+void usbSendLog(const char *msg);
+
+// Общий CRC16-CCITT (poly 0x1021, init 0xFFFF). Экспортирован для тестов.
+uint16_t linkCrc16(const uint8_t *data, uint16_t len);

device_firmware/cart_firmware/tools/bridge.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""Сетевой мост «пульт -> тележка»: один симметричный сервер, роль задаётся
+флагом. Два экземпляра переносят управление с STM-передатчика на STM-приёмник
+через локальную сеть/интернет.
+
+    [пульт] ADC-> STM(CART-TX) --USB--> bridge --role tx --UDP--> bridge --role rx --USB--> STM(CART-RX) --SBUS-> драйвер
+
+Роль tx: читает кадры CONTROL из USB от STM-TX и шлёт их по UDP на peer.
+Роль rx: принимает UDP, пишет CONTROL в USB на STM-RX; при тишине из сети шлёт
+         явную нейтраль с флагом failsafe (главный предохранитель — на самом STM).
+
+Обратный канал: rx шлёт tx heartbeat, поэтому на стороне отправителя видно,
+отвечает ли приёмник и не ушёл ли он сам в failsafe.
+
+Устройство выбирается по USB product string (CART-TX / CART-RX) и подтверждается
+handshake-кадром IDENT (роль + версия протокола). Для интернета используй общий
+ключ (--key) — каждый UDP-пакет аутентифицируется HMAC-SHA256; без ключа трафик
+идёт в открытом виде (только для доверенной локальной сети).
+
+Параметры можно задавать и через env (CART_BRIDGE_ROLE/PEER/BIND/DEVICE/KEY/
+LOG_LEVEL) — так настраиваются systemd-службы (см. deploy/).
+
+Запуск (из каталога прошивки):
+    .venv/bin/python tools/bridge.py --role tx --peer 10.0.0.2:5005
+    .venv/bin/python tools/bridge.py --role rx --bind 0.0.0.0:5005
+"""
+import argparse
+import hmac
+import logging
+import os
+import select
+import socket
+import struct
+import sys
+import time
+from hashlib import sha256
+
+import serial
+from serial.tools import list_ports
+
+import link_proto as lp
+
+HMAC_LEN = 8          # усечённый HMAC-SHA256 на пакет
+NET_TIMEOUT_S = 0.50  # нет UDP дольше -> rx начинает слать failsafe
+HELLO_TIMEOUT_S = 1.0
+SEQ_RESET_AFTER = 20  # столько подряд «несвежих» пакетов = перезапуск источника
+
+# Обратный канал «жив ли приёмник»: rx шлёт heartbeat в сторону tx (на адрес
+# источника последнего CONTROL), tx по ним показывает, отвечает ли приёмник и
+# не ушёл ли он сам в failsafe. Это PC-only служебный трафик (к STM отношения не
+# имеет), поэтому живёт здесь, а не в зеркале протокола link_proto.
+HEARTBEAT_MAGIC = b"\xCB\x01"
+HEARTBEAT_PERIOD_S = 0.2   # как часто rx шлёт heartbeat
+HEARTBEAT_TIMEOUT_S = 1.0  # нет heartbeat дольше -> tx считает приёмник недоступным
+HEARTBEAT_STATUS_S = 5.0   # период печати статуса приёмника на tx
+HB_FLAG_FAILSAFE = 0x01
+
+log = logging.getLogger("bridge")
+
+
+def pack_hb(failsafe: bool, last_seq: int) -> bytes:
+    flags = HB_FLAG_FAILSAFE if failsafe else 0
+    return HEARTBEAT_MAGIC + struct.pack("<BI", flags, last_seq & 0xFFFFFFFF)
+
+
+def parse_hb(payload: bytes):
+    """-> dict(failsafe, last_seq) либо None, если это не heartbeat."""
+    if len(payload) != len(HEARTBEAT_MAGIC) + 5 or payload[:2] != HEARTBEAT_MAGIC:
+        return None
+    flags, last_seq = struct.unpack_from("<BI", payload, 2)
+    return {"failsafe": bool(flags & HB_FLAG_FAILSAFE), "last_seq": last_seq}
+
+
+_ANSI = {"green": "\033[1;32m", "red": "\033[1;31m", "yellow": "\033[1;33m", "reset": "\033[0m"}
+
+
+def render_link_status(alive: bool, failsafe: bool, color: bool):
+    """Живая одна строка для оператора: зелёная «СВЯЗЬ ЕСТЬ» / красная «СВЯЗИ
+    НЕТ», обновляется на месте (возврат каретки)."""
+    if not alive:
+        text, c = "СВЯЗИ НЕТ", "red"
+    elif failsafe:
+        text, c = "СВЯЗЬ ЕСТЬ (приёмник в failsafe)", "yellow"
+    else:
+        text, c = "СВЯЗЬ ЕСТЬ", "green"
+    body = "● " + text
+    if color:
+        body = _ANSI[c] + body + _ANSI["reset"]
+    sys.stdout.write("\r\033[2K" + body)  # \033[2K — очистить строку
+    sys.stdout.flush()
+
+
+# ---------------- выбор и handshake USB-устройства ----------------
+
+def find_port(role: str, selector: str | None) -> str:
+    """Найти последовательный порт по роли (product string) или явному
+    селектору (путь /dev/..., подстрока product или серийник)."""
+    if selector and ("/" in selector or selector.startswith("COM")):
+        return selector  # явный путь к устройству
+    want_product = {"tx": "CART-TX", "rx": "CART-RX"}[role]
+    matches = []
+    for p in list_ports.comports():
+        hay = " ".join(filter(None, (p.product, p.serial_number, p.description))).upper()
+        if selector:
+            if selector.upper() in hay:
+                matches.append(p)
+        elif want_product in hay:
+            matches.append(p)
+    if not matches:
+        raise RuntimeError(f"USB-устройство роли {role} ({want_product}) не найдено")
+    if len(matches) > 1:
+        names = ", ".join(f"{m.device}({m.product})" for m in matches)
+        raise RuntimeError(f"найдено несколько кандидатов роли {role}: {names}; уточни --device")
+    return matches[0].device
+
+
+def handshake(ser: serial.Serial, role: str):
+    """Послать HELLO, дождаться IDENT, проверить роль и версию протокола."""
+    want_role = {"tx": lp.ROLE_TX, "rx": lp.ROLE_RX}[role]
+    parser = lp.FrameParser()
+    ser.reset_input_buffer()
+    ser.write(lp.build_frame(lp.HELLO, b""))
+    deadline = time.monotonic() + HELLO_TIMEOUT_S
+    while time.monotonic() < deadline:
+        for ftype, payload in parser.feed(ser.read(256)):
+            if ftype != lp.IDENT:
+                continue
+            ident = lp.unpack_ident(payload)
+            if ident["proto_ver"] != lp.VERSION:
+                raise RuntimeError(
+                    f"версия протокола устройства {ident['proto_ver']} != {lp.VERSION}")
+            if ident["role"] != want_role:
+                raise RuntimeError(
+                    f"устройство представилось ролью {lp.role_name(ident['role'])}, ожидалась {role}")
+            log.info("handshake OK: роль %s, fw 0x%04x, uid %s",
+                     role, ident["fw_ver"], ident["uid"].hex())
+            return
+    raise RuntimeError("нет ответа IDENT (не та прошивка/порт?)")
+
+
+def open_device(role: str, selector: str | None) -> serial.Serial:
+    port = find_port(role, selector)
+    ser = serial.Serial(port, baudrate=115200, timeout=0.05)
+    handshake(ser, role)
+    return ser
+
+
+# ---------------- аутентификация пакетов ----------------
+
+def seal(payload: bytes, key: bytes | None) -> bytes:
+    if not key:
+        return payload
+    return payload + hmac.new(key, payload, sha256).digest()[:HMAC_LEN]
+
+
+def unseal(datagram: bytes, key: bytes | None) -> bytes | None:
+    """Проверить HMAC и вернуть payload, либо None если пакет невалиден."""
+    if not key:
+        return datagram
+    if len(datagram) < HMAC_LEN:
+        return None
+    payload, tag = datagram[:-HMAC_LEN], datagram[-HMAC_LEN:]
+    want = hmac.new(key, payload, sha256).digest()[:HMAC_LEN]
+    return payload if hmac.compare_digest(tag, want) else None
+
+
+def seq_newer(a: int, b: int) -> bool:
+    """Арифметика последовательных номеров с переполнением uint32."""
+    return 0 < ((a - b) & 0xFFFFFFFF) < 0x80000000
+
+
+# ---------------- роль TX: USB -> сеть ----------------
+
+def run_tx(args, key):
+    peer = parse_hostport(args.peer, "peer")
+    ser = open_device("tx", args.device)
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    parser = lp.FrameParser()
+    log.info("tx: %s -> UDP %s:%d", ser.port, *peer)
+    sent = 0
+    rx_alive = False       # получаем ли heartbeat от приёмника
+    rx_failsafe = False    # сообщил ли приёмник, что сам в failsafe
+    last_hb = 0.0
+    last_status = 0.0
+    # В терминале — живая цветная строка; под systemd (journald, не TTY) — обычные
+    # события по изменению состояния.
+    tty = sys.stdout.isatty()
+    color = tty and os.environ.get("NO_COLOR") is None
+    while True:
+        # read(1) блокирует до первого байта, затем забираем всё доступное —
+        # кадр уходит в сеть сразу, без ожидания таймаута чтения (иначе каждый
+        # кадр задерживался бы до таймаута порта).
+        data = ser.read(1)
+        if ser.in_waiting:
+            data += ser.read(ser.in_waiting)
+        for ftype, payload in parser.feed(data):
+            if ftype == lp.CONTROL:
+                sock.sendto(seal(payload, key), peer)
+                sent += 1
+            elif ftype == lp.LOG:
+                log.info("STM-TX: %s", payload.decode("ascii", "replace"))
+
+        now = time.monotonic()
+        prev_alive, prev_fs = rx_alive, rx_failsafe
+        # обратный канал: heartbeat от приёмника (приходит на тот же сокет)
+        while select.select([sock], [], [], 0)[0]:
+            try:
+                datagram, _ = sock.recvfrom(2048)
+            except BlockingIOError:
+                break
+            hb = parse_hb(unseal(datagram, key) or b"")
+            if hb is None:
+                continue
+            last_hb = now
+            rx_alive = True
+            rx_failsafe = hb["failsafe"]
+        if rx_alive and now - last_hb > HEARTBEAT_TIMEOUT_S:
+            rx_alive, rx_failsafe = False, False
+
+        if tty:
+            render_link_status(rx_alive, rx_failsafe, color)  # живая строка
+        else:
+            if rx_alive != prev_alive:
+                (log.info if rx_alive else log.warning)(
+                    "приёмник отвечает" if rx_alive else "приёмник НЕ отвечает")
+            elif rx_alive and rx_failsafe != prev_fs:
+                (log.warning if rx_failsafe else log.info)(
+                    "приёмник в failsafe: наш поток не доходит" if rx_failsafe
+                    else "приёмник принимает поток")
+            if now - last_status >= HEARTBEAT_STATUS_S:
+                last_status = now
+                log.info("приёмник: %s (отправлено %d)",
+                         "отвечает" if rx_alive else "НЕ отвечает", sent)
+
+
+# ---------------- роль RX: сеть -> USB ----------------
+
+def run_rx(args, key):
+    bind = parse_hostport(args.bind, "bind")
+    # для rx --peer — фильтр источника по хосту (порт источника эфемерный)
+    allowed_host = args.peer.split(":")[0] if args.peer else None
+    ser = open_device("rx", args.device)
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(bind)
+    sock.setblocking(False)
+    parser = lp.FrameParser()
+    log.info("rx: UDP %s:%d -> %s", bind[0], bind[1], ser.port)
+
+    last_seq = None
+    last_net = time.monotonic()
+    last_fs = 0.0
+    last_hb_sent = 0.0
+    fs_seq = 0
+    in_failsafe = False
+    rejects = 0  # подряд отброшенных по seq -> признак перезапуска источника
+    tx_addr = None  # куда слать heartbeat (источник последнего CONTROL)
+
+    def accept(datagram, addr):
+        """Проверить пакет и обновить состояние; вернуть payload принятого
+        свежего кадра либо None."""
+        nonlocal last_seq, last_net, in_failsafe, rejects, tx_addr
+        if allowed_host and addr[0] != allowed_host:
+            log.warning("пакет с неожиданного адреса %s отброшен", addr[0])
+            return None
+        payload = unseal(datagram, key)
+        if not payload or len(payload) != lp.CONTROL_LEN:
+            log.warning("битый/неаутентичный пакет отброшен")
+            return None
+        tx_addr = addr  # аутентичный CONTROL -> знаем обратный адрес для heartbeat
+        c = lp.unpack_control(payload)
+        # Принять свежий seq ИЛИ новую сессию: источник (STM-TX) после ребута
+        # начинает seq заново с 0, и без сброса last_seq поток завис бы в
+        # failsafe навсегда. Новую сессию распознаём по пачке подряд «несвежих»
+        # пакетов (устойчиво к одиночным reorder/dup).
+        fresh = last_seq is None or seq_newer(c["seq"], last_seq)
+        if not fresh:
+            rejects += 1
+            if rejects >= SEQ_RESET_AFTER:
+                log.warning("seq откатился (%d -> %d): новая сессия", last_seq, c["seq"])
+                fresh = True
+        if not fresh:
+            return None  # устаревший/повторный — anti-replay
+        rejects = 0
+        last_seq = c["seq"]
+        last_net = time.monotonic()
+        if in_failsafe:
+            log.info("связь восстановлена")
+            in_failsafe = False
+        return payload
+
+    while True:
+        # Ждём пакет до 20 мс (пауза цикла), затем БЕЗ блокировки выгребаем всю
+        # накопившуюся очередь сокета и шлём на STM только самый свежий кадр
+        # (latest-wins): так задержка не растёт, даже если пакеты пришли пачкой.
+        newest = None
+        ready = select.select([sock], [], [], lp.FRAME_PERIOD_MS / 2000.0)[0]
+        while ready:
+            try:
+                datagram, addr = sock.recvfrom(2048)
+            except BlockingIOError:
+                break
+            p = accept(datagram, addr)
+            if p is not None:
+                newest = p
+            ready = select.select([sock], [], [], 0)[0]
+        if newest is not None:
+            ser.write(lp.build_frame(lp.CONTROL, newest))
+
+        # сетевой failsafe: тишина -> активная нейтраль на STM в темпе 20 Гц
+        now = time.monotonic()
+        if now - last_net >= NET_TIMEOUT_S and now - last_fs >= lp.FRAME_PERIOD_MS / 1000.0:
+            if not in_failsafe:
+                log.warning("потеря сети -> failsafe (нейтраль)")
+                in_failsafe = True
+                last_seq = None  # рестарт источника при простое примем сразу
+            ser.write(lp.build_frame(lp.CONTROL, lp.neutral_control(fs_seq, failsafe=True)))
+            fs_seq = (fs_seq + 1) & 0xFFFFFFFF
+            last_fs = now
+
+        # обратный heartbeat к tx: «приёмник жив», с признаком собственного failsafe
+        if tx_addr is not None and now - last_hb_sent >= HEARTBEAT_PERIOD_S:
+            sock.sendto(seal(pack_hb(in_failsafe, last_seq or 0), key), tx_addr)
+            last_hb_sent = now
+
+        # неблокирующий дренаж входящих LOG от STM-RX
+        if ser.in_waiting:
+            for ftype, payload in parser.feed(ser.read(ser.in_waiting)):
+                if ftype == lp.LOG:
+                    log.info("STM-RX: %s", payload.decode("ascii", "replace"))
+
+
+# ---------------- общее ----------------
+
+def parse_hostport(s: str, what: str):
+    if ":" not in s:
+        raise SystemExit(f"--{what} ожидает HOST:PORT, получено {s!r}")
+    host, port = s.rsplit(":", 1)
+    return (host, int(port))
+
+
+def main():
+    # Значения по умолчанию берутся из env (CART_BRIDGE_*), чтобы systemd-юнит
+    # мог задавать всё через EnvironmentFile; аргументы CLI их переопределяют.
+    env = os.environ.get
+    ap = argparse.ArgumentParser(description="мост пульт<->тележка через сеть")
+    ap.add_argument("--role", default=env("CART_BRIDGE_ROLE"), choices=("tx", "rx"))
+    ap.add_argument("--peer", default=env("CART_BRIDGE_PEER"),
+                    help="tx: куда слать HOST:PORT; rx: разрешённый источник (опц.)")
+    ap.add_argument("--bind", default=env("CART_BRIDGE_BIND", "0.0.0.0:5005"),
+                    help="rx: локальный UDP HOST:PORT")
+    ap.add_argument("--device", default=env("CART_BRIDGE_DEVICE"),
+                    help="путь к порту или подстрока product/serial (иначе по роли)")
+    ap.add_argument("--key", default=env("CART_BRIDGE_KEY"),
+                    help="общий ключ для HMAC-аутентификации пакетов (для интернета)")
+    ap.add_argument("--log-level", default=env("CART_BRIDGE_LOG_LEVEL", "INFO"))
+    args = ap.parse_args()
+
+    logging.basicConfig(level=args.log_level.upper(),
+                        format="%(asctime)s %(levelname)s %(message)s")
+    if args.role not in ("tx", "rx"):
+        raise SystemExit("нужна роль: --role tx|rx (или CART_BRIDGE_ROLE)")
+    key = args.key.encode() if args.key else None
+    if args.role == "tx" and not args.peer:
+        raise SystemExit("--peer обязателен для роли tx")
+    if not key:
+        log.warning("без --key: трафик не аутентифицирован, только для доверенной сети")
+
+    try:
+        (run_tx if args.role == "tx" else run_rx)(args, key)
+    except KeyboardInterrupt:
+        log.info("остановлено")
+    finally:
+        if sys.stdout.isatty():
+            sys.stdout.write("\n")  # увести живую строку от приглашения shell
+
+
+if __name__ == "__main__":
+    main()

device_firmware/cart_firmware/tools/link_proto.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Зеркало бинарного протокола из src/link_protocol.h (единственный источник
+истины на стороне Python). Кадрирование поверх потока, CRC16-CCITT, упаковка и
+разбор CONTROL/IDENT/HELLO/LOG, инкрементальный парсер с ресинхронизацией.
+
+При правке src/link_protocol.h меняй ЭТОТ файл и сверяйся:
+    python3 tools/link_proto.py --selftest
+"""
+import struct
+import sys
+
+SYNC0 = 0xA5
+SYNC1 = 0x5A
+VERSION = 1
+MAX_PAYLOAD = 64
+
+# типы кадров
+HELLO = 0x03
+IDENT = 0x02
+CONTROL = 0x01
+LOG = 0x04
+
+# роли
+ROLE_TX = ord("T")
+ROLE_RX = ord("R")
+
+# флаги CONTROL
+CTRL_FLAG_FAILSAFE = 0x01
+
+CONTROL_LEN = 4 + 4 + 1 + 2 * 16  # 41
+IDENT_LEN = 1 + 1 + 2 + 12  # 16
+
+SBUS_MID = 1024
+
+# тайминги (мс), зеркало link_protocol.h
+FRAME_PERIOD_MS = 50
+RX_USB_TIMEOUT_MS = 400
+
+
+def crc16(data: bytes) -> int:
+    """CRC16-CCITT, poly 0x1021, init 0xFFFF — как linkCrc16 в прошивке."""
+    crc = 0xFFFF
+    for byte in data:
+        crc ^= byte << 8
+        for _ in range(8):
+            crc = ((crc << 1) ^ 0x1021) & 0xFFFF if (crc & 0x8000) else (crc << 1) & 0xFFFF
+    return crc
+
+
+def build_frame(frame_type: int, payload: bytes) -> bytes:
+    """Собрать кадр: SYNC + VER + TYPE + LEN + PAYLOAD + CRC16(LE)."""
+    if len(payload) > MAX_PAYLOAD:
+        raise ValueError("payload too long")
+    body = bytes((VERSION, frame_type, len(payload))) + payload
+    crc = crc16(body)
+    return bytes((SYNC0, SYNC1)) + body + struct.pack("<H", crc)
+
+
+def pack_control(seq: int, t_ms: int, flags: int, ch) -> bytes:
+    """Полезная нагрузка CONTROL. ch — 16 значений 0..2047."""
+    if len(ch) != 16:
+        raise ValueError("need 16 channels")
+    return struct.pack("<IIB16H", seq & 0xFFFFFFFF, t_ms & 0xFFFFFFFF, flags & 0xFF, *ch)
+
+
+def unpack_control(payload: bytes):
+    """-> dict(seq, t_ms, flags, ch[16])."""
+    if len(payload) != CONTROL_LEN:
+        raise ValueError("bad CONTROL length")
+    seq, t_ms, flags = struct.unpack_from("<IIB", payload, 0)
+    ch = list(struct.unpack_from("<16H", payload, 9))
+    return {"seq": seq, "t_ms": t_ms, "flags": flags, "ch": ch}
+
+
+def unpack_ident(payload: bytes):
+    """-> dict(role, proto_ver, fw_ver, uid)."""
+    if len(payload) != IDENT_LEN:
+        raise ValueError("bad IDENT length")
+    role, proto_ver, fw_ver = struct.unpack_from("<BBH", payload, 0)
+    uid = payload[4:16]
+    return {"role": role, "proto_ver": proto_ver, "fw_ver": fw_ver, "uid": uid}
+
+
+def role_name(role: int) -> str:
+    return {ROLE_TX: "tx", ROLE_RX: "rx"}.get(role, "?")
+
+
+def neutral_control(seq: int = 0, t_ms: int = 0, failsafe: bool = True) -> bytes:
+    """Нейтральный CONTROL (все каналы 1024) — для сетевого failsafe на RX."""
+    flags = CTRL_FLAG_FAILSAFE if failsafe else 0
+    return pack_control(seq, t_ms, flags, [SBUS_MID] * 16)
+
+
+class FrameParser:
+    """Инкрементальный разбор потока. Скорми feed() любые байты — вернёт список
+    (type, payload) полных валидных кадров. Устойчив к мусору и потере байт:
+    при сбое CRC/версии сдвигается на байт и ищет следующий SYNC."""
+
+    def __init__(self):
+        self._buf = bytearray()
+
+    def feed(self, data: bytes):
+        self._buf.extend(data)
+        out = []
+        while True:
+            frame = self._try_one()
+            if frame is None:
+                break
+            out.append(frame)
+        return out
+
+    def _try_one(self):
+        buf = self._buf
+        while True:
+            # найти синхрослово
+            while len(buf) >= 2 and not (buf[0] == SYNC0 and buf[1] == SYNC1):
+                del buf[0]
+            if len(buf) < 5:  # SYNC(2)+VER+TYPE+LEN
+                return None
+            ver, ftype, length = buf[2], buf[3], buf[4]
+            if ver != VERSION or length > MAX_PAYLOAD:
+                del buf[0]  # ложный синк — сдвиг и поиск заново в этом же вызове
+                continue
+            total = 5 + length + 2
+            if len(buf) < total:
+                return None
+            body = bytes(buf[2:5 + length])
+            want = struct.unpack_from("<H", buf, 5 + length)[0]
+            if crc16(body) != want:
+                del buf[0]  # битый кадр — ресинхронизация
+                continue
+            payload = bytes(buf[5:5 + length])
+            del buf[:total]
+            return (ftype, payload)
+
+
+def _selftest():
+    # тест-вектор CONTROL: совпадает с packControl в прошивке
+    ch = [SBUS_MID] * 16
+    ch[1] = 1500
+    ch[3] = 600
+    payload = pack_control(0x01020304, 0x0A0B0C0D, CTRL_FLAG_FAILSAFE, ch)
+    assert len(payload) == CONTROL_LEN, len(payload)
+    back = unpack_control(payload)
+    assert back["seq"] == 0x01020304 and back["ch"][1] == 1500 and back["flags"] == 1, back
+
+    # кадрирование туда-обратно через парсер, c мусором спереди
+    frame = build_frame(CONTROL, payload)
+    p = FrameParser()
+    frames = p.feed(b"\x00\xffgarbage" + frame)
+    assert len(frames) == 1 and frames[0][0] == CONTROL, frames
+    assert frames[0][1] == payload
+
+    # битый CRC отбрасывается, следующий кадр ловится
+    bad = bytearray(frame)
+    bad[-1] ^= 0xFF
+    p2 = FrameParser()
+    assert p2.feed(bytes(bad)) == []
+    assert len(p2.feed(frame)) == 1
+
+    # битый + валидный в ОДНОМ feed() -> валидный извлекается сразу (ресинхрон
+    # не прерывает разбор остатка буфера)
+    p3 = FrameParser()
+    got = p3.feed(bytes(bad) + frame)
+    assert len(got) == 1 and got[0][1] == payload, got
+
+    # известный CRC-вектор для сверки с прошивкой
+    assert crc16(b"123456789") == 0x29B1, hex(crc16(b"123456789"))
+    print("link_proto selftest OK")
+
+
+if __name__ == "__main__":
+    if "--selftest" in sys.argv:
+        _selftest()
+    else:
+        print(__doc__)

python_app/gui/app_window.py

@@ -371,6 +371,9 @@ class AppWindow(
         self._gpr_region_contours = []
         self._gpr_geometry_signature = None
         self._gpr_selected_geometry = None
+        self._sar3d_lookup_table = None
+        self._sar3d_xz_image_item = None
+        self._sar3d_xy_image_item = None
         self._phase_viewbox = None
         self._history_run_signature = None
         self._processor_run_signature = None

python_app/gui/controllers/app_window_config/live_processing_mixin.py

@@ -13,13 +13,13 @@ from PyQt6.QtWidgets import (
 )
 
 from python_app.gui.runtime.constraints import validate_processing_mode_constraints
+from python_app.gui.runtime.sar3d_views import sar3d_bottom_view_deg_from_label
 from python_app.orchestration.live_processing_config import ProcessingLiveConfig
 
 _GPR_MODES = ("gpr", "legacy_gpr")
-
-
-def _is_legacy_gpr(window) -> bool:
-    return window._processing_mode.currentText() == "legacy_gpr"
+# Modes that consume the shared gpr_* live-config fields (band, depth gate, antenna
+# selection, motion): both GPR imagers plus the 3D SAR processor.
+_GPR_LIKE_MODES = ("gpr", "legacy_gpr", "sar3d")
 
 
 def _attr(name: str):
@@ -27,9 +27,16 @@ def _attr(name: str):
     return lambda window: getattr(window, name)
 
 
-def _dual(gpr_attr: str, legacy_attr: str):
-    """Widget getter for a gpr_* field with separate gpr / legacy_gpr widgets."""
-    return lambda window: getattr(window, legacy_attr if _is_legacy_gpr(window) else gpr_attr)
+def _dual(default_attr: str, mode_attrs: dict[str, str] | None = None):
+    """Widget getter for a field with per-mode widgets (gpr / legacy_gpr / sar3d).
+
+    `mode_attrs` maps a processor mode to its dedicated widget attribute; any
+    other mode (including inactive ones) falls back to `default_attr`.
+    """
+    attrs = dict(mode_attrs or {})
+    return lambda window: getattr(
+        window, attrs.get(window._processing_mode.currentText(), default_attr)
+    )
 
 
 # The ONE authoritative field <-> widget map (inverse of `_live_processing_config`),
@@ -50,17 +57,17 @@ _WEB_LIVE_SCHEMA = [
     ("bscan_start_freq_mhz", "B-scan", ("bscan",), _attr("_bscan_start_freq_mhz")),
     ("bscan_stop_freq_mhz", "B-scan", ("bscan",), _attr("_bscan_stop_freq_mhz")),
     ("legacy_gpr_mode", "Mode", ("legacy_gpr",), _attr("_legacy_gpr_config_mode")),
-    ("gpr_input_positions", "Geometry & depth", _GPR_MODES, _dual("_gpr_input_positions_input", "_legacy_gpr_input_positions_input")),
-    ("gpr_output_positions", "Geometry & depth", _GPR_MODES, _dual("_gpr_output_positions_input", "_legacy_gpr_output_positions_input")),
-    ("gpr_min_depth_m", "Geometry & depth", _GPR_MODES, _dual("_gpr_min_depth_m", "_legacy_gpr_min_depth_m")),
-    ("gpr_max_depth_m", "Geometry & depth", _GPR_MODES, _dual("_gpr_max_depth_m", "_legacy_gpr_max_depth_m")),
-    ("gpr_start_freq_mhz", "Geometry & depth", _GPR_MODES, _dual("_gpr_start_freq_mhz", "_legacy_gpr_start_freq_mhz")),
-    ("gpr_stop_freq_mhz", "Geometry & depth", _GPR_MODES, _dual("_gpr_stop_freq_mhz", "_legacy_gpr_stop_freq_mhz")),
+    ("gpr_input_positions", "Geometry & depth", _GPR_LIKE_MODES, _dual("_gpr_input_positions_input", {"legacy_gpr": "_legacy_gpr_input_positions_input", "sar3d": "_sar3d_input_positions_input"})),
+    ("gpr_output_positions", "Geometry & depth", _GPR_LIKE_MODES, _dual("_gpr_output_positions_input", {"legacy_gpr": "_legacy_gpr_output_positions_input", "sar3d": "_sar3d_output_positions_input"})),
+    ("gpr_min_depth_m", "Geometry & depth", _GPR_LIKE_MODES, _dual("_gpr_min_depth_m", {"legacy_gpr": "_legacy_gpr_min_depth_m", "sar3d": "_sar3d_min_depth_m"})),
+    ("gpr_max_depth_m", "Geometry & depth", _GPR_LIKE_MODES, _dual("_gpr_max_depth_m", {"legacy_gpr": "_legacy_gpr_max_depth_m", "sar3d": "_sar3d_max_depth_m"})),
+    ("gpr_start_freq_mhz", "Geometry & depth", _GPR_LIKE_MODES, _dual("_gpr_start_freq_mhz", {"legacy_gpr": "_legacy_gpr_start_freq_mhz", "sar3d": "_sar3d_start_freq_mhz"})),
+    ("gpr_stop_freq_mhz", "Geometry & depth", _GPR_LIKE_MODES, _dual("_gpr_stop_freq_mhz", {"legacy_gpr": "_legacy_gpr_stop_freq_mhz", "sar3d": "_sar3d_stop_freq_mhz"})),
     ("gpr_imaging_plane_y_m", "Geometry & depth", ("gpr",), _attr("_gpr_imaging_plane_y_m")),
     ("gpr_range_comp_power", "Imaging", ("gpr",), _attr("_gpr_range_comp_power")),
     ("gpr_score_mode", "Imaging", ("gpr",), _attr("_gpr_score_mode")),
-    ("gpr_background_subtract_enabled", "Imaging", _GPR_MODES, _dual("_gpr_background_subtract_enabled", "_legacy_gpr_background_subtract_enabled")),
-    ("gpr_background_mean_count", "Imaging", _GPR_MODES, _dual("_gpr_background_mean_count", "_legacy_gpr_background_mean_count")),
+    ("gpr_background_subtract_enabled", "Imaging", _GPR_MODES, _dual("_gpr_background_subtract_enabled", {"legacy_gpr": "_legacy_gpr_background_subtract_enabled"})),
+    ("gpr_background_mean_count", "Imaging", _GPR_MODES, _dual("_gpr_background_mean_count", {"legacy_gpr": "_legacy_gpr_background_mean_count"})),
     ("gpr_remove_sidelobe_objects_enabled", "Imaging", ("gpr",), _attr("_gpr_remove_sidelobe_objects_enabled")),
     ("gpr_object_min_frac", "Detection", ("gpr",), _attr("_gpr_object_min_frac")),
     ("gpr_max_detected_objects_to_draw", "Detection", ("gpr",), _attr("_gpr_max_detected_objects_to_draw")),
@@ -70,17 +77,38 @@ _WEB_LIVE_SCHEMA = [
     ("gpr_snr_thresh", "Detection", ("legacy_gpr",), _attr("_legacy_gpr_snr_thresh")),
     ("gpr_snr_comp_max", "Detection", ("legacy_gpr",), _attr("_legacy_gpr_snr_comp_max")),
     ("legacy_gpr_min_visible_pair_count", "Detection", ("legacy_gpr",), _attr("_legacy_gpr_min_visible_pair_count")),
-    ("gpr_visible_x_min_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_x_min_m", "_legacy_gpr_visible_x_min_m")),
-    ("gpr_visible_x_max_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_x_max_m", "_legacy_gpr_visible_x_max_m")),
-    ("gpr_visible_z_min_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_z_min_m", "_legacy_gpr_visible_z_min_m")),
-    ("gpr_visible_z_max_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_z_max_m", "_legacy_gpr_visible_z_max_m")),
+    ("gpr_visible_x_min_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_x_min_m", {"legacy_gpr": "_legacy_gpr_visible_x_min_m"})),
+    ("gpr_visible_x_max_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_x_max_m", {"legacy_gpr": "_legacy_gpr_visible_x_max_m"})),
+    ("gpr_visible_z_min_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_z_min_m", {"legacy_gpr": "_legacy_gpr_visible_z_min_m"})),
+    ("gpr_visible_z_max_m", "Visible window", _GPR_MODES, _dual("_gpr_visible_z_max_m", {"legacy_gpr": "_legacy_gpr_visible_z_max_m"})),
     ("gpr_motion_mode", "Motion", ("gpr",), _attr("_gpr_motion_mode")),
-    ("gpr_look_angle_deg", "Motion", _GPR_MODES, _dual("_gpr_look_angle_deg", "_legacy_gpr_look_angle_deg")),
-    ("gpr_direction_sign", "Motion", ("gpr",), _attr("_gpr_direction_sign")),
-    ("gpr_apply_freq_phase_correction", "Motion", ("legacy_gpr",), _attr("_legacy_gpr_apply_freq_phase_correction")),
+    ("gpr_look_angle_deg", "Motion", _GPR_LIKE_MODES, _dual("_gpr_look_angle_deg", {"legacy_gpr": "_legacy_gpr_look_angle_deg", "sar3d": "_sar3d_look_angle_deg"})),
+    ("gpr_direction_sign", "Motion", ("gpr", "sar3d"), _dual("_gpr_direction_sign", {"sar3d": "_sar3d_direction_sign"})),
+    ("gpr_apply_freq_phase_correction", "Motion", ("legacy_gpr", "sar3d"), _dual("_legacy_gpr_apply_freq_phase_correction", {"sar3d": "_sar3d_apply_freq_phase_correction"})),
     ("gpr_reference_mode", "Motion", ("legacy_gpr",), _attr("_legacy_gpr_reference_mode")),
-    ("ignore_socket_speed", "Motion", _GPR_MODES, _dual("_gpr_ignore_socket_speed_enabled", "_legacy_gpr_ignore_socket_speed_enabled")),
-    ("gpr_speed_m_s", "Motion", _GPR_MODES, _dual("_gpr_speed_m_s", "_legacy_gpr_speed_m_s")),
+    ("ignore_socket_speed", "Motion", _GPR_LIKE_MODES, _dual("_gpr_ignore_socket_speed_enabled", {"legacy_gpr": "_legacy_gpr_ignore_socket_speed_enabled", "sar3d": "_sar3d_ignore_socket_speed_enabled"})),
+    ("gpr_speed_m_s", "Motion", _GPR_LIKE_MODES, _dual("_gpr_speed_m_s", {"legacy_gpr": "_legacy_gpr_speed_m_s", "sar3d": "_sar3d_speed_m_s"})),
+    ("sar3d_frame_radius", "3D SAR", ("sar3d",), _attr("_sar3d_frame_radius")),
+    ("sar3d_edge_frame_weight", "3D SAR", ("sar3d",), _attr("_sar3d_edge_frame_weight")),
+    ("sar3d_pitch_override_enabled", "3D SAR", ("sar3d",), _attr("_sar3d_pitch_override_enabled")),
+    ("sar3d_pitch_deg", "3D SAR", ("sar3d",), _attr("_sar3d_pitch_deg")),
+    ("sar3d_ground_depth_m", "3D SAR", ("sar3d",), _attr("_sar3d_ground_depth_m")),
+    ("sar3d_x_min_m", "3D SAR", ("sar3d",), _attr("_sar3d_x_min_m")),
+    ("sar3d_x_max_m", "3D SAR", ("sar3d",), _attr("_sar3d_x_max_m")),
+    ("sar3d_y_min_m", "3D SAR", ("sar3d",), _attr("_sar3d_y_min_m")),
+    ("sar3d_y_max_m", "3D SAR", ("sar3d",), _attr("_sar3d_y_max_m")),
+    ("sar3d_z_min_m", "3D SAR", ("sar3d",), _attr("_sar3d_z_min_m")),
+    ("sar3d_z_max_m", "3D SAR", ("sar3d",), _attr("_sar3d_z_max_m")),
+    ("sar3d_voxel_x_m", "3D SAR", ("sar3d",), _attr("_sar3d_voxel_x_m")),
+    ("sar3d_voxel_y_m", "3D SAR", ("sar3d",), _attr("_sar3d_voxel_y_m")),
+    ("sar3d_voxel_z_m", "3D SAR", ("sar3d",), _attr("_sar3d_voxel_z_m")),
+    ("sar3d_norm_edge_margin_m", "3D SAR", ("sar3d",), _attr("_sar3d_norm_edge_margin_m")),
+    ("sar3d_smooth_sigma", "3D SAR", ("sar3d",), _attr("_sar3d_smooth_sigma")),
+    ("sar3d_comp_range_power", "3D SAR", ("sar3d",), _attr("_sar3d_comp_range_power")),
+    ("sar3d_tx_per_segment", "3D SAR", ("sar3d",), _attr("_sar3d_tx_per_segment")),
+    ("sar3d_use_compensation", "3D SAR", ("sar3d",), _attr("_sar3d_use_compensation")),
+    ("sar3d_normalize_pairs", "3D SAR", ("sar3d",), _attr("_sar3d_normalize_pairs")),
+    ("sar3d_bottom_view_deg", "3D SAR", ("sar3d",), _attr("_sar3d_bottom_view")),
 ]
 _WEB_LIVE_GETTERS = {field: getter for field, _group, _modes, getter in _WEB_LIVE_SCHEMA}
 
@@ -101,7 +129,7 @@ _NON_WIDGET_LIVE_FIELDS = frozenset({
 # config). They apply immediately through the same redraw as a live edit but write
 # nothing to processing_live.json.
 _WEB_DISPLAY_SCHEMA = [
-    ("render_mode", "Display", _GPR_MODES, _dual("_gpr_render_mode", "_legacy_gpr_render_mode")),
+    ("render_mode", "Display", _GPR_MODES, _dual("_gpr_render_mode", {"legacy_gpr": "_legacy_gpr_render_mode"})),
     ("subtract_mean_ascan", "Display", ("bscan",), _attr("_bscan_subtract_mean_ascan")),
     ("combo_filter", "Display", ("pass_through",), _attr("_pass_through_combo_filter_input")),
 ]
@@ -113,8 +141,8 @@ _WEB_STABLE_SCHEMA = [
     # Coherent BP fixes the medium to eps_r = 1 (Horns_motion_3libre.py), so relative
     # permittivity is a legacy-GPR-only knob; BP ignores it.
     ("relative_permittivity", "Geometry & medium", ("legacy_gpr",), _attr("_gpr_relative_permittivity")),
-    ("tx_geometry", "Geometry & medium", _GPR_MODES, _attr("_gpr_tx_geometry_input")),
-    ("rx_geometry", "Geometry & medium", _GPR_MODES, _attr("_gpr_rx_geometry_input")),
+    ("tx_geometry", "Geometry & medium", _GPR_LIKE_MODES, _attr("_gpr_tx_geometry_input")),
+    ("rx_geometry", "Geometry & medium", _GPR_LIKE_MODES, _attr("_gpr_rx_geometry_input")),
 ]
 
 # Every field the web form renders and may write back, across all three categories.
@@ -222,6 +250,17 @@ class AppWindowLiveProcessingMixin:
         """Return whether a mode uses GPR result payloads and plot surface."""
         return mode in {"gpr", "legacy_gpr"}
 
+    @staticmethod
+    def _is_gpr_like_processing_mode(mode: str) -> bool:
+        """Return whether a mode consumes the shared gpr_* fields and Tx/Rx geometry.
+
+        Covers both GPR imagers and the 3D SAR processor. The latter renders on its
+        own plot surface, so GPR-object/locator branches must keep using
+        :meth:`_is_gpr_processing_mode`; this predicate gates only the shared
+        behaviors (result drain on settings changes, geometry page visibility).
+        """
+        return mode in set(_GPR_LIKE_MODES)
+
     def _validate_processing_mode_selection(self, mode: str) -> None:
         """Validate requested processing mode against current stable/live GUI state."""
         validate_processing_mode_constraints(
@@ -256,6 +295,10 @@ class AppWindowLiveProcessingMixin:
         # Switch-position CSV text -> integer lists.
         values["gpr_input_positions"] = self._parse_csv_int_list(values["gpr_input_positions"])
         values["gpr_output_positions"] = self._parse_csv_int_list(values["gpr_output_positions"])
+        # Bottom-view combo label -> projection angle in degrees.
+        values["sar3d_bottom_view_deg"] = sar3d_bottom_view_deg_from_label(
+            str(values["sar3d_bottom_view_deg"])
+        )
         # Order-normalize the pass-through Y range so a reversed entry still works.
         y_min_db, y_max_db = values["pass_through_y_min_db"], values["pass_through_y_max_db"]
         values["pass_through_y_min_db"] = min(y_min_db, y_max_db)
@@ -352,7 +395,7 @@ class AppWindowLiveProcessingMixin:
             return
         try:
             current_mode = self._processing_mode.currentText()
-            if self._is_gpr_processing_mode(current_mode):
+            if self._is_gpr_like_processing_mode(current_mode):
                 self._drain_results_until_quiet(timeout_s=0.05, poll_s=0.005)
 
             self._write_live_processing_config()
@@ -364,16 +407,16 @@ class AppWindowLiveProcessingMixin:
                 # recompute of everything on screen. Debounced, so dragging a spin box
                 # sends one burst instead of one per step.
                 self._schedule_bscan_history_reprocess()
-            elif self._is_gpr_processing_mode(current_mode):
+            elif self._is_gpr_like_processing_mode(current_mode):
                 latest = self._drain_results_until_quiet(timeout_s=0.8, poll_s=0.02)
                 collection = latest
                 if collection is None and self._result_history:
                     collection = self._result_history[-1]
-                if collection is not None:
-                    if not self._draw_results(collection):
+                if collection is None or not self._draw_results(collection):
+                    if current_mode == "sar3d":
+                        self._clear_sar3d_plot()
+                    else:
                         self._clear_gpr_plot()
-                else:
-                    self._clear_gpr_plot()
             elif self._result_history:
                 self._draw_results(self._result_history[-1])
             else:
@@ -427,9 +470,10 @@ class AppWindowLiveProcessingMixin:
             "bscan": 1,
             "gpr": 2,
             "legacy_gpr": 3,
+            "sar3d": 4,
         }
         self._processing_mode_pages.setCurrentIndex(mode_to_page.get(mode, 0))
-        self._gpr_common_page.setVisible(self._is_gpr_processing_mode(mode))
+        self._gpr_common_page.setVisible(self._is_gpr_like_processing_mode(mode))
         current_page = self._processing_mode_pages.currentWidget()
         if current_page is not None:
             self._processing_mode_pages.setFixedHeight(current_page.sizeHint().height())
@@ -509,9 +553,20 @@ class AppWindowLiveProcessingMixin:
                 f"render_mode={self._legacy_gpr_render_mode.currentText()}, "
                 f"min_pairs={self._legacy_gpr_min_visible_pair_count.value()})"
             )
+        elif mode == "sar3d":
+            self._log(
+                "Processing mode selected: sar3d "
+                f"(inputs={self._sar3d_input_positions_input.text().strip() or '<all>'}, "
+                f"outputs={self._sar3d_output_positions_input.text().strip() or '<all>'}, "
+                f"depth={self._sar3d_min_depth_m.value():g}..{self._sar3d_max_depth_m.value():g} m, "
+                f"freq={self._sar3d_start_freq_mhz.value():g}..{self._sar3d_stop_freq_mhz.value():g} MHz, "
+                f"frame_radius={self._sar3d_frame_radius.value()}, "
+                f"voxel={self._sar3d_voxel_x_m.value():g}x{self._sar3d_voxel_y_m.value():g}x{self._sar3d_voxel_z_m.value():g} m, "
+                f"ground_depth={self._sar3d_ground_depth_m.value():g} m)"
+            )
 
     def _clear_history_mode_caches(self) -> None:
-        """Drop cached render state for pass-through, B-scan, and GPR views."""
+        """Drop cached render state for pass-through, B-scan, GPR, and 3D SAR views."""
         self._clear_bscan_plot_history()
         if hasattr(self, "_bscan_plot"):
             self._bscan_plot.clear()
@@ -519,6 +574,8 @@ class AppWindowLiveProcessingMixin:
         self._clear_trace_plots()
         if hasattr(self, "_gpr_plot"):
             self._clear_gpr_plot()
+        if hasattr(self, "_sar3d_xz_plot"):
+            self._clear_sar3d_plot()
 
     def _redraw_after_history_deletion(self) -> None:
         """Refresh plot immediately after destructive history deletion."""
@@ -534,6 +591,11 @@ class AppWindowLiveProcessingMixin:
                 return
             self._clear_gpr_plot()
             return
+        if self._processing_mode.currentText() == "sar3d":
+            if self._result_history and self._draw_results(self._result_history[-1]):
+                return
+            self._clear_sar3d_plot()
+            return
         if self._result_history:
             self._draw_results(self._result_history[-1])
             return

python_app/gui/controllers/app_window_config/profile_io_mixin.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from PyQt6.QtCore import QSignalBlocker
 from PyQt6.QtWidgets import QFileDialog
 
+from python_app.gui.runtime.sar3d_views import sar3d_bottom_view_label_from_deg
 from python_app.models.gui_profile_model import GuiProfileModel
 from python_app.models.run_config_model import RunConfigModel
 from python_app.orchestration.preprocess_assets import (
@@ -336,6 +337,37 @@ class AppWindowConfigProfileIOMixin:
             self._legacy_gpr_visible_x_max_m,
             self._legacy_gpr_visible_z_min_m,
             self._legacy_gpr_visible_z_max_m,
+            self._sar3d_input_positions_input,
+            self._sar3d_output_positions_input,
+            self._sar3d_min_depth_m,
+            self._sar3d_max_depth_m,
+            self._sar3d_start_freq_mhz,
+            self._sar3d_stop_freq_mhz,
+            self._sar3d_speed_m_s,
+            self._sar3d_ignore_socket_speed_enabled,
+            self._sar3d_look_angle_deg,
+            self._sar3d_direction_sign,
+            self._sar3d_apply_freq_phase_correction,
+            self._sar3d_frame_radius,
+            self._sar3d_edge_frame_weight,
+            self._sar3d_pitch_override_enabled,
+            self._sar3d_pitch_deg,
+            self._sar3d_ground_depth_m,
+            self._sar3d_x_min_m,
+            self._sar3d_x_max_m,
+            self._sar3d_y_min_m,
+            self._sar3d_y_max_m,
+            self._sar3d_z_min_m,
+            self._sar3d_z_max_m,
+            self._sar3d_voxel_x_m,
+            self._sar3d_voxel_y_m,
+            self._sar3d_voxel_z_m,
+            self._sar3d_norm_edge_margin_m,
+            self._sar3d_smooth_sigma,
+            self._sar3d_comp_range_power,
+            self._sar3d_tx_per_segment,
+            self._sar3d_use_compensation,
+            self._sar3d_normalize_pairs,
             self._save_count,
             self._record_count,
             self._save_path_input,
@@ -524,6 +556,43 @@ class AppWindowConfigProfileIOMixin:
             self._legacy_gpr_visible_z_min_m.setValue(float(gui_state.processing.legacy_gpr.visible_z_min_m))
             self._legacy_gpr_visible_z_max_m.setValue(float(gui_state.processing.legacy_gpr.visible_z_max_m))
 
+            sar3d_state = gui_state.processing.sar3d
+            self._sar3d_input_positions_input.setText(str(sar3d_state.input_positions))
+            self._sar3d_output_positions_input.setText(str(sar3d_state.output_positions))
+            self._sar3d_min_depth_m.setValue(float(sar3d_state.min_depth_m))
+            self._sar3d_max_depth_m.setValue(float(sar3d_state.max_depth_m))
+            self._sar3d_start_freq_mhz.setValue(float(sar3d_state.start_freq_mhz))
+            self._sar3d_stop_freq_mhz.setValue(float(sar3d_state.stop_freq_mhz))
+            self._sar3d_speed_m_s.setValue(float(sar3d_state.speed_m_s))
+            self._sar3d_ignore_socket_speed_enabled.setChecked(bool(sar3d_state.ignore_socket_speed_enabled))
+            self._sar3d_look_angle_deg.setValue(float(sar3d_state.look_angle_deg))
+            self._sar3d_direction_sign.setValue(float(sar3d_state.direction_sign))
+            self._sar3d_apply_freq_phase_correction.setChecked(bool(sar3d_state.apply_freq_phase_correction))
+            self._sar3d_frame_radius.setValue(int(sar3d_state.frame_radius))
+            self._sar3d_edge_frame_weight.setValue(float(sar3d_state.edge_frame_weight))
+            self._sar3d_pitch_override_enabled.setChecked(bool(sar3d_state.pitch_override_enabled))
+            self._sar3d_pitch_deg.setValue(float(sar3d_state.pitch_deg))
+            self._sar3d_ground_depth_m.setValue(float(sar3d_state.ground_depth_m))
+            self._sar3d_x_min_m.setValue(float(sar3d_state.x_min_m))
+            self._sar3d_x_max_m.setValue(float(sar3d_state.x_max_m))
+            self._sar3d_y_min_m.setValue(float(sar3d_state.y_min_m))
+            self._sar3d_y_max_m.setValue(float(sar3d_state.y_max_m))
+            self._sar3d_z_min_m.setValue(float(sar3d_state.z_min_m))
+            self._sar3d_z_max_m.setValue(float(sar3d_state.z_max_m))
+            self._sar3d_voxel_x_m.setValue(float(sar3d_state.voxel_x_m))
+            self._sar3d_voxel_y_m.setValue(float(sar3d_state.voxel_y_m))
+            self._sar3d_voxel_z_m.setValue(float(sar3d_state.voxel_z_m))
+            self._sar3d_norm_edge_margin_m.setValue(float(sar3d_state.norm_edge_margin_m))
+            self._sar3d_smooth_sigma.setValue(float(sar3d_state.smooth_sigma))
+            self._sar3d_comp_range_power.setValue(float(sar3d_state.comp_range_power))
+            self._sar3d_tx_per_segment.setValue(int(sar3d_state.tx_per_segment))
+            self._sar3d_use_compensation.setChecked(bool(sar3d_state.use_compensation))
+            self._sar3d_normalize_pairs.setChecked(bool(sar3d_state.normalize_pairs))
+            self._set_combo_current_text(
+                self._sar3d_bottom_view,
+                sar3d_bottom_view_label_from_deg(float(sar3d_state.bottom_view_deg)),
+            )
+
             self._save_count.setValue(int(gui_state.data_actions.save_count))
             self._record_count.setValue(int(gui_state.data_actions.record_count))
             self._save_path_input.setText(str(gui_state.data_actions.save_path))

python_app/gui/controllers/app_window_config/radar_limits_mixin.py

@@ -182,6 +182,8 @@ class AppWindowRadarLimitsMixin:
             "_gpr_stop_freq_mhz": "GPR Stop MHz",
             "_legacy_gpr_start_freq_mhz": "Legacy GPR Start MHz",
             "_legacy_gpr_stop_freq_mhz": "Legacy GPR Stop MHz",
+            "_sar3d_start_freq_mhz": "3D SAR Start MHz",
+            "_sar3d_stop_freq_mhz": "3D SAR Stop MHz",
         }
         widgets = [getattr(self, widget_name) for widget_name in widget_names]
         previous_values = {widget_name: getattr(self, widget_name).value() for widget_name in widget_names}
@@ -232,5 +234,7 @@ class AppWindowRadarLimitsMixin:
                 "_gpr_stop_freq_mhz",
                 "_legacy_gpr_start_freq_mhz",
                 "_legacy_gpr_stop_freq_mhz",
+                "_sar3d_start_freq_mhz",
+                "_sar3d_stop_freq_mhz",
             )
         )

python_app/gui/controllers/app_window_config/state_builders.py

@@ -13,6 +13,7 @@ from python_app.models.gui_profile_model import (
     GuiPreprocessDialogStateModel,
     GuiProcessingStateModel,
     GuiProfileModel,
+    GuiSar3dStateModel,
     GuiStateModel,
     GuiSwitchStateModel,
 )
@@ -24,6 +25,7 @@ from python_app.orchestration.preprocess_assets import (
     VISIBLE_PREPROCESS_ASSET_KEYS,
     preprocess_asset_model,
 )
+from python_app.gui.runtime.sar3d_views import sar3d_bottom_view_deg_from_label
 from python_app.storage.npz_store import radar_key_from_config
 
 
@@ -285,6 +287,10 @@ class AppWindowConfigStateBuildersMixin:
                     visible_z_min_m=0.0,
                     visible_z_max_m=14.0,
                 ),
+                sar3d=GuiSar3dStateModel(
+                    input_positions=self._default_gpr_input_positions_from_config(config),
+                    output_positions=self._default_gpr_output_positions_from_config(config),
+                ),
             ),
             data_actions=GuiDataActionsStateModel(
                 save_count=10,
@@ -418,6 +424,42 @@ class AppWindowConfigStateBuildersMixin:
                     visible_z_min_m=float(self._legacy_gpr_visible_z_min_m.value()),
                     visible_z_max_m=float(self._legacy_gpr_visible_z_max_m.value()),
                 ),
+                sar3d=GuiSar3dStateModel(
+                    input_positions=self._sar3d_input_positions_input.text().strip(),
+                    output_positions=self._sar3d_output_positions_input.text().strip(),
+                    min_depth_m=float(self._sar3d_min_depth_m.value()),
+                    max_depth_m=float(self._sar3d_max_depth_m.value()),
+                    start_freq_mhz=float(self._sar3d_start_freq_mhz.value()),
+                    stop_freq_mhz=float(self._sar3d_stop_freq_mhz.value()),
+                    speed_m_s=float(self._sar3d_speed_m_s.value()),
+                    ignore_socket_speed_enabled=bool(self._sar3d_ignore_socket_speed_enabled.isChecked()),
+                    look_angle_deg=float(self._sar3d_look_angle_deg.value()),
+                    direction_sign=float(self._sar3d_direction_sign.value()),
+                    apply_freq_phase_correction=bool(self._sar3d_apply_freq_phase_correction.isChecked()),
+                    frame_radius=int(self._sar3d_frame_radius.value()),
+                    edge_frame_weight=float(self._sar3d_edge_frame_weight.value()),
+                    pitch_override_enabled=bool(self._sar3d_pitch_override_enabled.isChecked()),
+                    pitch_deg=float(self._sar3d_pitch_deg.value()),
+                    ground_depth_m=float(self._sar3d_ground_depth_m.value()),
+                    x_min_m=float(self._sar3d_x_min_m.value()),
+                    x_max_m=float(self._sar3d_x_max_m.value()),
+                    y_min_m=float(self._sar3d_y_min_m.value()),
+                    y_max_m=float(self._sar3d_y_max_m.value()),
+                    z_min_m=float(self._sar3d_z_min_m.value()),
+                    z_max_m=float(self._sar3d_z_max_m.value()),
+                    voxel_x_m=float(self._sar3d_voxel_x_m.value()),
+                    voxel_y_m=float(self._sar3d_voxel_y_m.value()),
+                    voxel_z_m=float(self._sar3d_voxel_z_m.value()),
+                    norm_edge_margin_m=float(self._sar3d_norm_edge_margin_m.value()),
+                    smooth_sigma=float(self._sar3d_smooth_sigma.value()),
+                    comp_range_power=float(self._sar3d_comp_range_power.value()),
+                    tx_per_segment=int(self._sar3d_tx_per_segment.value()),
+                    use_compensation=bool(self._sar3d_use_compensation.isChecked()),
+                    normalize_pairs=bool(self._sar3d_normalize_pairs.isChecked()),
+                    bottom_view_deg=sar3d_bottom_view_deg_from_label(
+                        self._sar3d_bottom_view.currentText()
+                    ),
+                ),
             ),
             data_actions=GuiDataActionsStateModel(
                 save_count=int(self._save_count.value()),
@@ -472,7 +514,7 @@ class AppWindowConfigStateBuildersMixin:
                 combo_text = self._combos_text.text()
                 config.combos = parse_combos_from_text(combo_text)
                 config.ensure_combos()
-            if self._processing_mode.currentText() not in {"gpr", "legacy_gpr"} and self._switches_are_effectively_static(config):
+            if self._processing_mode.currentText() not in {"gpr", "legacy_gpr", "sar3d"} and self._switches_are_effectively_static(config):
                 config.combos = [ComboModel(input=0, output=0)]
 
         for key in PREPROCESS_ASSET_KEYS:

python_app/gui/controllers/app_window_plot/__init__.py

@@ -3,11 +3,13 @@
 from python_app.gui.controllers.app_window_plot.bscan_plot_mixin import AppWindowBscanPlotMixin
 from python_app.gui.controllers.app_window_plot.bscan_replay_mixin import AppWindowBscanReplayMixin
 from python_app.gui.controllers.app_window_plot.gpr_plot_mixin import AppWindowGprPlotMixin
+from python_app.gui.controllers.app_window_plot.sar3d_plot_mixin import AppWindowSar3dPlotMixin
 from python_app.gui.controllers.app_window_plot.trace_plot_mixin import AppWindowTracePlotMixin
 
 __all__ = [
     "AppWindowBscanPlotMixin",
     "AppWindowBscanReplayMixin",
     "AppWindowGprPlotMixin",
+    "AppWindowSar3dPlotMixin",
     "AppWindowTracePlotMixin",
 ]

python_app/gui/controllers/app_window_plot/sar3d_plot_mixin.py

@@ -0,0 +1,162 @@
+"""3D SAR projection rendering helpers.
+
+The sar3d processor publishes two normalized max-projections of the imaged
+volume as collection-level ImageF32 payloads, matching the legacy render
+conventions (X across, Z range/"вдаль", Y up):
+
+- ``sar3d_proj_xz`` — top view: X (m) horizontal, Z/range (m) vertical
+  (max over the height Y), like the classic GPR heatmap;
+- ``sar3d_proj_bottom`` — switchable bottom view: height Y (m) vertical, the
+  horizontal axis is the ground direction rotated by ``sar3d_bottom_view_deg``
+  around Y (0° = front view X, 90° = side view Z, 30°/60° in between);
+
+plus ``sar3d_peak`` (ScalarF32), the volume peak before normalization. Both
+projections are drawn on their own PlotWidgets stacked in one plot-stack page
+(top view on top), mirroring how the pass-through page stacks its two plots.
+"""
+
+from __future__ import annotations
+
+from PyQt6.QtCore import QRectF
+import numpy as np
+import pyqtgraph as pg
+
+from python_app.gui.runtime.sar3d_views import sar3d_bottom_view_deg_from_label
+from python_app.models.dataset_model import ResultCollection
+
+# Fraction of the projection maximum below which the heatmap is not highlighted
+# (same as cloud-threshold=0.75 in the VNA_AlGo 3D SAR animation): the color
+# scale is stretched over [frac, 1], everything below falls into the darkest
+# LUT color.
+HEATMAP_DISPLAY_THRESHOLD_FRAC = 0.75
+
+
+class AppWindowSar3dPlotMixin:
+    """Renders 3D SAR volume projections published by the sar3d processor."""
+
+    def _sar3d_bottom_view_labels(self) -> tuple[str, str]:
+        """Return (plot title, horizontal axis label) for the active bottom view.
+
+        The plot surfaces are created before the processing section builds the
+        bottom-view combo, so fall back to the front view until it exists.
+        """
+        combo = getattr(self, "_sar3d_bottom_view", None)
+        degrees = sar3d_bottom_view_deg_from_label(combo.currentText()) if combo is not None else 0.0
+        if degrees <= 1e-9:
+            return "3D SAR front view (X-Y)", "X"
+        if degrees >= 90.0 - 1e-9:
+            return "3D SAR side view (Z-Y)", "Range Z"
+        return f"3D SAR view @ {degrees:g}\N{DEGREE SIGN}", f"u({degrees:g}\N{DEGREE SIGN})"
+
+    def _configure_sar3d_plot_axes(self) -> None:
+        """Apply persistent axis labels and view settings to both projection plots."""
+        _bottom_title, bottom_x_label = self._sar3d_bottom_view_labels()
+        for plot, x_label, y_label in (
+            (self._sar3d_xz_plot, "X", "Range Z"),
+            (self._sar3d_xy_plot, bottom_x_label, "Height Y"),
+        ):
+            plot_item = plot.getPlotItem()
+            plot_item.showAxis("left", show=True)
+            plot_item.showAxis("bottom", show=True)
+            plot_item.setClipToView(True)
+            plot.setLabel("bottom", x_label, units="m")
+            plot.setLabel("left", y_label, units="m")
+            view_box = plot.getViewBox()
+            view_box.invertY(False)
+            view_box.enableAutoRange(x=False, y=False)
+            self._disable_gpr_plot_interaction(plot, view_box)
+
+    def _ensure_sar3d_plot_items(self) -> None:
+        """Create persistent projection image items once and reuse them on redraw."""
+        if self._sar3d_xz_image_item is not None:
+            return
+
+        self._configure_sar3d_plot_axes()
+        if self._sar3d_lookup_table is None:
+            # Same palette as the GPR accumulator so both imagers read alike.
+            self._sar3d_lookup_table = self._build_lut(["#081c15", "#1b4332", "#ffd166", "#f94144"])
+
+        self._sar3d_xz_image_item = pg.ImageItem(axisOrder="row-major")
+        self._sar3d_xz_image_item.setZValue(0)
+        self._sar3d_xz_image_item.hide()
+        self._sar3d_xz_plot.addItem(self._sar3d_xz_image_item)
+
+        self._sar3d_xy_image_item = pg.ImageItem(axisOrder="row-major")
+        self._sar3d_xy_image_item.setZValue(0)
+        self._sar3d_xy_image_item.hide()
+        self._sar3d_xy_plot.addItem(self._sar3d_xy_image_item)
+
+    def _clear_sar3d_plot(self) -> None:
+        """Clear both 3D SAR projection surfaces."""
+        if not hasattr(self, "_sar3d_xz_plot"):
+            return
+        self._configure_sar3d_plot_axes()
+        if self._sar3d_xz_image_item is not None:
+            self._sar3d_xz_image_item.hide()
+        if self._sar3d_xy_image_item is not None:
+            self._sar3d_xy_image_item.hide()
+        bottom_title, _bottom_x_label = self._sar3d_bottom_view_labels()
+        self._sar3d_xz_plot.setTitle("3D SAR top view (X-Z)")
+        self._sar3d_xy_plot.setTitle(bottom_title)
+
+    def _draw_sar3d_projection(self, plot: pg.PlotWidget, image_item: pg.ImageItem, payload) -> bool:
+        """Draw one normalized projection payload onto its plot; return success."""
+        image = np.asarray(payload.image, dtype=np.float32)
+        x_axis = np.asarray(payload.image_x_axis, dtype=np.float32)
+        y_axis = np.asarray(payload.image_y_axis, dtype=np.float32)
+        if image.ndim != 2 or image.size == 0 or x_axis.size == 0 or y_axis.size == 0:
+            image_item.hide()
+            return False
+
+        x_min = float(x_axis[0])
+        x_max = float(x_axis[-1])
+        y_min = float(y_axis[0])
+        y_max = float(y_axis[-1])
+        rect = QRectF(x_min, y_min, max(x_max - x_min, 1e-6), max(y_max - y_min, 1e-6))
+
+        image_item.setImage(image, autoLevels=False)
+        image_item.setRect(rect)
+        image_item.setLookupTable(self._sar3d_lookup_table)
+        # Projections are normalized to [0, 1] by the processor; stretch the
+        # colors over [threshold, 1] like the 3D animation cloud cutoff.
+        image_item.setLevels((HEATMAP_DISPLAY_THRESHOLD_FRAC, 1.0))
+        image_item.show()
+        plot.setXRange(x_min, x_max, padding=0.0)
+        plot.setYRange(y_min, y_max, padding=0.0)
+        return True
+
+    def _draw_sar3d_projections(self, collection: ResultCollection) -> bool:
+        """Draw the latest collection-level 3D SAR top and bottom projections."""
+        xz_payload = self._collection_payload_by_name(collection, "sar3d_proj_xz", kind=3)
+        bottom_payload = self._collection_payload_by_name(collection, "sar3d_proj_bottom", kind=3)
+        if xz_payload is None and bottom_payload is None:
+            self._clear_sar3d_plot()
+            return False
+
+        for plot in (self._sar3d_xz_plot, self._sar3d_xy_plot):
+            plot.setUpdatesEnabled(False)
+        try:
+            self._ensure_sar3d_plot_items()
+            # Axis labels track the bottom-view selector (payload axes change with it).
+            self._configure_sar3d_plot_axes()
+            xz_drawn = xz_payload is not None and self._draw_sar3d_projection(
+                self._sar3d_xz_plot, self._sar3d_xz_image_item, xz_payload
+            )
+            bottom_drawn = bottom_payload is not None and self._draw_sar3d_projection(
+                self._sar3d_xy_plot, self._sar3d_xy_image_item, bottom_payload
+            )
+            if not xz_drawn and not bottom_drawn:
+                self._clear_sar3d_plot()
+                return False
+
+            peak_payload = self._collection_payload_by_name(collection, "sar3d_peak", kind=2)
+            peak_suffix = ""
+            if peak_payload is not None:
+                peak_suffix = f" | peak={float(peak_payload.scalar_value):.3g}"
+            bottom_title, _bottom_x_label = self._sar3d_bottom_view_labels()
+            self._sar3d_xz_plot.setTitle(f"3D SAR top view (X-Z){peak_suffix}")
+            self._sar3d_xy_plot.setTitle(bottom_title)
+        finally:
+            for plot in (self._sar3d_xz_plot, self._sar3d_xy_plot):
+                plot.setUpdatesEnabled(True)
+        return True

python_app/gui/controllers/app_window_plot/trace_plot_mixin.py

@@ -78,7 +78,7 @@ class AppWindowTracePlotMixin:
 
     def _on_trace_visibility_changed(self, *_args) -> None:
         """Redraw pass-through traces when magnitude/phase toggles changed."""
-        if self._processing_mode.currentText() in {"bscan", "gpr", "legacy_gpr"}:
+        if self._processing_mode.currentText() in {"bscan", "gpr", "legacy_gpr", "sar3d"}:
             return
         if self._result_history:
             self._draw_results(self._result_history[-1])

python_app/gui/controllers/app_window_plot_mixin.py

@@ -6,6 +6,7 @@ from python_app.gui.controllers.app_window_plot import (
     AppWindowBscanPlotMixin,
     AppWindowBscanReplayMixin,
     AppWindowGprPlotMixin,
+    AppWindowSar3dPlotMixin,
     AppWindowTracePlotMixin,
 )
 from python_app.models.dataset_model import ResultCollection
@@ -16,8 +17,9 @@ class AppWindowPlotMixin(
     AppWindowBscanPlotMixin,
     AppWindowBscanReplayMixin,
     AppWindowGprPlotMixin,
+    AppWindowSar3dPlotMixin,
 ):
-    """Routes plotting to trace, B-scan, or GPR-specific mixins."""
+    """Routes plotting to trace, B-scan, GPR, or 3D SAR-specific mixins."""
 
     def _draw_preferred_collection(
         self,
@@ -35,6 +37,8 @@ class AppWindowPlotMixin(
             return self._draw_bscan_heatmap(collection)
         if self._processing_mode.currentText() in {"gpr", "legacy_gpr"}:
             return self._draw_gpr_map(collection)
+        if self._processing_mode.currentText() == "sar3d":
+            return self._draw_sar3d_projections(collection)
         return self._draw_trace_lines(collection)
 
     def _result_collection_has_trace(self, collection: ResultCollection) -> bool:

python_app/gui/controllers/app_window_ui_mixin.py

@@ -74,6 +74,7 @@ class AppWindowUiMixin:
         self._plot_stack = QStackedWidget(root)
         self._build_bscan_plot_page()
         self._build_gpr_plot_page()
+        self._build_sar3d_plot_page()
         self._build_trace_plot_page()
 
         # Default view on startup is pass-through traces.
@@ -139,6 +140,27 @@ class AppWindowUiMixin:
         self._configure_gpr_plot_axes()
         self._plot_stack.addWidget(self._gpr_plot)
 
+    def _build_sar3d_plot_page(self) -> None:
+        """Create 3D SAR page with stacked side (X-Z) and top (X-Y) projection plots."""
+        # 3D SAR surface: container with two projection heatmaps, mirroring the
+        # pass-through page layout (two stacked PlotWidgets on one stack page).
+        self._sar3d_plots_container = QWidget()
+        sar3d_layout = QVBoxLayout(self._sar3d_plots_container)
+        sar3d_layout.setContentsMargins(0, 0, 0, 0)
+        sar3d_layout.setSpacing(6)
+
+        self._sar3d_xz_plot = self._create_plot_widget(background="#0f141c")
+        self._sar3d_xz_plot.showGrid(x=True, y=True, alpha=0.2)
+        sar3d_layout.addWidget(self._sar3d_xz_plot, stretch=1)
+
+        self._sar3d_xy_plot = self._create_plot_widget(background="#0f141c")
+        self._sar3d_xy_plot.showGrid(x=True, y=True, alpha=0.2)
+        sar3d_layout.addWidget(self._sar3d_xy_plot, stretch=1)
+
+        self._configure_sar3d_plot_axes()
+        self._clear_sar3d_plot()
+        self._plot_stack.addWidget(self._sar3d_plots_container)
+
     def _build_settings_toggle(self, root_layout: QHBoxLayout) -> None:
         """Create narrow button used to collapse or show settings panel."""
         self._settings_toggle_button = QPushButton("<")
@@ -286,6 +308,7 @@ class AppWindowUiMixin:
 
         `bscan`   -> show `self._bscan_plot`
         `gpr` and `legacy_gpr` -> show `self._gpr_plot`
+        `sar3d`   -> show `self._sar3d_plots_container`
         otherwise -> show `self._trace_plots_container`
         """
         if mode == "bscan":
@@ -294,6 +317,9 @@ class AppWindowUiMixin:
         if mode in {"gpr", "legacy_gpr"}:
             self._plot_stack.setCurrentWidget(self._gpr_plot)
             return
+        if mode == "sar3d":
+            self._plot_stack.setCurrentWidget(self._sar3d_plots_container)
+            return
         self._plot_stack.setCurrentWidget(self._trace_plots_container)
 
     @staticmethod

python_app/gui/controllers/sections/processing_section.py

@@ -20,6 +20,10 @@ from PyQt6.QtWidgets import (
 
 from python_app.gui.controllers.app_window_config.state_builders import GUI_SAVE_HISTORY_LIMIT
 from python_app.gui.controllers.sections.layout_helpers import FormRow, build_two_column_form_widget
+from python_app.gui.runtime.sar3d_views import (
+    SAR3D_BOTTOM_VIEW_CHOICES,
+    sar3d_bottom_view_label_from_deg,
+)
 
 
 def _format_geometry_row(position: int, x_m: float, y_m: float, z_m: float) -> str:
@@ -59,7 +63,7 @@ def _build_processing_mode_page(parent: QStackedWidget, rows: list[FormRow], *,
 
 
 def build_processing_group(owner) -> QGroupBox:
-    """Create processing mode section with pass-through, B-scan, and GPR pages."""
+    """Create processing mode section with pass-through, B-scan, GPR, and 3D SAR pages."""
     group = QGroupBox("Processing")
     form = QFormLayout(group)
     form.setFieldGrowthPolicy(QFormLayout.FieldGrowthPolicy.AllNonFixedFieldsGrow)
@@ -68,9 +72,10 @@ def build_processing_group(owner) -> QGroupBox:
     bscan_defaults = processing_defaults.bscan
     gpr_live_defaults = processing_defaults.gpr
     legacy_gpr_defaults = processing_defaults.legacy_gpr
+    sar3d_defaults = processing_defaults.sar3d
 
     owner._processing_mode = QComboBox()
-    owner._processing_mode.addItems(["pass_through", "bscan", "gpr", "legacy_gpr"])
+    owner._processing_mode.addItems(["pass_through", "bscan", "gpr", "legacy_gpr", "sar3d"])
     owner._set_combo_current_text(owner._processing_mode, processing_defaults.selected_mode)
 
     owner._processing_mode_pages = QStackedWidget(group)
@@ -570,6 +575,258 @@ def build_processing_group(owner) -> QGroupBox:
     )
     owner._processing_mode_pages.addWidget(legacy_gpr_page)
 
+    # 3D SAR page: shared gpr_* knobs get their own widget set (like legacy_gpr)
+    # plus the sar3d-specific aperture/volume knobs consumed by the C++ processor.
+    owner._sar3d_input_positions_input = QLineEdit(str(sar3d_defaults.input_positions))
+    owner._sar3d_input_positions_input.setPlaceholderText("0,1,2")
+
+    owner._sar3d_output_positions_input = QLineEdit(str(sar3d_defaults.output_positions))
+    owner._sar3d_output_positions_input.setPlaceholderText("0,1")
+
+    owner._sar3d_min_depth_m = QDoubleSpinBox()
+    owner._sar3d_min_depth_m.setDecimals(2)
+    owner._sar3d_min_depth_m.setRange(0.0, 50.0)
+    owner._sar3d_min_depth_m.setSingleStep(0.1)
+    owner._sar3d_min_depth_m.setValue(float(sar3d_defaults.min_depth_m))
+
+    owner._sar3d_max_depth_m = QDoubleSpinBox()
+    owner._sar3d_max_depth_m.setDecimals(2)
+    owner._sar3d_max_depth_m.setRange(0.1, 50.0)
+    owner._sar3d_max_depth_m.setSingleStep(0.1)
+    owner._sar3d_max_depth_m.setValue(float(sar3d_defaults.max_depth_m))
+
+    owner._sar3d_start_freq_mhz = QDoubleSpinBox()
+    owner._sar3d_start_freq_mhz.setDecimals(1)
+    owner._sar3d_start_freq_mhz.setRange(100.0, 8800.0)
+    owner._sar3d_start_freq_mhz.setSingleStep(10.0)
+    owner._sar3d_start_freq_mhz.setValue(float(sar3d_defaults.start_freq_mhz))
+
+    owner._sar3d_stop_freq_mhz = QDoubleSpinBox()
+    owner._sar3d_stop_freq_mhz.setDecimals(1)
+    owner._sar3d_stop_freq_mhz.setRange(100.0, 8800.0)
+    owner._sar3d_stop_freq_mhz.setSingleStep(10.0)
+    owner._sar3d_stop_freq_mhz.setValue(float(sar3d_defaults.stop_freq_mhz))
+
+    owner._sar3d_look_angle_deg = QDoubleSpinBox()
+    owner._sar3d_look_angle_deg.setDecimals(2)
+    owner._sar3d_look_angle_deg.setRange(-90.0, 90.0)
+    owner._sar3d_look_angle_deg.setSingleStep(0.5)
+    owner._sar3d_look_angle_deg.setValue(float(sar3d_defaults.look_angle_deg))
+    owner._sar3d_look_angle_deg.setToolTip(
+        "Radar look angle vs the range axis (deg). Used by intra-sweep motion correction."
+    )
+
+    owner._sar3d_direction_sign = QDoubleSpinBox()
+    owner._sar3d_direction_sign.setDecimals(0)
+    owner._sar3d_direction_sign.setRange(-1.0, 1.0)
+    owner._sar3d_direction_sign.setSingleStep(2.0)
+    owner._sar3d_direction_sign.setValue(float(sar3d_defaults.direction_sign))
+    owner._sar3d_direction_sign.setToolTip(
+        "Motion direction along range: +1 (later frequencies deeper) or -1 (shallower)."
+    )
+
+    owner._sar3d_ignore_socket_speed_enabled = QCheckBox("Ignore socket speed")
+    owner._sar3d_ignore_socket_speed_enabled.setChecked(bool(sar3d_defaults.ignore_socket_speed_enabled))
+    owner._sar3d_ignore_socket_speed_enabled.setToolTip(
+        "When checked, use the speed below for motion correction instead of the "
+        "value streamed over the locator socket."
+    )
+
+    owner._sar3d_speed_m_s = QDoubleSpinBox()
+    owner._sar3d_speed_m_s.setDecimals(3)
+    owner._sar3d_speed_m_s.setRange(-100.0, 100.0)
+    owner._sar3d_speed_m_s.setSingleStep(0.05)
+    owner._sar3d_speed_m_s.setValue(float(sar3d_defaults.speed_m_s))
+    owner._sar3d_speed_m_s.setToolTip(
+        "Radar speed (m/s) used by intra-sweep motion correction when 'Ignore socket speed' is on."
+    )
+
+    owner._sar3d_apply_freq_phase_correction = QCheckBox("Apply intra-sweep phase correction")
+    owner._sar3d_apply_freq_phase_correction.setChecked(bool(sar3d_defaults.apply_freq_phase_correction))
+
+    owner._sar3d_frame_radius = QSpinBox()
+    owner._sar3d_frame_radius.setRange(0, 25)
+    owner._sar3d_frame_radius.setValue(int(sar3d_defaults.frame_radius))
+    owner._sar3d_frame_radius.setToolTip(
+        "Synthetic-aperture half width in frames: 2*radius+1 consecutive frames form one aperture."
+    )
+
+    owner._sar3d_edge_frame_weight = QDoubleSpinBox()
+    owner._sar3d_edge_frame_weight.setDecimals(2)
+    owner._sar3d_edge_frame_weight.setRange(0.0, 1.0)
+    owner._sar3d_edge_frame_weight.setSingleStep(0.05)
+    owner._sar3d_edge_frame_weight.setValue(float(sar3d_defaults.edge_frame_weight))
+    owner._sar3d_edge_frame_weight.setToolTip(
+        "Weight of the outermost aperture frames (1 = flat window, 0 = strong taper)."
+    )
+
+    owner._sar3d_pitch_override_enabled = QCheckBox("Override pitch")
+    owner._sar3d_pitch_override_enabled.setChecked(bool(sar3d_defaults.pitch_override_enabled))
+    owner._sar3d_pitch_override_enabled.setToolTip(
+        "When unchecked, the frame pitch follows the look angle (notebook "
+        "BP_GROUND_PITCH_DEG = None); check to set it separately below."
+    )
+
+    owner._sar3d_pitch_deg = QDoubleSpinBox()
+    owner._sar3d_pitch_deg.setDecimals(2)
+    owner._sar3d_pitch_deg.setRange(-90.0, 90.0)
+    owner._sar3d_pitch_deg.setSingleStep(0.5)
+    owner._sar3d_pitch_deg.setValue(float(sar3d_defaults.pitch_deg))
+    owner._sar3d_pitch_deg.setToolTip(
+        "Frame pitch (deg) used for ground coordinates and aperture offsets when the override is on."
+    )
+
+    owner._sar3d_ground_depth_m = QDoubleSpinBox()
+    owner._sar3d_ground_depth_m.setDecimals(2)
+    owner._sar3d_ground_depth_m.setRange(0.0, 10.0)
+    owner._sar3d_ground_depth_m.setSingleStep(0.05)
+    owner._sar3d_ground_depth_m.setValue(float(sar3d_defaults.ground_depth_m))
+    owner._sar3d_ground_depth_m.setToolTip(
+        "Height of the lower antenna row above the ground (m); scene Y=0 is the ground."
+    )
+
+    owner._sar3d_x_min_m = QDoubleSpinBox()
+    owner._sar3d_x_min_m.setDecimals(2)
+    owner._sar3d_x_min_m.setRange(-50.0, 50.0)
+    owner._sar3d_x_min_m.setSingleStep(0.1)
+    owner._sar3d_x_min_m.setValue(float(sar3d_defaults.x_min_m))
+
+    owner._sar3d_x_max_m = QDoubleSpinBox()
+    owner._sar3d_x_max_m.setDecimals(2)
+    owner._sar3d_x_max_m.setRange(-50.0, 50.0)
+    owner._sar3d_x_max_m.setSingleStep(0.1)
+    owner._sar3d_x_max_m.setValue(float(sar3d_defaults.x_max_m))
+
+    owner._sar3d_z_min_m = QDoubleSpinBox()
+    owner._sar3d_z_min_m.setDecimals(2)
+    owner._sar3d_z_min_m.setRange(-50.0, 50.0)
+    owner._sar3d_z_min_m.setSingleStep(0.1)
+    owner._sar3d_z_min_m.setValue(float(sar3d_defaults.z_min_m))
+
+    owner._sar3d_z_max_m = QDoubleSpinBox()
+    owner._sar3d_z_max_m.setDecimals(2)
+    owner._sar3d_z_max_m.setRange(-50.0, 50.0)
+    owner._sar3d_z_max_m.setSingleStep(0.1)
+    owner._sar3d_z_max_m.setValue(float(sar3d_defaults.z_max_m))
+
+    owner._sar3d_y_min_m = QDoubleSpinBox()
+    owner._sar3d_y_min_m.setDecimals(2)
+    owner._sar3d_y_min_m.setRange(-10.0, 10.0)
+    owner._sar3d_y_min_m.setSingleStep(0.1)
+    owner._sar3d_y_min_m.setValue(float(sar3d_defaults.y_min_m))
+
+    owner._sar3d_y_max_m = QDoubleSpinBox()
+    owner._sar3d_y_max_m.setDecimals(2)
+    owner._sar3d_y_max_m.setRange(-10.0, 10.0)
+    owner._sar3d_y_max_m.setSingleStep(0.1)
+    owner._sar3d_y_max_m.setValue(float(sar3d_defaults.y_max_m))
+
+    owner._sar3d_voxel_x_m = QDoubleSpinBox()
+    owner._sar3d_voxel_x_m.setDecimals(3)
+    owner._sar3d_voxel_x_m.setRange(0.005, 1.0)
+    owner._sar3d_voxel_x_m.setSingleStep(0.005)
+    owner._sar3d_voxel_x_m.setValue(float(sar3d_defaults.voxel_x_m))
+
+    owner._sar3d_voxel_y_m = QDoubleSpinBox()
+    owner._sar3d_voxel_y_m.setDecimals(3)
+    owner._sar3d_voxel_y_m.setRange(0.005, 1.0)
+    owner._sar3d_voxel_y_m.setSingleStep(0.005)
+    owner._sar3d_voxel_y_m.setValue(float(sar3d_defaults.voxel_y_m))
+
+    owner._sar3d_voxel_z_m = QDoubleSpinBox()
+    owner._sar3d_voxel_z_m.setDecimals(3)
+    owner._sar3d_voxel_z_m.setRange(0.005, 1.0)
+    owner._sar3d_voxel_z_m.setSingleStep(0.005)
+    owner._sar3d_voxel_z_m.setValue(float(sar3d_defaults.voxel_z_m))
+
+    owner._sar3d_norm_edge_margin_m = QDoubleSpinBox()
+    owner._sar3d_norm_edge_margin_m.setDecimals(2)
+    owner._sar3d_norm_edge_margin_m.setRange(0.0, 5.0)
+    owner._sar3d_norm_edge_margin_m.setSingleStep(0.05)
+    owner._sar3d_norm_edge_margin_m.setValue(float(sar3d_defaults.norm_edge_margin_m))
+    owner._sar3d_norm_edge_margin_m.setToolTip(
+        "Grid Y edges excluded from volume normalization (constant-range ridge)."
+    )
+
+    owner._sar3d_smooth_sigma = QDoubleSpinBox()
+    owner._sar3d_smooth_sigma.setDecimals(2)
+    owner._sar3d_smooth_sigma.setRange(0.0, 10.0)
+    owner._sar3d_smooth_sigma.setSingleStep(0.25)
+    owner._sar3d_smooth_sigma.setValue(float(sar3d_defaults.smooth_sigma))
+    owner._sar3d_smooth_sigma.setToolTip("Gaussian smoothing sigma over (Z, X) planes, voxels.")
+
+    owner._sar3d_comp_range_power = QDoubleSpinBox()
+    owner._sar3d_comp_range_power.setDecimals(2)
+    owner._sar3d_comp_range_power.setRange(0.0, 2.0)
+    owner._sar3d_comp_range_power.setSingleStep(0.05)
+    owner._sar3d_comp_range_power.setValue(float(sar3d_defaults.comp_range_power))
+    owner._sar3d_comp_range_power.setToolTip("Geometric spreading compensation power.")
+
+    owner._sar3d_tx_per_segment = QSpinBox()
+    owner._sar3d_tx_per_segment.setRange(1, 64)
+    owner._sar3d_tx_per_segment.setValue(int(sar3d_defaults.tx_per_segment))
+    owner._sar3d_tx_per_segment.setToolTip(
+        "Fallback Tx-per-segment split of a frame when per-trace capture stamps are absent."
+    )
+
+    owner._sar3d_use_compensation = QCheckBox("Use per-voxel compensation")
+    owner._sar3d_use_compensation.setChecked(bool(sar3d_defaults.use_compensation))
+
+    owner._sar3d_normalize_pairs = QCheckBox("Normalize Tx/Rx pairs")
+    owner._sar3d_normalize_pairs.setChecked(bool(sar3d_defaults.normalize_pairs))
+
+    owner._sar3d_bottom_view = QComboBox()
+    owner._sar3d_bottom_view.addItems([label for label, _deg in SAR3D_BOTTOM_VIEW_CHOICES])
+    owner._set_combo_current_text(
+        owner._sar3d_bottom_view,
+        sar3d_bottom_view_label_from_deg(float(sar3d_defaults.bottom_view_deg)),
+    )
+    owner._sar3d_bottom_view.setToolTip(
+        "Bottom plot projection: front view (X-Y), side view (Z-Y) or an "
+        "intermediate rotation around the vertical axis. The top plot always "
+        "shows the X-Z top view."
+    )
+
+    sar3d_page = _build_processing_mode_page(
+        owner._processing_mode_pages,
+        [
+            ("Input positions", owner._sar3d_input_positions_input),
+            ("Output positions", owner._sar3d_output_positions_input),
+            ("Min depth m", owner._sar3d_min_depth_m),
+            ("Max depth m", owner._sar3d_max_depth_m),
+            ("Start MHz", owner._sar3d_start_freq_mhz),
+            ("Stop MHz", owner._sar3d_stop_freq_mhz),
+            ("Look angle deg", owner._sar3d_look_angle_deg),
+            ("Direction sign", owner._sar3d_direction_sign),
+            owner._sar3d_ignore_socket_speed_enabled,
+            ("Speed m/s", owner._sar3d_speed_m_s),
+            owner._sar3d_apply_freq_phase_correction,
+            ("Frame radius", owner._sar3d_frame_radius),
+            ("Edge frame weight", owner._sar3d_edge_frame_weight),
+            owner._sar3d_pitch_override_enabled,
+            ("Pitch deg", owner._sar3d_pitch_deg),
+            ("Ground depth m", owner._sar3d_ground_depth_m),
+            ("X min m", owner._sar3d_x_min_m),
+            ("X max m", owner._sar3d_x_max_m),
+            ("Y min m", owner._sar3d_y_min_m),
+            ("Y max m", owner._sar3d_y_max_m),
+            ("Z min m", owner._sar3d_z_min_m),
+            ("Z max m", owner._sar3d_z_max_m),
+            ("Voxel X m", owner._sar3d_voxel_x_m),
+            ("Voxel Y m", owner._sar3d_voxel_y_m),
+            ("Voxel Z m", owner._sar3d_voxel_z_m),
+            ("Norm edge margin m", owner._sar3d_norm_edge_margin_m),
+            ("Smooth sigma", owner._sar3d_smooth_sigma),
+            ("Comp range power", owner._sar3d_comp_range_power),
+            ("Tx per segment", owner._sar3d_tx_per_segment),
+            ("Bottom view", owner._sar3d_bottom_view),
+            owner._sar3d_use_compensation,
+            owner._sar3d_normalize_pairs,
+        ],
+        split_index=13,
+    )
+    owner._processing_mode_pages.addWidget(sar3d_page)
+
     owner._processing_mode.currentTextChanged.connect(owner._on_processing_mode_changed)
     owner._show_magnitude_checkbox.toggled.connect(owner._on_trace_visibility_changed)
     owner._show_phase_checkbox.toggled.connect(owner._on_trace_visibility_changed)
@@ -642,6 +899,38 @@ def build_processing_group(owner) -> QGroupBox:
     owner._legacy_gpr_visible_x_max_m.valueChanged.connect(owner._on_gpr_locator_window_changed)
     owner._legacy_gpr_visible_z_min_m.valueChanged.connect(owner._on_gpr_locator_window_changed)
     owner._legacy_gpr_visible_z_max_m.valueChanged.connect(owner._on_gpr_locator_window_changed)
+    owner._sar3d_input_positions_input.editingFinished.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_output_positions_input.editingFinished.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_min_depth_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_max_depth_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_start_freq_mhz.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_stop_freq_mhz.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_look_angle_deg.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_direction_sign.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_ignore_socket_speed_enabled.toggled.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_speed_m_s.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_apply_freq_phase_correction.toggled.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_frame_radius.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_edge_frame_weight.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_pitch_override_enabled.toggled.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_pitch_deg.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_ground_depth_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_x_min_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_x_max_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_z_min_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_z_max_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_y_min_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_y_max_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_voxel_x_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_voxel_y_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_voxel_z_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_norm_edge_margin_m.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_smooth_sigma.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_comp_range_power.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_tx_per_segment.valueChanged.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_use_compensation.toggled.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_normalize_pairs.toggled.connect(owner._on_processing_live_settings_changed)
+    owner._sar3d_bottom_view.currentTextChanged.connect(owner._on_processing_live_settings_changed)
 
     owner._set_processing_mode_page(owner._processing_mode.currentText())
     return group

python_app/gui/runtime/constraints.py

@@ -24,7 +24,9 @@ def validate_processing_mode_constraints(
             )
         return
 
-    if processing_mode not in {"gpr", "legacy_gpr"}:
+    # sar3d shares the GPR combo/geometry requirements: it images from the same
+    # multi-Tx/Rx pair set selected through the gpr_* live-config fields.
+    if processing_mode not in {"gpr", "legacy_gpr", "sar3d"}:
         return
 
     configured_combos = {(int(combo.input), int(combo.output)) for combo in config.combos}

python_app/gui/runtime/sar3d_views.py

@@ -0,0 +1,30 @@
+"""Shared mapping for the sar3d bottom-view projection choices.
+
+The bottom plot of the sar3d mode projects the imaged volume along a
+horizontal direction rotated around the vertical Y axis: 0° = front view
+(X horizontal), 90° = side view (Z horizontal). One shared mapping keeps the
+combo box, the live-config build, the profile persistence and the plot labels
+consistent.
+"""
+
+from __future__ import annotations
+
+SAR3D_BOTTOM_VIEW_CHOICES: tuple[tuple[str, float], ...] = (
+    ("front (0°)", 0.0),
+    ("30°", 30.0),
+    ("60°", 60.0),
+    ("side (90°)", 90.0),
+)
+
+
+def sar3d_bottom_view_deg_from_label(label: str) -> float:
+    """Map a bottom-view combo label to its projection angle in degrees."""
+    for choice_label, degrees in SAR3D_BOTTOM_VIEW_CHOICES:
+        if choice_label == label:
+            return degrees
+    return 0.0
+
+
+def sar3d_bottom_view_label_from_deg(degrees: float) -> str:
+    """Map a projection angle to the nearest bottom-view combo label."""
+    return min(SAR3D_BOTTOM_VIEW_CHOICES, key=lambda choice: abs(choice[1] - float(degrees)))[0]

python_app/hardware_full/laser_control/exceptions.py

@@ -68,6 +68,24 @@ class PortNotFoundError(CommunicationError):
         super().__init__(message)
 
 
+class PortBusyError(CommunicationError):
+    """Raised when the serial port is already held by another program.
+
+    A laser controller is a single half-duplex request/response bus: only one
+    process may own it at a time. When the port is opened exclusively
+    (``exclusive=True``), a second exclusive open fails with this error instead
+    of silently sharing the bus and corrupting both sides' traffic.
+    """
+
+    def __init__(self, port: str = None):
+        target = f"'{port}'" if port else "the laser controller port"
+        super().__init__(
+            f"Serial port {target} is busy — another program is already using "
+            f"the laser controller. Close it first (only one program may own the "
+            f"port at a time)."
+        )
+
+
 class DeviceNotRespondingError(CommunicationError):
     """Exception raised when device doesn't respond to commands."""
 

python_app/hardware_full/laser_control/protocol.py

@@ -33,6 +33,7 @@ from .models import Measurements, VariationType
 from .exceptions import (
     CommunicationError,
     PortNotFoundError,
+    PortBusyError,
     CRCError,
     ProtocolError,
 )
@@ -184,20 +185,36 @@ class Protocol:
     # ---- Connection management
 
     def connect(self) -> None:
-        """Open the serial port. Auto-detects the device path when port is None."""
+        """Open the serial port. Auto-detects the device path when port is None.
+
+        The port is opened with ``exclusive=True`` so only one program can own the
+        laser controller at a time. This is required because the board is a single
+        half-duplex request/response bus: if two processes opened it, their
+        commands and responses would interleave and corrupt each other. A second
+        opener fails fast with :class:`PortBusyError` instead of silently sharing
+        the bus. Note the lock is advisory (``flock``): every program that opens
+        this port must also use ``exclusive=True`` for the guarantee to hold.
+        """
         port = self._port_name or self._detect_port()
         try:
             self._serial = serial.Serial(
                 port=port,
                 baudrate=BAUDRATE,
                 timeout=SERIAL_TIMEOUT_SEC,
+                exclusive=True,
             )
+        except serial.SerialException as exc:
+            # pyserial raises SerialException with errno EAGAIN/EWOULDBLOCK (11)
+            # when another process already holds the exclusive flock.
+            if getattr(exc, "errno", None) in (11,) or "exclusively lock" in str(exc).lower():
+                logger.error("Laser serial port '%s' is busy (held by another program)", port)
+                raise PortBusyError(port) from exc
+            logger.error("Cannot open laser serial port '%s': %s", port, exc)
+            raise CommunicationError(f"Cannot connect to port '{port}': {exc}") from exc
         except Exception as exc:
             logger.error("Cannot open laser serial port '%s': %s", port, exc)
-            raise CommunicationError(
-                f"Cannot connect to port '{port}': {exc}"
-            ) from exc
-        logger.debug("Laser serial port opened: %s @ %d baud", port, BAUDRATE)
+            raise CommunicationError(f"Cannot connect to port '{port}': {exc}") from exc
+        logger.debug("Laser serial port opened (exclusive): %s @ %d baud", port, BAUDRATE)
 
     def disconnect(self) -> None:
         """Close the serial port if open."""

python_app/models/gui_profile_codec.py

@@ -14,6 +14,7 @@ from python_app.models.gui_profile_schema import (
     GuiPreprocessDialogStateModel,
     GuiProcessingStateModel,
     GuiProfileModel,
+    GuiSar3dStateModel,
     GuiStateModel,
     GuiSwitchStateModel,
 )
@@ -106,6 +107,7 @@ def gui_profile_from_dict(payload: dict[str, Any]) -> GuiProfileModel:
     bscan_object = _as_dict(processing_object.get("bscan"), "gui.processing.bscan")
     gpr_object = _as_dict(processing_object.get("gpr"), "gui.processing.gpr")
     legacy_gpr_object = _as_dict(processing_object.get("legacy_gpr"), "gui.processing.legacy_gpr")
+    sar3d_object = _as_dict(processing_object.get("sar3d"), "gui.processing.sar3d")
     root_gpr_object = payload.get("gpr")
 
     selected_mode = _optional_string(
@@ -452,9 +454,205 @@ def gui_profile_from_dict(payload: dict[str, Any]) -> GuiProfileModel:
             visible_z_min_m=legacy_float("visible_z_min_m", gui.processing.legacy_gpr.visible_z_min_m),
             visible_z_max_m=legacy_float("visible_z_max_m", gui.processing.legacy_gpr.visible_z_max_m),
         ),
+        sar3d=GuiSar3dStateModel(
+            input_positions=_optional_string(
+                sar3d_object,
+                "input_positions",
+                gui.processing.sar3d.input_positions,
+                "gui.processing.sar3d",
+            ),
+            output_positions=_optional_string(
+                sar3d_object,
+                "output_positions",
+                gui.processing.sar3d.output_positions,
+                "gui.processing.sar3d",
+            ),
+            min_depth_m=_optional_float(
+                sar3d_object,
+                "min_depth_m",
+                gui.processing.sar3d.min_depth_m,
+                "gui.processing.sar3d",
+            ),
+            max_depth_m=_optional_float(
+                sar3d_object,
+                "max_depth_m",
+                gui.processing.sar3d.max_depth_m,
+                "gui.processing.sar3d",
+            ),
+            start_freq_mhz=_optional_float(
+                sar3d_object,
+                "start_freq_mhz",
+                gui.processing.sar3d.start_freq_mhz,
+                "gui.processing.sar3d",
+            ),
+            stop_freq_mhz=_optional_float(
+                sar3d_object,
+                "stop_freq_mhz",
+                gui.processing.sar3d.stop_freq_mhz,
+                "gui.processing.sar3d",
+            ),
+            speed_m_s=_optional_float(
+                sar3d_object,
+                "speed_m_s",
+                gui.processing.sar3d.speed_m_s,
+                "gui.processing.sar3d",
+            ),
+            ignore_socket_speed_enabled=_optional_bool(
+                sar3d_object,
+                "ignore_socket_speed_enabled",
+                gui.processing.sar3d.ignore_socket_speed_enabled,
+                "gui.processing.sar3d",
+            ),
+            look_angle_deg=_optional_float(
+                sar3d_object,
+                "look_angle_deg",
+                gui.processing.sar3d.look_angle_deg,
+                "gui.processing.sar3d",
+            ),
+            direction_sign=_optional_float(
+                sar3d_object,
+                "direction_sign",
+                gui.processing.sar3d.direction_sign,
+                "gui.processing.sar3d",
+            ),
+            apply_freq_phase_correction=_optional_bool(
+                sar3d_object,
+                "apply_freq_phase_correction",
+                gui.processing.sar3d.apply_freq_phase_correction,
+                "gui.processing.sar3d",
+            ),
+            frame_radius=_optional_int(
+                sar3d_object,
+                "frame_radius",
+                gui.processing.sar3d.frame_radius,
+                "gui.processing.sar3d",
+            ),
+            edge_frame_weight=_optional_float(
+                sar3d_object,
+                "edge_frame_weight",
+                gui.processing.sar3d.edge_frame_weight,
+                "gui.processing.sar3d",
+            ),
+            pitch_override_enabled=_optional_bool(
+                sar3d_object,
+                "pitch_override_enabled",
+                gui.processing.sar3d.pitch_override_enabled,
+                "gui.processing.sar3d",
+            ),
+            pitch_deg=_optional_float(
+                sar3d_object,
+                "pitch_deg",
+                gui.processing.sar3d.pitch_deg,
+                "gui.processing.sar3d",
+            ),
+            ground_depth_m=_optional_float(
+                sar3d_object,
+                "ground_depth_m",
+                gui.processing.sar3d.ground_depth_m,
+                "gui.processing.sar3d",
+            ),
+            x_min_m=_optional_float(
+                sar3d_object,
+                "x_min_m",
+                gui.processing.sar3d.x_min_m,
+                "gui.processing.sar3d",
+            ),
+            x_max_m=_optional_float(
+                sar3d_object,
+                "x_max_m",
+                gui.processing.sar3d.x_max_m,
+                "gui.processing.sar3d",
+            ),
+            y_min_m=_optional_float(
+                sar3d_object,
+                "y_min_m",
+                gui.processing.sar3d.y_min_m,
+                "gui.processing.sar3d",
+            ),
+            y_max_m=_optional_float(
+                sar3d_object,
+                "y_max_m",
+                gui.processing.sar3d.y_max_m,
+                "gui.processing.sar3d",
+            ),
+            z_min_m=_optional_float(
+                sar3d_object,
+                "z_min_m",
+                gui.processing.sar3d.z_min_m,
+                "gui.processing.sar3d",
+            ),
+            z_max_m=_optional_float(
+                sar3d_object,
+                "z_max_m",
+                gui.processing.sar3d.z_max_m,
+                "gui.processing.sar3d",
+            ),
+            voxel_x_m=_optional_float(
+                sar3d_object,
+                "voxel_x_m",
+                gui.processing.sar3d.voxel_x_m,
+                "gui.processing.sar3d",
+            ),
+            voxel_y_m=_optional_float(
+                sar3d_object,
+                "voxel_y_m",
+                gui.processing.sar3d.voxel_y_m,
+                "gui.processing.sar3d",
+            ),
+            voxel_z_m=_optional_float(
+                sar3d_object,
+                "voxel_z_m",
+                gui.processing.sar3d.voxel_z_m,
+                "gui.processing.sar3d",
+            ),
+            norm_edge_margin_m=_optional_float(
+                sar3d_object,
+                "norm_edge_margin_m",
+                gui.processing.sar3d.norm_edge_margin_m,
+                "gui.processing.sar3d",
+            ),
+            smooth_sigma=_optional_float(
+                sar3d_object,
+                "smooth_sigma",
+                gui.processing.sar3d.smooth_sigma,
+                "gui.processing.sar3d",
+            ),
+            comp_range_power=_optional_float(
+                sar3d_object,
+                "comp_range_power",
+                gui.processing.sar3d.comp_range_power,
+                "gui.processing.sar3d",
+            ),
+            tx_per_segment=_optional_int(
+                sar3d_object,
+                "tx_per_segment",
+                gui.processing.sar3d.tx_per_segment,
+                "gui.processing.sar3d",
+            ),
+            use_compensation=_optional_bool(
+                sar3d_object,
+                "use_compensation",
+                gui.processing.sar3d.use_compensation,
+                "gui.processing.sar3d",
+            ),
+            normalize_pairs=_optional_bool(
+                sar3d_object,
+                "normalize_pairs",
+                gui.processing.sar3d.normalize_pairs,
+                "gui.processing.sar3d",
+            ),
+            bottom_view_deg=_optional_float(
+                sar3d_object,
+                "bottom_view_deg",
+                gui.processing.sar3d.bottom_view_deg,
+                "gui.processing.sar3d",
+            ),
+        ),
     )
-    if gui.processing.selected_mode not in {"pass_through", "bscan", "gpr", "legacy_gpr"}:
-        raise ValueError("gui.processing.selected_mode must be one of: pass_through, bscan, gpr, legacy_gpr")
+    if gui.processing.selected_mode not in {"pass_through", "bscan", "gpr", "legacy_gpr", "sar3d"}:
+        raise ValueError(
+            "gui.processing.selected_mode must be one of: pass_through, bscan, gpr, legacy_gpr, sar3d"
+        )
     if gui.processing.bscan.axis not in {"abs", "real", "phase"}:
         raise ValueError("gui.processing.bscan.axis must be one of: abs, real, phase")
     if gui.processing.gpr.render_mode not in {"heatmap", "objects_only"}:
@@ -489,6 +687,22 @@ def gui_profile_from_dict(payload: dict[str, Any]) -> GuiProfileModel:
         raise ValueError("gui.processing.legacy_gpr.snr_comp_max must be >= 0")
     if gui.processing.legacy_gpr.min_visible_pair_count < 1:
         raise ValueError("gui.processing.legacy_gpr.min_visible_pair_count must be >= 1")
+    if gui.processing.sar3d.frame_radius < 0:
+        raise ValueError("gui.processing.sar3d.frame_radius must be >= 0")
+    if not 0.0 <= gui.processing.sar3d.edge_frame_weight <= 1.0:
+        raise ValueError("gui.processing.sar3d.edge_frame_weight must be within [0, 1]")
+    if min(gui.processing.sar3d.voxel_x_m, gui.processing.sar3d.voxel_y_m, gui.processing.sar3d.voxel_z_m) <= 0.0:
+        raise ValueError("gui.processing.sar3d.voxel_x/y/z_m must each be > 0")
+    if gui.processing.sar3d.x_max_m <= gui.processing.sar3d.x_min_m:
+        raise ValueError("gui.processing.sar3d.x_max_m must be > x_min_m")
+    if gui.processing.sar3d.y_max_m <= gui.processing.sar3d.y_min_m:
+        raise ValueError("gui.processing.sar3d.y_max_m must be > y_min_m")
+    if gui.processing.sar3d.z_max_m <= gui.processing.sar3d.z_min_m:
+        raise ValueError("gui.processing.sar3d.z_max_m must be > z_min_m")
+    if gui.processing.sar3d.ground_depth_m < 0.0:
+        raise ValueError("gui.processing.sar3d.ground_depth_m must be >= 0")
+    if gui.processing.sar3d.tx_per_segment < 1:
+        raise ValueError("gui.processing.sar3d.tx_per_segment must be >= 1")
 
     data_actions_object = _as_dict(gui_object.get("data_actions"), "gui.data_actions")
     gui.data_actions = GuiDataActionsStateModel(
@@ -640,6 +854,40 @@ def gui_profile_to_dict(model: GuiProfileModel) -> dict[str, Any]:
                 "visible_z_min_m": gui.processing.legacy_gpr.visible_z_min_m,
                 "visible_z_max_m": gui.processing.legacy_gpr.visible_z_max_m,
             },
+            "sar3d": {
+                "input_positions": gui.processing.sar3d.input_positions,
+                "output_positions": gui.processing.sar3d.output_positions,
+                "min_depth_m": gui.processing.sar3d.min_depth_m,
+                "max_depth_m": gui.processing.sar3d.max_depth_m,
+                "start_freq_mhz": gui.processing.sar3d.start_freq_mhz,
+                "stop_freq_mhz": gui.processing.sar3d.stop_freq_mhz,
+                "speed_m_s": gui.processing.sar3d.speed_m_s,
+                "ignore_socket_speed_enabled": gui.processing.sar3d.ignore_socket_speed_enabled,
+                "look_angle_deg": gui.processing.sar3d.look_angle_deg,
+                "direction_sign": gui.processing.sar3d.direction_sign,
+                "apply_freq_phase_correction": gui.processing.sar3d.apply_freq_phase_correction,
+                "frame_radius": gui.processing.sar3d.frame_radius,
+                "edge_frame_weight": gui.processing.sar3d.edge_frame_weight,
+                "pitch_override_enabled": gui.processing.sar3d.pitch_override_enabled,
+                "pitch_deg": gui.processing.sar3d.pitch_deg,
+                "ground_depth_m": gui.processing.sar3d.ground_depth_m,
+                "x_min_m": gui.processing.sar3d.x_min_m,
+                "x_max_m": gui.processing.sar3d.x_max_m,
+                "y_min_m": gui.processing.sar3d.y_min_m,
+                "y_max_m": gui.processing.sar3d.y_max_m,
+                "z_min_m": gui.processing.sar3d.z_min_m,
+                "z_max_m": gui.processing.sar3d.z_max_m,
+                "voxel_x_m": gui.processing.sar3d.voxel_x_m,
+                "voxel_y_m": gui.processing.sar3d.voxel_y_m,
+                "voxel_z_m": gui.processing.sar3d.voxel_z_m,
+                "norm_edge_margin_m": gui.processing.sar3d.norm_edge_margin_m,
+                "smooth_sigma": gui.processing.sar3d.smooth_sigma,
+                "comp_range_power": gui.processing.sar3d.comp_range_power,
+                "tx_per_segment": gui.processing.sar3d.tx_per_segment,
+                "use_compensation": gui.processing.sar3d.use_compensation,
+                "normalize_pairs": gui.processing.sar3d.normalize_pairs,
+                "bottom_view_deg": gui.processing.sar3d.bottom_view_deg,
+            },
         },
         "data_actions": {
             "save_count": gui.data_actions.save_count,

python_app/models/gui_profile_model.py

@@ -10,6 +10,7 @@ from python_app.models.gui_profile_schema import (
     GuiPreprocessDialogStateModel,
     GuiProcessingStateModel,
     GuiProfileModel,
+    GuiSar3dStateModel,
     GuiStateModel,
     GuiSwitchStateModel,
 )
@@ -23,6 +24,7 @@ __all__ = [
     "GuiPreprocessDialogStateModel",
     "GuiProcessingStateModel",
     "GuiProfileModel",
+    "GuiSar3dStateModel",
     "GuiStateModel",
     "GuiSwitchStateModel",
     "gui_profile_from_dict",

python_app/models/gui_profile_schema.py

@@ -123,6 +123,51 @@ class GuiLegacyGprStateModel:
     visible_z_max_m: float = 14.0
 
 
+@dataclass(slots=True)
+class GuiSar3dStateModel:
+    """UI-only defaults for the 3D SAR (sar3d) live settings.
+
+    The band, depth gate, antenna selection and motion knobs mirror the shared
+    gpr_* live-config fields; the sar3d_* knobs mirror the reference notebook
+    (Multi_antenna_3D_clean_v1.ipynb) defaults used by the C++ sar3d processor.
+    """
+
+    input_positions: str = ""
+    output_positions: str = ""
+    min_depth_m: float = 2.5
+    max_depth_m: float = 8.0
+    start_freq_mhz: float = 2000.0
+    stop_freq_mhz: float = 6000.0
+    speed_m_s: float = 0.0
+    ignore_socket_speed_enabled: bool = False
+    look_angle_deg: float = 17.5
+    direction_sign: float = 1.0
+    apply_freq_phase_correction: bool = True
+    frame_radius: int = 0
+    edge_frame_weight: float = 0.8
+    pitch_override_enabled: bool = False
+    pitch_deg: float = 17.5
+    ground_depth_m: float = 1.25
+    x_min_m: float = -2.0
+    x_max_m: float = 2.0
+    y_min_m: float = -0.5
+    y_max_m: float = 2.0
+    z_min_m: float = 0.0
+    z_max_m: float = 8.0
+    voxel_x_m: float = 0.025
+    voxel_y_m: float = 0.02
+    voxel_z_m: float = 0.02
+    norm_edge_margin_m: float = 0.3
+    smooth_sigma: float = 1.5
+    comp_range_power: float = 0.3
+    tx_per_segment: int = 2
+    use_compensation: bool = True
+    normalize_pairs: bool = True
+    # Bottom-view projection angle around the vertical Y axis, degrees:
+    # 0 = front view (X-Y), 90 = side view (Z-Y).
+    bottom_view_deg: float = 0.0
+
+
 @dataclass(slots=True)
 class GuiProcessingStateModel:
     """UI-only processing-section defaults."""
@@ -132,6 +177,7 @@ class GuiProcessingStateModel:
     bscan: GuiBscanStateModel = field(default_factory=GuiBscanStateModel)
     gpr: GuiGprStateModel = field(default_factory=GuiGprStateModel)
     legacy_gpr: GuiLegacyGprStateModel = field(default_factory=GuiLegacyGprStateModel)
+    sar3d: GuiSar3dStateModel = field(default_factory=GuiSar3dStateModel)
 
 
 @dataclass(slots=True)

python_app/models/run_config_codec.py

@@ -175,6 +175,7 @@ def run_config_from_dict(payload: dict[str, Any]) -> RunConfigModel:
         "run.locator_server",
     )
     multi_device_payload = _as_dict(radar_payload.get("multi_device"), "radar.multi_device")
+    replay_payload = _as_dict(radar_payload.get("replay"), "radar.replay")
     kamil_adc_payload = _as_dict(radar_payload.get("kamil_adc"), "radar.kamil_adc")
     laser_control_payload = _as_dict(radar_payload.get("laser_control"), "radar.laser_control")
 
@@ -235,6 +236,13 @@ def run_config_from_dict(payload: dict[str, Any]) -> RunConfigModel:
         "stimulus_switch_positions",
         model.radar.multi_device.stimulus_switch_positions,
     )
+    model.radar.replay.dataset_dir = _read_str(
+        replay_payload, "dataset_dir", model.radar.replay.dataset_dir
+    )
+    model.radar.replay.loop = _read_bool(replay_payload, "loop", model.radar.replay.loop)
+    model.radar.replay.rate_scale = _read_float(
+        replay_payload, "rate_scale", model.radar.replay.rate_scale
+    )
     model.radar.kamil_adc.project_dir = _read_str(
         kamil_adc_payload, "project_dir", model.radar.kamil_adc.project_dir
     )
@@ -519,6 +527,11 @@ def run_config_to_dict(model: RunConfigModel) -> dict[str, Any]:
                 "input_switch_positions": model.radar.multi_device.input_switch_positions,
                 "stimulus_switch_positions": model.radar.multi_device.stimulus_switch_positions
             },
+            "replay": {
+                "dataset_dir": model.radar.replay.dataset_dir,
+                "loop": model.radar.replay.loop,
+                "rate_scale": model.radar.replay.rate_scale,
+            },
             "kamil_adc": {
                 "project_dir": model.radar.kamil_adc.project_dir,
                 "executable_path": model.radar.kamil_adc.executable_path,

python_app/models/run_config_schema.py

@@ -52,6 +52,25 @@ class RadarMultiDeviceModel:
     stimulus_switch_positions: int = 1
 
 
+@dataclass(slots=True)
+class RadarReplayModel:
+    """Recorded-dataset replay settings (no hardware).
+
+    When ``dataset_dir`` is non-empty the supervisor launches
+    ``python_app.scripts.replay_raw_producer`` instead of the model's normal
+    acquisition producer. The dataset is a directory of snapshot folders named
+    ``NNNN_idK_ns<timestamp>``, each holding ``i{input}_o{output}_s21.npy`` /
+    ``_freq.npy`` files (the VNA_AlGo preprocessed-capture layout).
+    """
+
+    dataset_dir: str = ""
+    # Restart from the first snapshot when the dataset ends; the replay
+    # timeline keeps advancing monotonically across the seam.
+    loop: bool = True
+    # Playback speed multiplier: 1.0 replays at the recorded frame cadence.
+    rate_scale: float = 1.0
+
+
 @dataclass(slots=True)
 class KamilAdcPhaseCalibrationModel:
     """Affine law mapping the reference signal's unwrapped phase to frequency.
@@ -159,6 +178,7 @@ class RadarModel:
     visa_library: str = ""
     sweep: RadarSweepModel = field(default_factory=RadarSweepModel)
     multi_device: RadarMultiDeviceModel = field(default_factory=RadarMultiDeviceModel)
+    replay: RadarReplayModel = field(default_factory=RadarReplayModel)
     kamil_adc: KamilAdcModel = field(default_factory=KamilAdcModel)
     laser_control: LaserControlModel = field(default_factory=LaserControlModel)
 

python_app/orchestration/live_processing_config.py

@@ -72,6 +72,40 @@ class ProcessingLiveConfig:
     gpr_visible_x_max_m: float = 2.0
     gpr_visible_z_min_m: float = 0.0
     gpr_visible_z_max_m: float = 14.0
+    # 3D SAR (sar3d processor) parameters; defaults mirror the reference
+    # notebook Multi_antenna_3D_clean_v1.ipynb. The frequency band, depth gate,
+    # antenna selection and motion parameters are shared with the gpr_* fields.
+    sar3d_frame_radius: int = 0
+    sar3d_edge_frame_weight: float = 0.8
+    # Frame pitch override; disabled -> the pitch follows gpr_look_angle_deg.
+    sar3d_pitch_override_enabled: bool = False
+    sar3d_pitch_deg: float = 17.5
+    # Height of the lower antenna row above the ground (scene Y=0 = ground).
+    sar3d_ground_depth_m: float = 1.25
+    # Scene grid bounds (metres): X across, Y height above the ground, Z along
+    # the ground away from the radar. Voxels outside the radar depth gate are
+    # zeroed by the mask regardless of the Z window.
+    sar3d_x_min_m: float = -2.0
+    sar3d_x_max_m: float = 2.0
+    sar3d_y_min_m: float = -0.5
+    sar3d_y_max_m: float = 2.0
+    sar3d_z_min_m: float = 0.0
+    sar3d_z_max_m: float = 8.0
+    sar3d_voxel_x_m: float = 0.025
+    sar3d_voxel_y_m: float = 0.02
+    sar3d_voxel_z_m: float = 0.02
+    # Volume finalization: Y-edge margin excluded from normalization, Gaussian
+    # smoothing sigma over (Z, X) planes.
+    sar3d_norm_edge_margin_m: float = 0.3
+    sar3d_smooth_sigma: float = 1.5
+    sar3d_comp_range_power: float = 0.3
+    # Fallback frame segmentation when per-trace capture stamps are absent.
+    sar3d_tx_per_segment: int = 2
+    sar3d_use_compensation: bool = True
+    sar3d_normalize_pairs: bool = True
+    # Bottom-view projection angle around the vertical Y axis, degrees:
+    # 0 = front view (X horizontal), 90 = side view (Z horizontal).
+    sar3d_bottom_view_deg: float = 0.0
     # When true, the C++ data_processor ignores socket-supplied vlc updates
     # and keeps using `gpr_speed_m_s` from this file.
     ignore_socket_speed: bool = False
@@ -136,6 +170,27 @@ class ProcessingLiveConfig:
             "gpr_visible_x_max_m": float(self.gpr_visible_x_max_m),
             "gpr_visible_z_min_m": float(self.gpr_visible_z_min_m),
             "gpr_visible_z_max_m": float(self.gpr_visible_z_max_m),
+            "sar3d_frame_radius": int(self.sar3d_frame_radius),
+            "sar3d_edge_frame_weight": float(self.sar3d_edge_frame_weight),
+            "sar3d_pitch_override_enabled": bool(self.sar3d_pitch_override_enabled),
+            "sar3d_pitch_deg": float(self.sar3d_pitch_deg),
+            "sar3d_ground_depth_m": float(self.sar3d_ground_depth_m),
+            "sar3d_x_min_m": float(self.sar3d_x_min_m),
+            "sar3d_x_max_m": float(self.sar3d_x_max_m),
+            "sar3d_y_min_m": float(self.sar3d_y_min_m),
+            "sar3d_y_max_m": float(self.sar3d_y_max_m),
+            "sar3d_z_min_m": float(self.sar3d_z_min_m),
+            "sar3d_z_max_m": float(self.sar3d_z_max_m),
+            "sar3d_voxel_x_m": float(self.sar3d_voxel_x_m),
+            "sar3d_voxel_y_m": float(self.sar3d_voxel_y_m),
+            "sar3d_voxel_z_m": float(self.sar3d_voxel_z_m),
+            "sar3d_norm_edge_margin_m": float(self.sar3d_norm_edge_margin_m),
+            "sar3d_smooth_sigma": float(self.sar3d_smooth_sigma),
+            "sar3d_comp_range_power": float(self.sar3d_comp_range_power),
+            "sar3d_tx_per_segment": int(self.sar3d_tx_per_segment),
+            "sar3d_use_compensation": bool(self.sar3d_use_compensation),
+            "sar3d_normalize_pairs": bool(self.sar3d_normalize_pairs),
+            "sar3d_bottom_view_deg": float(self.sar3d_bottom_view_deg),
             "ignore_socket_speed": bool(self.ignore_socket_speed),
             "reprocess_current_result": bool(self.reprocess_current_result),
             "history_command_seq": int(self.history_command_seq),

python_app/orchestration/process_supervisor.py

@@ -283,6 +283,19 @@ class ProcessSupervisor:
 
     def _acquisition_command(self, config_path: Path) -> list[str]:
         """Return acquisition producer command selected by radar.model."""
+        # A configured replay dataset overrides the model's normal producer:
+        # recorded snapshots are replayed into the raw ring instead of
+        # acquiring from (mock) hardware.
+        replay_dir = self._read_replay_dataset_dir(config_path)
+        if replay_dir:
+            logger.debug("Selecting replay producer for dataset_dir=%s", replay_dir)
+            return [
+                sys.executable,
+                "-m",
+                "python_app.scripts.replay_raw_producer",
+                "--config",
+                str(config_path),
+            ]
         radar_model = self._read_radar_model(config_path)
         logger.debug("Selecting acquisition producer for radar.model=%s", radar_model)
         if radar_model in {"librevna_multi", "sn9000"}:
@@ -318,6 +331,20 @@ class ProcessSupervisor:
             return "librevna"
         return str(radar_payload.get("model", "librevna"))
 
+    @staticmethod
+    def _read_replay_dataset_dir(config_path: Path) -> str:
+        """Read `radar.replay.dataset_dir` cheaply, '' when replay is off."""
+        payload = json.loads(config_path.read_text(encoding="utf-8"))
+        if not isinstance(payload, dict):
+            return ""
+        radar_payload = payload.get("radar")
+        if not isinstance(radar_payload, dict):
+            return ""
+        replay_payload = radar_payload.get("replay")
+        if not isinstance(replay_payload, dict):
+            return ""
+        return str(replay_payload.get("dataset_dir", "")).strip()
+
     def _stop_processes(self, names: Iterable[str]) -> None:
         """Gracefully terminate processes, then force-kill on per-process timeout."""
         ordered_names = list(names)
@@ -591,6 +618,7 @@ class ProcessSupervisor:
             "build/bin/sweep_orchestrator",
             "python_app.scripts.matrix_raw_producer",
             "python_app.scripts.kamil_adc_raw_producer",
+            "python_app.scripts.replay_raw_producer",
         )
         try:
             raw = (Path("/proc") / str(pid) / "cmdline").read_bytes()

python_app/scripts/create_neutral_preprocess_sets.py

@@ -0,0 +1,90 @@
+"""CLI to create neutral S21 preprocess sets for a profile (headless).
+
+Mirrors the GUI's "Create neutral sets" button: builds calibration = 1+0j and
+reference = 0 collections for every combo of the profile and saves them under
+the profile's radar key, so the data_preprocessor becomes a bit-exact
+pass-through. Needed for replay profiles whose recorded data is already
+preprocessed (see run_config_examples/run_config_replay_vna.example.json).
+
+Usage:
+    python -m python_app.scripts.create_neutral_preprocess_sets \
+        --config run_config_examples/run_config_replay_vna.example.json \
+        [--set-name neutral_replay] [--force]
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+from python_app.models.run_config_model import RunConfigModel
+from python_app.storage.npz_store import NpzStore, radar_key_from_config
+from python_app.workflows.kamil_adc_neutral_preprocess import (
+    build_neutral_s21_sets,
+    supports_neutral_preprocess_sets,
+)
+
+logger = logging.getLogger(__name__)
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def main() -> int:
+    """Create and save the neutral S21 calibration/reference pair."""
+    parser = argparse.ArgumentParser(description="Create neutral S21 preprocess sets")
+    parser.add_argument("--config", required=True, type=Path, help="Path to a run_config profile")
+    parser.add_argument("--set-name", default="neutral_replay", help="Name for both saved sets")
+    parser.add_argument(
+        "--force", action="store_true", help="Overwrite the sets if they already exist"
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    config = RunConfigModel.load_from_path(args.config)
+    config.ensure_combos()
+    if not supports_neutral_preprocess_sets(config):
+        raise RuntimeError(
+            "Neutral S21 sets are available only for kamil_adc and librevna_multi"
+        )
+
+    radar_key = radar_key_from_config(
+        model_name=config.radar.model,
+        serial=config.radar.serial,
+        sweep_start_hz=config.radar.sweep.start_hz,
+        sweep_stop_hz=config.radar.sweep.stop_hz,
+        sweep_points=config.radar.sweep.points,
+        ifbw_hz=config.radar.sweep.if_bandwidth_hz,
+        power_dbm=config.radar.sweep.power_dbm,
+        extra_serials=config.radar_key_extra_parts() or None,
+    )
+    store = NpzStore(PROJECT_ROOT / "python_app/data")
+
+    existing = [
+        kind
+        for kind in ("s21_calibration", "s21_reference")
+        if args.set_name in store.list_sets(kind, radar_key)
+    ]
+    if existing and not args.force:
+        logger.info(
+            "Sets '%s' already exist for %s (radar_key=%s); nothing to do (use --force to overwrite).",
+            args.set_name, ", ".join(existing), radar_key,
+        )
+        return 0
+
+    calibration, reference = build_neutral_s21_sets(config)
+    store.save_set("s21_calibration", radar_key, args.set_name, calibration)
+    store.save_set("s21_reference", radar_key, args.set_name, reference)
+    logger.info(
+        "Neutral S21 sets saved: set=%s, radar_key=%s, combos=%d, points=%d",
+        args.set_name,
+        radar_key,
+        len(calibration.traces),
+        int(calibration.traces[0].frequency_hz.size),
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python_app/scripts/replay_raw_producer.py

@@ -0,0 +1,279 @@
+"""Raw producer that replays a recorded snapshot dataset (no hardware).
+
+Selected by the supervisor instead of the model's normal acquisition producer
+when ``radar.replay.dataset_dir`` is non-empty. The dataset is a directory of
+snapshot folders named ``NNNN_idK_ns<timestamp>`` (the VNA_AlGo
+preprocessed-capture layout), each holding ``i{input}_o{output}_s21.npy`` and
+``i{input}_o{output}_freq.npy`` files for every run combo.
+
+The recorded data is already background-subtracted, so the profile must pair
+this producer with NEUTRAL preprocess sets (calibration = 1, reference = 0,
+no notch) — then the C++ preprocessor passes the traces through bit-exactly
+and the processors (e.g. sar3d) see the recorded scene.
+
+Timeline: snapshot timestamps are re-anchored to this process's monotonic
+clock, preserving the recorded inter-frame gaps. On loop, the seam advances by
+the median inter-frame gap, so motion-model consumers (sar3d aperture offsets)
+never see time jump backwards. ``collection_id`` increases forever.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+from pathlib import Path
+import re
+import signal
+import statistics
+import threading
+import time
+
+import numpy as np
+
+from python_app.logging_setup import coerce_level
+from python_app.models.dataset_model import ComboKey, SweepCollection, TraceData
+from python_app.models.run_config_model import RunConfigModel
+from python_app.orchestration.shm import ShmRingWriter
+from python_app.storage.npz.serialize import RAW_MAGIC, serialize_trace_collection
+
+logger = logging.getLogger(__name__)
+
+_SNAPSHOT_NAME = re.compile(r"^\d+_id\d+_ns(\d+)$")
+
+
+class ReplayDataset:
+    """Recorded snapshots preloaded into memory, with their recorded timeline."""
+
+    def __init__(self, snapshots: list[list[TraceData]], timestamps_ns: list[int]) -> None:
+        self.snapshots = snapshots
+        self.timestamps_ns = timestamps_ns
+        gaps = [b - a for a, b in zip(timestamps_ns, timestamps_ns[1:])]
+        # Median gap doubles as the loop-seam step and the capture-window span;
+        # a single-snapshot dataset falls back to an arbitrary sane cadence.
+        self.median_gap_ns = int(statistics.median(gaps)) if gaps else 160_000_000
+
+    def __len__(self) -> int:
+        return len(self.snapshots)
+
+
+def _load_dataset(dataset_dir: Path, combos: list[ComboKey], expected_points: int) -> ReplayDataset:
+    """Preload every snapshot's traces; fail loudly on a malformed dataset."""
+    if not dataset_dir.is_dir():
+        raise RuntimeError(f"radar.replay.dataset_dir is not a directory: {dataset_dir}")
+
+    named: list[tuple[str, int]] = []
+    for entry in sorted(dataset_dir.iterdir()):
+        match = _SNAPSHOT_NAME.match(entry.name)
+        if entry.is_dir() and match:
+            named.append((entry.name, int(match.group(1))))
+    if not named:
+        raise RuntimeError(
+            f"No snapshot folders (NNNN_idK_ns<ts>) found in {dataset_dir}"
+        )
+
+    snapshots: list[list[TraceData]] = []
+    timestamps_ns: list[int] = []
+    for name, timestamp_ns in named:
+        folder = dataset_dir / name
+        # Recorded per-trace capture windows from the snapshot's meta.json: the
+        # sar3d segmented timing model reconstructs the acquisition segments
+        # from them. Missing/partial meta leaves the zero "unmeasured" sentinel
+        # and the consumer falls back to its uniform-segment model.
+        windows: dict[tuple[int, int], tuple[int, int]] = {}
+        meta_path = folder / "meta.json"
+        if meta_path.is_file():
+            try:
+                meta = json.loads(meta_path.read_text())
+                for entry in meta.get("traces", []):
+                    windows[(int(entry["input"]), int(entry["output"]))] = (
+                        int(entry["capture_start_ns"]),
+                        int(entry["capture_end_ns"]),
+                    )
+            except (OSError, ValueError, KeyError, TypeError):
+                windows = {}
+        traces: list[TraceData] = []
+        for combo in combos:
+            s21_path = folder / f"i{combo.input}_o{combo.output}_s21.npy"
+            freq_path = folder / f"i{combo.input}_o{combo.output}_freq.npy"
+            if not s21_path.is_file() or not freq_path.is_file():
+                raise RuntimeError(
+                    f"Snapshot {name} is missing files for combo "
+                    f"input={combo.input} output={combo.output}: expected "
+                    f"{s21_path.name} and {freq_path.name}. Check run.combos vs the dataset."
+                )
+            s21 = np.load(s21_path).astype(np.complex64, copy=False)
+            freq = np.load(freq_path).astype(np.float32, copy=False)
+            if s21.size != freq.size:
+                raise RuntimeError(f"{s21_path}: s21 size {s21.size} != freq size {freq.size}")
+            if expected_points and s21.size != expected_points:
+                raise RuntimeError(
+                    f"{s21_path}: {s21.size} points, but radar.sweep.points = "
+                    f"{expected_points}. Align the profile's sweep with the dataset."
+                )
+            window = windows.get((combo.input, combo.output), (0, 0))
+            traces.append(
+                TraceData(
+                    combo=combo,
+                    frequency_hz=freq,
+                    s11=np.zeros_like(s21),
+                    s21=s21,
+                    capture_start_ns=window[0],
+                    capture_end_ns=window[1],
+                )
+            )
+        snapshots.append(traces)
+        timestamps_ns.append(timestamp_ns)
+
+    return ReplayDataset(snapshots, timestamps_ns)
+
+
+def _build_collection(
+    dataset: ReplayDataset,
+    index: int,
+    collection_id: int,
+    frame_ns: int,
+) -> SweepCollection:
+    """Wrap one preloaded snapshot in a SweepCollection at the given frame time.
+
+    Recorded per-trace capture windows are re-anchored by the same shift as the
+    frame time, preserving the real intra-frame segment layout. Traces without
+    recorded windows get a synthetic window spanning the median frame gap.
+    """
+    span_ns = dataset.median_gap_ns
+    start_ns = frame_ns - span_ns // 2
+    end_ns = frame_ns + span_ns // 2
+    shift_ns = frame_ns - dataset.timestamps_ns[index]
+    traces = []
+    for source in dataset.snapshots[index]:
+        if source.capture_end_ns > source.capture_start_ns:
+            capture = (source.capture_start_ns + shift_ns, source.capture_end_ns + shift_ns)
+        else:
+            capture = (start_ns, end_ns)
+        traces.append(
+            TraceData(
+                combo=source.combo,
+                frequency_hz=source.frequency_hz,
+                s11=source.s11,
+                s21=source.s21,
+                capture_start_ns=capture[0],
+                capture_end_ns=capture[1],
+            )
+        )
+    return SweepCollection(
+        collection_id=collection_id,
+        monotonic_ns=frame_ns,
+        traces=traces,
+        capture_start_ns=min(t.capture_start_ns for t in traces),
+        capture_end_ns=max(t.capture_end_ns for t in traces),
+    )
+
+
+def main() -> int:
+    """Replay the configured dataset into the raw SHM rings until stopped."""
+    parser = argparse.ArgumentParser(description="Replay a recorded dataset to raw SHM rings")
+    parser.add_argument("--config", required=True, type=Path, help="Path to run_config.json")
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    stop_requested = threading.Event()
+
+    def request_stop(_signum: int, _frame: object) -> None:
+        stop_requested.set()
+
+    signal.signal(signal.SIGINT, request_stop)
+    signal.signal(signal.SIGTERM, request_stop)
+
+    config = RunConfigModel.load_from_path(args.config)
+    config.apply_device_model_constraints()
+    logging.getLogger("python_app").setLevel(coerce_level(config.logging.level))
+
+    replay = config.radar.replay
+    if not replay.dataset_dir:
+        raise RuntimeError("replay_raw_producer requires a non-empty radar.replay.dataset_dir")
+    rate_scale = float(replay.rate_scale) if replay.rate_scale > 0 else 1.0
+    combos = [ComboKey(input=combo.input, output=combo.output) for combo in config.combos]
+
+    # expanduser: profiles are copied between machines, so "~/..." dataset paths
+    # must resolve against the local home instead of failing as a literal "~".
+    dataset = _load_dataset(
+        Path(replay.dataset_dir).expanduser(), combos, int(config.radar.sweep.points)
+    )
+    logger.info(
+        "Replay producer starting: dataset=%s, snapshots=%d, combos=%d, "
+        "median_gap=%.3f s, loop=%s, rate_scale=%.2f",
+        replay.dataset_dir, len(dataset), len(combos),
+        dataset.median_gap_ns / 1e9, replay.loop, rate_scale,
+    )
+
+    raw_writer = ShmRingWriter(
+        config.rings.raw.name,
+        config.rings.raw.capacity,
+        config.rings.raw.slot_size_bytes,
+    )
+    raw_tap_writer = ShmRingWriter(
+        config.rings.raw_tap.name,
+        config.rings.raw_tap.capacity,
+        config.rings.raw_tap.slot_size_bytes,
+    )
+
+    try:
+        base_ns = time.monotonic_ns()
+        wall_start_s = time.monotonic()
+        first_ts = dataset.timestamps_ns[0]
+        cycle_span_ns = dataset.timestamps_ns[-1] - first_ts + dataset.median_gap_ns
+
+        collection_id = 1
+        publish_failures = 0
+        cycle = 0
+        while not stop_requested.is_set():
+            for index in range(len(dataset)):
+                if stop_requested.is_set():
+                    break
+                # Monotonic replay timeline: recorded offsets re-anchored at
+                # base_ns, each loop shifted by one full cycle span.
+                frame_ns = (
+                    base_ns
+                    + (dataset.timestamps_ns[index] - first_ts)
+                    + cycle * cycle_span_ns
+                )
+                # Publish on the recorded cadence (scaled); waiting via the stop
+                # event keeps shutdown prompt.
+                deadline_s = wall_start_s + (frame_ns - base_ns) / 1e9 / rate_scale
+                delay_s = deadline_s - time.monotonic()
+                if delay_s > 0 and stop_requested.wait(delay_s):
+                    break
+
+                collection = _build_collection(dataset, index, collection_id, frame_ns)
+                payload = serialize_trace_collection(collection, RAW_MAGIC)
+                if raw_writer.push(payload):
+                    raw_tap_writer.push(payload)  # best-effort GUI tap; never fatal
+                else:
+                    publish_failures += 1
+                    if publish_failures == 1 or publish_failures % 100 == 0:
+                        logger.error(
+                            "Replay payload %d B exceeds ring slot %d B; dropping collection %d (drops=%d)",
+                            len(payload), raw_writer.slot_size_bytes, collection_id, publish_failures,
+                        )
+                if collection_id == 1 or collection_id % 50 == 0:
+                    logger.info(
+                        "replay collection %d published (snapshot %d/%d, cycle %d)",
+                        collection_id, index + 1, len(dataset), cycle,
+                    )
+                collection_id += 1
+                if not config.runtime.continuous:
+                    stop_requested.set()
+                    break
+            if not replay.loop:
+                break
+            cycle += 1
+    finally:
+        raw_tap_writer.close()
+        raw_writer.close()
+
+    logger.info("replay raw producer stopped")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python_app/scripts/replay_smoke_run.py

@@ -0,0 +1,262 @@
+"""Headless smoke: replay the recorded VNA_AlGo dataset through the full pipeline.
+
+Loads the replay profile, creates neutral preprocess sets, launches the whole
+pipeline (replay_raw_producer -> data_preprocessor -> data_processor) via the
+ProcessSupervisor with unique ring names, forces the sar3d processor through
+processing_live.json, and asserts that:
+
+- sar3d projection payloads arrive with a positive peak;
+- collection ids increase monotonically (including across a dataset loop);
+- the preprocessor is transparent: a preprocessed_tap trace equals the
+  recorded snapshot's s21 within float32 rounding.
+
+Usage:
+    python -m python_app.scripts.replay_smoke_run \
+        [--config run_config_examples/run_config_replay_vna.example.json] \
+        [--duration 20.0]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+from pathlib import Path
+import time
+
+import numpy as np
+
+from python_app.models.run_config_model import RunConfigModel
+from python_app.orchestration.config_writer import ConfigWriter
+from python_app.orchestration.live_processing_config import (
+    ProcessingLiveConfig,
+    ProcessingLiveConfigWriter,
+)
+from python_app.orchestration.process_supervisor import ProcessSupervisor
+from python_app.orchestration.shm import ShmRingReader
+from python_app.orchestration.shm.decoder import PREPROC_MAGIC, decode_trace_collection
+from python_app.storage.npz_store import NpzStore, radar_key_from_config
+from python_app.workflows.kamil_adc_neutral_preprocess import build_neutral_s21_sets
+
+logger = logging.getLogger(__name__)
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _make_unique_ring_name(prefix: str) -> str:
+    """Build unique POSIX SHM ring name."""
+    return f"/{prefix}_{os.getpid()}_{time.monotonic_ns()}"
+
+
+def _sar3d_live_config(profile_path: Path) -> ProcessingLiveConfig:
+    """Build a sar3d live config from the profile's gui.processing.sar3d section.
+
+    RunConfigModel does not carry the GUI section (it belongs to the GUI profile
+    layer), so the sar3d defaults are read straight from the profile JSON.
+    """
+    payload = json.loads(profile_path.read_text(encoding="utf-8"))
+    sar3d = (
+        payload.get("gui", {}).get("processing", {}).get("sar3d", {})
+        if isinstance(payload, dict)
+        else {}
+    )
+
+    def _positions(text: str) -> list[int]:
+        return [int(value) for value in str(text).split(",") if value.strip()]
+
+    live = ProcessingLiveConfig(processor_mode="sar3d", ignore_socket_speed=True)
+    if not isinstance(sar3d, dict) or not sar3d:
+        return live
+    live.gpr_input_positions = _positions(sar3d.get("input_positions", ""))
+    live.gpr_output_positions = _positions(sar3d.get("output_positions", ""))
+    live.gpr_min_depth_m = float(sar3d.get("min_depth_m", live.gpr_min_depth_m))
+    live.gpr_max_depth_m = float(sar3d.get("max_depth_m", live.gpr_max_depth_m))
+    live.gpr_start_freq_mhz = float(sar3d.get("start_freq_mhz", live.gpr_start_freq_mhz))
+    live.gpr_stop_freq_mhz = float(sar3d.get("stop_freq_mhz", live.gpr_stop_freq_mhz))
+    live.gpr_speed_m_s = float(sar3d.get("speed_m_s", live.gpr_speed_m_s))
+    live.gpr_look_angle_deg = float(sar3d.get("look_angle_deg", live.gpr_look_angle_deg))
+    live.gpr_direction_sign = float(sar3d.get("direction_sign", live.gpr_direction_sign))
+    live.gpr_apply_freq_phase_correction = bool(
+        sar3d.get("apply_freq_phase_correction", live.gpr_apply_freq_phase_correction)
+    )
+    live.sar3d_frame_radius = int(sar3d.get("frame_radius", live.sar3d_frame_radius))
+    live.sar3d_edge_frame_weight = float(
+        sar3d.get("edge_frame_weight", live.sar3d_edge_frame_weight)
+    )
+    live.sar3d_pitch_override_enabled = bool(
+        sar3d.get("pitch_override_enabled", live.sar3d_pitch_override_enabled)
+    )
+    live.sar3d_pitch_deg = float(sar3d.get("pitch_deg", live.sar3d_pitch_deg))
+    live.sar3d_ground_depth_m = float(sar3d.get("ground_depth_m", live.sar3d_ground_depth_m))
+    live.sar3d_x_min_m = float(sar3d.get("x_min_m", live.sar3d_x_min_m))
+    live.sar3d_x_max_m = float(sar3d.get("x_max_m", live.sar3d_x_max_m))
+    live.sar3d_y_min_m = float(sar3d.get("y_min_m", live.sar3d_y_min_m))
+    live.sar3d_y_max_m = float(sar3d.get("y_max_m", live.sar3d_y_max_m))
+    live.sar3d_z_min_m = float(sar3d.get("z_min_m", live.sar3d_z_min_m))
+    live.sar3d_z_max_m = float(sar3d.get("z_max_m", live.sar3d_z_max_m))
+    live.sar3d_voxel_x_m = float(sar3d.get("voxel_x_m", live.sar3d_voxel_x_m))
+    live.sar3d_voxel_y_m = float(sar3d.get("voxel_y_m", live.sar3d_voxel_y_m))
+    live.sar3d_voxel_z_m = float(sar3d.get("voxel_z_m", live.sar3d_voxel_z_m))
+    live.sar3d_norm_edge_margin_m = float(
+        sar3d.get("norm_edge_margin_m", live.sar3d_norm_edge_margin_m)
+    )
+    live.sar3d_smooth_sigma = float(sar3d.get("smooth_sigma", live.sar3d_smooth_sigma))
+    live.sar3d_comp_range_power = float(
+        sar3d.get("comp_range_power", live.sar3d_comp_range_power)
+    )
+    live.sar3d_tx_per_segment = int(sar3d.get("tx_per_segment", live.sar3d_tx_per_segment))
+    live.sar3d_use_compensation = bool(sar3d.get("use_compensation", live.sar3d_use_compensation))
+    live.sar3d_normalize_pairs = bool(sar3d.get("normalize_pairs", live.sar3d_normalize_pairs))
+    live.sar3d_bottom_view_deg = float(sar3d.get("bottom_view_deg", live.sar3d_bottom_view_deg))
+    return live
+
+
+def _check_preprocessor_transparency(
+    tap_reader: ShmRingReader, dataset_dir: Path
+) -> bool:
+    """Compare one preprocessed trace against the recorded snapshot's s21."""
+    payload = tap_reader.peek_latest_payload()
+    if payload is None:
+        logger.warning("No preprocessed_tap payload available for transparency check")
+        return False
+    preprocessed = decode_trace_collection(payload, PREPROC_MAGIC)
+
+    # Any snapshot works: neutral preprocessing is time-invariant, so match the
+    # trace against every recorded snapshot and accept the best one.
+    trace = preprocessed.traces[0]
+    combo_file = f"i{trace.combo.input}_o{trace.combo.output}_s21.npy"
+    best_delta = np.inf
+    for folder in sorted(p for p in dataset_dir.iterdir() if p.name[:1].isdigit()):
+        recorded = np.load(folder / combo_file).astype(np.complex64)
+        if recorded.size != np.asarray(trace.s21).size:
+            continue
+        delta = float(np.max(np.abs(np.asarray(trace.s21) - recorded)))
+        best_delta = min(best_delta, delta)
+        if best_delta == 0.0:
+            break
+    logger.info("Preprocessor transparency: max|delta| vs best snapshot = %.3e", best_delta)
+    return best_delta < 1e-6
+
+
+def main() -> int:
+    """Run the replay pipeline smoke and report pass/fail."""
+    parser = argparse.ArgumentParser(description="Headless replay pipeline smoke")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=PROJECT_ROOT / "run_config_examples/run_config_replay_vna.example.json",
+    )
+    parser.add_argument("--duration", type=float, default=20.0)
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    config = RunConfigModel.load_from_path(args.config)
+    config.ensure_combos()
+    # expanduser: "~/..." dataset paths from machine-portable profiles.
+    dataset_dir = Path(config.radar.replay.dataset_dir).expanduser()
+    if not dataset_dir.is_dir():
+        raise RuntimeError(f"Replay dataset not found: {dataset_dir}")
+
+    config.rings.raw.name = _make_unique_ring_name("radar_raw_replay_smoke")
+    config.rings.raw_tap.name = _make_unique_ring_name("radar_raw_tap_replay_smoke")
+    config.rings.preprocessed.name = _make_unique_ring_name("radar_preprocessed_replay_smoke")
+    config.rings.preprocessed_tap.name = _make_unique_ring_name("radar_preprocessed_tap_replay_smoke")
+    config.rings.results.name = _make_unique_ring_name("radar_results_replay_smoke")
+    # Private live-config path so the smoke never clobbers the GUI's file.
+    live_path = PROJECT_ROOT / "python_app/runtime/processing_live_replay_smoke.json"
+    config.runtime.processing_live_config_path = str(
+        live_path.relative_to(PROJECT_ROOT)
+    )
+
+    radar_key = radar_key_from_config(
+        model_name=config.radar.model,
+        serial=config.radar.serial,
+        sweep_start_hz=config.radar.sweep.start_hz,
+        sweep_stop_hz=config.radar.sweep.stop_hz,
+        sweep_points=config.radar.sweep.points,
+        ifbw_hz=config.radar.sweep.if_bandwidth_hz,
+        power_dbm=config.radar.sweep.power_dbm,
+        extra_serials=config.radar_key_extra_parts() or None,
+    )
+    store = NpzStore(PROJECT_ROOT / "python_app/data")
+    set_name = config.preprocess.s21.calibration.set_name or "neutral_replay"
+    if set_name not in store.list_sets("s21_calibration", radar_key):
+        calibration, reference = build_neutral_s21_sets(config)
+        store.save_set("s21_calibration", radar_key, set_name, calibration)
+        store.save_set("s21_reference", radar_key, set_name, reference)
+        logger.info("Created neutral sets '%s' (radar_key=%s)", set_name, radar_key)
+    config.preprocess.s21.calibration.set_name = set_name
+    config.preprocess.s21.reference.set_name = set_name
+
+    ProcessingLiveConfigWriter(live_path).write(_sar3d_live_config(args.config))
+
+    config_writer = ConfigWriter(PROJECT_ROOT / "python_app/runtime")
+    config_writer.prepare_preprocess_bundles(store, radar_key, config)
+    config_path = config_writer.write(
+        config, PROJECT_ROOT / "python_app/runtime/run_config_replay_smoke.json"
+    )
+
+    supervisor = ProcessSupervisor(PROJECT_ROOT)
+    result_reader: ShmRingReader | None = None
+    tap_reader: ShmRingReader | None = None
+    failures: list[str] = []
+    try:
+        supervisor.start(config_path)
+        result_reader = ShmRingReader(config.rings.results.name, open_timeout_s=15.0)
+        tap_reader = ShmRingReader(config.rings.preprocessed_tap.name, open_timeout_s=15.0)
+
+        deadline = time.monotonic() + args.duration
+        received = 0
+        sar3d_results = 0
+        last_peak = 0.0
+        last_id = 0
+        ids_monotonic = True
+        while time.monotonic() < deadline:
+            result = result_reader.pop_result_collection()
+            if result is None:
+                time.sleep(0.02)
+                continue
+            received += 1
+            if last_id and result.collection_id <= last_id:
+                ids_monotonic = False
+            last_id = result.collection_id
+            names = {p.processing_name: p for p in result.collection_payloads}
+            if "sar3d_proj_xz" in names and "sar3d_proj_bottom" in names:
+                sar3d_results += 1
+                peak_payload = names.get("sar3d_peak")
+                if peak_payload is not None:
+                    last_peak = float(peak_payload.scalar_value)
+
+        logger.info(
+            "Results: total=%d, with sar3d projections=%d, last collection_id=%d, last peak=%.4e",
+            received, sar3d_results, last_id, last_peak,
+        )
+        if received == 0:
+            failures.append("no result collections received")
+        if sar3d_results == 0:
+            failures.append("no sar3d projection payloads received")
+        if not (last_peak > 0.0):
+            failures.append(f"sar3d peak is not positive: {last_peak}")
+        if not ids_monotonic:
+            failures.append("collection ids were not monotonically increasing")
+        if not _check_preprocessor_transparency(tap_reader, dataset_dir):
+            failures.append("preprocessor is not transparent vs recorded snapshots")
+    finally:
+        supervisor.stop_all()
+        if result_reader is not None:
+            result_reader.close()
+        if tap_reader is not None:
+            tap_reader.close()
+
+    if failures:
+        for failure in failures:
+            logger.error("FAIL: %s", failure)
+        return 1
+    logger.info("REPLAY SMOKE OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python_app/scripts/sar3d_reference_check.py

@@ -0,0 +1,389 @@
+"""Reference implementation of the sar3d volume from Multi_antenna_3D_clean_v1.ipynb.
+
+Executable specification for the C++ port: recomputes a single-frame
+(aperture radius 0) 3D SAR volume from a preprocessed snapshot exactly the
+way the notebook does, then compares it against a reference *_volume.npz
+exported by the notebook.
+
+Usage:
+    python sar3d_reference_check.py <dataset_root> <reference_volume.npz>
+
+<dataset_root> is an extracted replay dataset (contains config_profile.json
+and preprocessed/<snapshot>/i*_o*_{s21,freq}.npy + meta.json). The snapshot
+name and all physics parameters are taken from the npz meta.
+
+Exits non-zero when the recomputed volume differs from the reference by more
+than the tolerance. The only expected difference is the Gaussian smoothing
+(manual separable filter vs scipy) at the 1e-6 level.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+TOLERANCE = 2e-6
+
+C_LIGHT = 3e8
+
+# Notebook constants not recorded in the npz meta (cell 0 / cell 4).
+BP_OVERSAMPLE = 8
+BP_WINDOW = True
+PAIR_NORM_PERCENTILE = 50.0
+PAIR_NORM_EPS = 1e-15
+COMP_RANGE_POWER = 0.3
+COMP_RANGE_WEIGHT_MAX = 5.0
+COMP_REF_DEPTH = 5.0
+BP_SMOOTH_SIGMA = 1.5
+SAR_Y_RANGE_M = (-0.5, 2.0)
+SAR_NORM_EDGE_MARGIN_M = 0.3
+X_MARGIN_M = 2.0
+MOTION_PHASE_SIGN = -1.0
+DIRECTION_SIGN = +1.0
+
+
+def gaussian_kernel1d(sigma: float, radius: int) -> np.ndarray:
+    x = np.arange(-radius, radius + 1, dtype=float)
+    phi = np.exp(-0.5 / (sigma * sigma) * x * x)
+    return phi / phi.sum()
+
+
+def correlate1d_reflect(arr: np.ndarray, weights: np.ndarray, axis: int) -> np.ndarray:
+    r = (len(weights) - 1) // 2
+    a = np.moveaxis(arr, axis, -1)
+    pad = np.concatenate([a[..., r - 1::-1], a, a[..., :-r - 1:-1]], axis=-1)
+    out = np.zeros_like(a)
+    for k, w in enumerate(weights):
+        out += w * pad[..., k:k + a.shape[-1]]
+    return np.moveaxis(out, -1, axis)
+
+
+def gaussian_filter(arr: np.ndarray, sigma: tuple[float, ...], truncate: float = 4.0) -> np.ndarray:
+    """scipy.ndimage.gaussian_filter equivalent (mode='reflect')."""
+    out = np.asarray(arr, dtype=float).copy()
+    for axis, s in enumerate(sigma):
+        if s <= 0:
+            continue
+        radius = int(truncate * float(s) + 0.5)
+        out = correlate1d_reflect(out, gaussian_kernel1d(float(s), radius), axis)
+    return out
+
+
+def load_geometry(profile_path: Path) -> dict:
+    profile = json.loads(profile_path.read_text())
+    gpr = profile["gpr"]
+    tx_geom = {int(e["output_pos"]): (e["x_m"], e.get("y_m", 0.0), e.get("z_m", 0.0))
+               for e in gpr["tx_geometry"]}
+    rx_geom = {int(e["input_pos"]): (e["x_m"], e.get("y_m", 0.0), e.get("z_m", 0.0))
+               for e in gpr["rx_geometry"]}
+    combos = profile["run"]["combos"]
+    pair_order = [(int(c["output"]), int(c["input"])) for c in combos]
+    tx_order_full: list[int] = []
+    for tx, _ in pair_order:
+        if tx not in tx_order_full:
+            tx_order_full.append(tx)
+    output_idx = sorted(tx_geom)
+    input_idx = sorted(rx_geom)
+    tx_xyz = np.array([tx_geom[i] for i in output_idx], dtype=float)
+    rx_xyz = np.array([rx_geom[i] for i in input_idx], dtype=float)
+    return {
+        "output_idx": output_idx, "input_idx": input_idx,
+        "tx_xyz": tx_xyz, "rx_xyz": rx_xyz,
+        "pair_order": pair_order, "tx_order_full": tx_order_full,
+    }
+
+
+def snapshot_timing(snapshot_dir: Path) -> dict | None:
+    """Per-Tx capture windows from the snapshot's meta.json trace labels."""
+    try:
+        meta = json.loads((snapshot_dir / "meta.json").read_text())
+    except OSError:
+        return None
+    traces = [t for t in meta.get("traces", [])
+              if "capture_start_ns" in t and "capture_end_ns" in t and "output" in t]
+    if not traces:
+        return None
+    first = min(int(t["capture_start_ns"]) for t in traces)
+    last = max(int(t["capture_end_ns"]) for t in traces)
+    by_tx: dict[int, tuple[int, int]] = {}
+    for t in traces:
+        by_tx.setdefault(int(t["output"]), (int(t["capture_start_ns"]), int(t["capture_end_ns"])))
+    return {
+        "acq_s": (last - first) * 1e-9,
+        "center_abs_s": 0.5 * (first + last) * 1e-9,
+        "tx_window_s": {tx: ((a - first) * 1e-9, (b - first) * 1e-9) for tx, (a, b) in by_tx.items()},
+    }
+
+
+def pair_timestamps(geometry: dict, timing: dict, speed_m_s: float, look_angle_deg: float,
+                    wave_speed: float) -> dict:
+    """Segment/slot assignment and coarse pair dtau (notebook compute_pair_timestamps_for_snapshot)."""
+    windows = timing["tx_window_s"]
+    hw_order = [tx for tx in geometry["tx_order_full"] if tx in windows]
+    hw_order += [tx for tx in sorted(windows) if tx not in hw_order]
+    groups: dict[tuple[float, float], list[int]] = {}
+    for tx in hw_order:
+        groups.setdefault(windows[tx], []).append(tx)
+    seg_of = {}
+    for seg_idx, win in enumerate(sorted(groups)):
+        for slot, tx in enumerate(groups[win]):
+            seg_of[tx] = (seg_idx, slot, len(groups[win]))
+    cos_theta = np.cos(np.radians(look_angle_deg))
+    t_ref = 0.5 * timing["acq_s"]
+    tx_map = {p: k for k, p in enumerate(geometry["output_idx"])}
+    rx_map = {p: k for k, p in enumerate(geometry["input_idx"])}
+    ts = {}
+    for tx_phys, rx_phys in geometry["pair_order"]:
+        _, slot, n_slots = seg_of[tx_phys]
+        t0, t1 = windows[tx_phys]
+        t_center = 0.5 * (t0 + t1)
+        dz_motion = DIRECTION_SIGN * speed_m_s * (t_center - t_ref) * cos_theta
+        ts[(tx_map[tx_phys], rx_map[rx_phys])] = {
+            "slot": slot, "n_slots": n_slots,
+            "segment_start_s": t0, "segment_time_s": t1 - t0,
+            "t_center_s": t_center,
+            "dtau_motion_s": 2.0 * dz_motion / wave_speed,
+        }
+    return ts
+
+
+def timing_abs_center(snapshot_dir: Path) -> float:
+    timing = snapshot_timing(snapshot_dir)
+    if timing is None:
+        raise RuntimeError(f"meta.json trace labels required in {snapshot_dir}")
+    return timing["center_abs_s"]
+
+
+def load_mimo(snapshot_dir: Path, geometry: dict) -> tuple[dict, dict]:
+    s21_data, freq_data = {}, {}
+    for f in snapshot_dir.glob("i*_o*_s21.npy"):
+        parts = f.stem.split("_")
+        rx_phys = int(parts[0][1:])
+        tx_phys = int(parts[1][1:])
+        if tx_phys not in geometry["output_idx"] or rx_phys not in geometry["input_idx"]:
+            continue
+        key = (geometry["output_idx"].index(tx_phys), geometry["input_idx"].index(rx_phys))
+        s21_data[key] = np.load(f)
+        freq_data[key] = np.asarray(np.load(f.parent / f"i{rx_phys}_o{tx_phys}_freq.npy"), dtype=float)
+    return s21_data, freq_data
+
+
+def apply_phase_correction(s21: np.ndarray, freq_full: np.ndarray, info: dict,
+                           f_start: float, f_stop: float, speed_m_s: float,
+                           look_angle_deg: float, wave_speed: float) -> np.ndarray:
+    """Coarse pair + intra-sweep motion correction as one phase ramp before the IFFT."""
+    idx = np.flatnonzero((freq_full >= f_start) & (freq_full <= f_stop))
+    n_full = len(freq_full)
+    dt_event = info["segment_time_s"] / (info["n_slots"] * n_full)
+    t_abs = info["segment_start_s"] + (info["n_slots"] * idx + info["slot"]) * dt_event
+    dt_intra = t_abs - info["t_center_s"]
+    dtau_intra = 2.0 * DIRECTION_SIGN * speed_m_s * np.cos(np.radians(look_angle_deg)) * dt_intra / wave_speed
+    total_dtau = dtau_intra + info["dtau_motion_s"]
+    phi = 2.0 * np.pi * freq_full[idx] * total_dtau
+    out = np.array(s21, dtype=np.complex128, copy=True)
+    out[idx] *= np.exp(1j * MOTION_PHASE_SIGN * phi)
+    return out
+
+
+def compute_ascan(s21: np.ndarray, freq: np.ndarray, f_start: float, f_stop: float):
+    """Oversampled complex A-scan with the notebook's frequency-shifted IFFT."""
+    mask = (freq >= f_start) & (freq <= f_stop)
+    freq_cut = freq[mask]
+    s21_cut = s21[mask]
+    df = float(np.median(np.diff(freq_cut)))
+    n = len(freq_cut)
+    k0 = int(round(freq_cut[0] / df))
+    n_fft = (1 << int(np.ceil(np.log2(2 * (k0 + n - 1))))) * BP_OVERSAMPLE
+    dt = 1.0 / (n_fft * df)
+    s = s21_cut * np.hanning(n) if BP_WINDOW else s21_cut.copy()
+    spectrum = np.zeros(n_fft, dtype=np.complex128)
+    spectrum[k0:k0 + n] = s
+    return np.arange(n_fft, dtype=float) * dt, np.fft.ifft(spectrum)
+
+
+def interp_complex(tau: np.ndarray, t_axis: np.ndarray, h_axis: np.ndarray) -> np.ndarray:
+    n = t_axis.size
+    dt = (float(t_axis[-1]) - float(t_axis[0])) / (n - 1)
+    pos = (tau - float(t_axis[0])) / dt
+    inside = (pos >= 0.0) & (pos <= n - 1)
+    k = np.clip(np.floor(pos), 0, n - 2).astype(np.intp)
+    frac = pos - k
+    out = h_axis[k] + frac * (h_axis[k + 1] - h_axis[k])
+    return np.where(inside, out, 0.0 + 0.0j)
+
+
+def axis_linspace(lo: float, hi: float, step: float) -> np.ndarray:
+    return np.linspace(lo, hi, max(int(round((hi - lo) / step)) + 1, 2))
+
+
+def compute_volume(dataset_root: Path, meta: dict) -> dict:
+    """Single-frame volume via the notebook's ANIMATION path.
+
+    The reference npz files were exported from animation frames: the base grid
+    is shifted by the radar displacement between the frame and the scene-origin
+    snapshot (meta reference_snapshot), antennas get the same offset, and the
+    depth window follows the radar (depth_shift). Physically it all cancels for
+    an aperture of radius 0, but replicating the exact float arithmetic is what
+    makes the comparison bit-tight at the depth-mask knife edge.
+    """
+    geometry = load_geometry(dataset_root / "config_profile.json")
+    snapshot_dir = dataset_root / "preprocessed" / meta["snapshot"]
+
+    eps_r = 1.0
+    wave_speed = C_LIGHT / np.sqrt(eps_r)
+    f_start = float(meta["f_start_hz"])
+    f_stop = float(meta["f_stop_hz"])
+    min_depth = float(meta["min_depth_m"])
+    max_depth = float(meta["max_depth_m"])
+    speed = float(meta["speed_m_s"])
+    look_angle = float(meta["look_angle_deg"])
+    ground_depth = float(meta["ground_depth_m"])
+    voxel = [float(a) for a in meta["voxel_m"]]
+
+    x_tx, y_tx, z_tx = geometry["tx_xyz"].T
+    x_rx, y_rx, z_rx = geometry["rx_xyz"].T
+    n_tx, n_rx = len(x_tx), len(x_rx)
+
+    timing = snapshot_timing(snapshot_dir)
+    if timing is None:
+        raise RuntimeError(f"meta.json trace labels required in {snapshot_dir}")
+    ts = pair_timestamps(geometry, timing, speed, look_angle, wave_speed)
+
+    s21_data, freq_data = load_mimo(snapshot_dir, geometry)
+    ascan_h, ascan_t = {}, {}
+    for key, s21 in s21_data.items():
+        corrected = apply_phase_correction(
+            s21, freq_data[key], ts[key], f_start, f_stop, speed, look_angle, wave_speed)
+        t_axis, h = compute_ascan(corrected, freq_data[key], f_start, f_stop)
+        z_axis = t_axis * wave_speed / 2
+        m = (z_axis >= min_depth) & (z_axis <= max_depth)
+        scale = float(np.percentile(np.abs(h)[m], PAIR_NORM_PERCENTILE))
+        if not np.isfinite(scale) or scale <= PAIR_NORM_EPS:
+            scale = 1.0
+        ascan_h[key] = h / (scale + PAIR_NORM_EPS)
+        ascan_t[key] = t_axis
+
+    pitch = np.radians(look_angle)
+    cos_p, sin_p = np.cos(pitch), np.sin(pitch)
+
+    def scene_to_radar_yz(y_scene, z_scene):
+        y0 = y_scene - ground_depth
+        return y0 * cos_p + z_scene * sin_p, -y0 * sin_p + z_scene * cos_p
+
+    x_ant = np.concatenate([x_tx, x_rx])
+    y_lo, y_hi = SAR_Y_RANGE_M
+    z_span = [(d - float(scene_to_radar_yz(y, 0.0)[1])) / cos_p
+              for y in (y_lo, y_hi) for d in (min_depth, max_depth)]
+    gx = axis_linspace(float(x_ant.min() - X_MARGIN_M), float(x_ant.max() + X_MARGIN_M), voxel[0])
+    gy = axis_linspace(y_lo, y_hi, voxel[1])
+    gz = axis_linspace(min(z_span), max(z_span), voxel[2])
+
+    # Displacement of this frame relative to the scene-origin snapshot
+    # (notebook sar_frame_offsets + anim_frame_displacement).
+    off_dy = off_dz = 0.0
+    disp_y = disp_z = 0.0
+    reference_name = meta.get("reference_snapshot", meta["snapshot"])
+    if reference_name != meta["snapshot"]:
+        ref_timing = snapshot_timing(dataset_root / "preprocessed" / reference_name)
+        if ref_timing is None:
+            raise RuntimeError(f"meta.json trace labels required in {reference_name}")
+        dt = timing_abs_center(snapshot_dir) - ref_timing["center_abs_s"]
+        horizontal = DIRECTION_SIGN * speed * dt
+        off_dy = float(horizontal * np.sin(pitch))
+        off_dz = float(horizontal * np.cos(pitch))
+        # Scene displacement = difference of two transformed points; the ground
+        # lift cancels, leaving essentially (0, ~0, horizontal).
+        disp_y = (off_dy * cos_p - off_dz * sin_p + ground_depth) - ground_depth
+        disp_z = off_dy * sin_p + off_dz * cos_p
+    gy_s = gy + disp_y
+    gz_s = gz + disp_z
+    depth_shift = off_dz
+    grid_xx, grid_zz = np.meshgrid(gx, gz_s)
+
+    ground_plane_y = (-ground_depth + COMP_REF_DEPTH * sin_p) / cos_p
+
+    def pair_geo_ref(i, j):
+        xc = (x_tx[i] + x_rx[j]) / 2.0
+        r_tx = np.sqrt((xc - x_tx[i]) ** 2 + (ground_plane_y - y_tx[i]) ** 2 + (COMP_REF_DEPTH - z_tx[i]) ** 2)
+        r_rx = np.sqrt((xc - x_rx[j]) ** 2 + (ground_plane_y - y_rx[j]) ** 2 + (COMP_REF_DEPTH - z_rx[j]) ** 2)
+        return 1.0 / (r_tx * r_rx + 1e-12) + 1e-30
+
+    geo_ref = {(i, j): pair_geo_ref(i, j) for i in range(n_tx) for j in range(n_rx)}
+    dx2_tx = [(grid_xx - x_tx[i]) ** 2 for i in range(n_tx)]
+    dx2_rx = [(grid_xx - x_rx[j]) ** 2 for j in range(n_rx)]
+
+    acc_vol = np.zeros((gy.size, gz.size, gx.size), dtype=np.complex128)
+    cnt_vol = np.zeros(acc_vol.shape, dtype=float)
+    for iy, y_plane in enumerate(gy_s):
+        y_rad, z_rad = scene_to_radar_yz(y_plane, grid_zz)
+        depth_ok = (z_rad - depth_shift >= min_depth) & (z_rad - depth_shift <= max_depth)
+        r_tx_all = [np.sqrt(dx2_tx[i] + (y_rad - (y_tx[i] + off_dy)) ** 2 + (z_rad - (z_tx[i] + off_dz)) ** 2)
+                    for i in range(n_tx)]
+        r_rx_all = [np.sqrt(dx2_rx[j] + (y_rad - (y_rx[j] + off_dy)) ** 2 + (z_rad - (z_rx[j] + off_dz)) ** 2)
+                    for j in range(n_rx)]
+        acc = np.zeros_like(grid_xx, dtype=np.complex128)
+        cnt = np.zeros_like(grid_xx, dtype=float)
+        for i in range(n_tx):
+            for j in range(n_rx):
+                key = (i, j)
+                if key not in ascan_h:
+                    continue
+                r_tx, r_rx = r_tx_all[i], r_rx_all[j]
+                tau = (r_tx + r_rx) / wave_speed
+                t_axis = ascan_t[key]
+                valid = depth_ok & (tau >= t_axis[0]) & (tau <= t_axis[-1])
+                h = interp_complex(tau, t_axis, ascan_h[key])
+                ratio = (1.0 / (r_tx * r_rx + 1e-12) + 1e-30) / geo_ref[key]
+                weight = np.clip(1.0 / (ratio ** COMP_RANGE_POWER + 1e-12), 0.0, COMP_RANGE_WEIGHT_MAX)
+                acc += np.where(valid, h * weight, 0.0 + 0.0j)
+                cnt += valid
+        acc_vol[iy] = acc
+        cnt_vol[iy] = cnt
+
+    volume = np.abs(acc_vol / (cnt_vol + 1e-12))
+    z_rad_planes = np.asarray([scene_to_radar_yz(yp, grid_zz)[1] - depth_shift for yp in gy_s])
+    volume = np.where((z_rad_planes >= min_depth) & (z_rad_planes <= max_depth), volume, 0.0)
+    ref_planes = (gy_s >= gy_s[0] + SAR_NORM_EDGE_MARGIN_M) & (gy_s <= gy_s[-1] - SAR_NORM_EDGE_MARGIN_M)
+    level_raw = volume[ref_planes].max() + 1e-12
+    volume = gaussian_filter(volume / level_raw, sigma=(0.0, BP_SMOOTH_SIGMA, BP_SMOOTH_SIGMA))
+    level_smooth = volume[ref_planes].max() + 1e-12
+    volume = np.clip(volume / level_smooth, 0.0, None).astype(np.float32)
+    return {"volume": volume, "level": float(level_raw * level_smooth), "x": gx, "y": gy, "z": gz}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("dataset_root", type=Path,
+                        help="extracted dataset dir (config_profile.json + preprocessed/)")
+    parser.add_argument("reference_npz", type=Path, help="reference *_volume.npz from the notebook")
+    args = parser.parse_args()
+
+    ref = np.load(args.reference_npz)
+    meta = json.loads(str(ref["meta"]))
+    print(f"snapshot: {meta['snapshot']}")
+    result = compute_volume(args.dataset_root, meta)
+
+    volume, ref_volume = result["volume"], ref["volume"]
+    axes_ok = all(np.allclose(result[k], ref[f"{k}_m"]) for k in ("x", "y", "z"))
+    level_rel = abs(result["level"] - meta["level"]) / abs(meta["level"])
+    print(f"axes match: {axes_ok}; level rel diff: {level_rel:.3e} "
+          f"(mine {result['level']:.9f}, ref {meta['level']:.9f})")
+    if volume.shape != ref_volume.shape:
+        print(f"FAIL: shape mismatch {volume.shape} vs {ref_volume.shape}")
+        return 1
+    diff = np.abs(volume.astype(np.float64) - ref_volume.astype(np.float64))
+    argmax = np.unravel_index(int(np.argmax(volume)), volume.shape)
+    ref_argmax = np.unravel_index(int(np.argmax(ref_volume)), ref_volume.shape)
+    print(f"max |diff| = {diff.max():.3e}, mean = {diff.mean():.3e}")
+    print(f"argmax: mine {argmax}, ref {ref_argmax}")
+    ok = axes_ok and diff.max() <= TOLERANCE and argmax == ref_argmax and level_rel <= TOLERANCE
+    print("OK" if ok else "FAIL")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

python_app/scripts/sar3d_volume_compare.py

@@ -0,0 +1,89 @@
+"""Compare a sar3d volume dumped by the C++ processor with a notebook npz export.
+
+Usage:
+    python sar3d_volume_compare.py <dump_base> <reference_volume.npz>
+
+<dump_base> is the path prefix written by `sar3d_parity --dump-dir` (or by the
+processor with `sar3d_volume_dump_dir` set): <dump_base>.f32 holds the raw
+float32 volume [iy][iz][ix], <dump_base>.json its axes and level.
+
+The C++ path accumulates the backprojection in float32 (CUDA kernel), so the
+comparison is tolerance-based rather than bitwise; geometry is computed in
+double, keeping the expected difference at the 1e-5 level. Voxels within the
+smoothing radius of the depth-mask boundary are reported separately: there the
+float32 knife-edge can flip whole boundary voxels (the same effect exists
+between two float64 runs with shifted grids).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+MAX_DIFF_TOLERANCE = 1e-4
+LEVEL_REL_TOLERANCE = 1e-4
+# Gaussian smoothing radius (sigma 1.5 -> radius 6) around the depth-mask edge.
+EDGE_EXCLUSION_VOXELS = 7
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("dump_base", type=Path, help="path prefix of the .f32/.json dump")
+    parser.add_argument("reference_npz", type=Path, help="reference *_volume.npz from the notebook")
+    args = parser.parse_args()
+
+    header = json.loads(Path(str(args.dump_base) + ".json").read_text())
+    shape = (header["ny"], header["nz"], header["nx"])
+    volume = np.fromfile(str(args.dump_base) + ".f32", dtype=np.float32).reshape(shape)
+
+    ref = np.load(args.reference_npz)
+    ref_volume = ref["volume"]
+    meta = json.loads(str(ref["meta"]))
+    print(f"snapshot: {meta['snapshot']}")
+    if volume.shape != ref_volume.shape:
+        print(f"FAIL: shape mismatch {volume.shape} vs {ref_volume.shape}")
+        return 1
+
+    axes_ok = all(
+        np.allclose(np.asarray(header[key]), ref[key])
+        for key in ("x_m", "y_m", "z_m")
+    )
+    level_rel = abs(header["level"] - meta["level"]) / abs(meta["level"])
+    print(f"axes match: {axes_ok}; level rel diff: {level_rel:.3e} "
+          f"(dump {header['level']:.9f}, ref {meta['level']:.9f})")
+
+    diff = np.abs(volume.astype(np.float64) - ref_volume.astype(np.float64))
+
+    # Depth-mask boundary band: voxels whose (iy, iz) sit within the smoothing
+    # radius of a masked/unmasked transition. Reconstructed from the reference
+    # parameters exactly like the processor computes the mask.
+    pitch = np.radians(float(meta.get("ground_pitch_deg") or meta["look_angle_deg"]))
+    y0 = np.asarray(ref["y_m"]) - float(meta["ground_depth_m"])
+    z_rad = -y0[:, None] * np.sin(pitch) + np.asarray(ref["z_m"])[None, :] * np.cos(pitch)
+    mask = (z_rad >= float(meta["min_depth_m"])) & (z_rad <= float(meta["max_depth_m"]))
+    edge = np.zeros_like(mask)
+    r = EDGE_EXCLUSION_VOXELS
+    for shift in range(-r, r + 1):
+        edge |= np.roll(mask, shift, axis=1) != mask
+    interior = ~edge
+
+    argmax = np.unravel_index(int(np.argmax(volume)), volume.shape)
+    ref_argmax = np.unravel_index(int(np.argmax(ref_volume)), ref_volume.shape)
+    interior_diff = diff[interior[:, :, None] & np.ones(volume.shape, dtype=bool)]
+    print(f"max |diff| (all voxels)          = {diff.max():.3e}")
+    print(f"max |diff| (off depth-mask edge) = {interior_diff.max():.3e}, "
+          f"mean = {interior_diff.mean():.3e}")
+    print(f"argmax: dump {argmax}, ref {ref_argmax}")
+
+    ok = (axes_ok and level_rel <= LEVEL_REL_TOLERANCE and argmax == ref_argmax
+          and interior_diff.max() <= MAX_DIFF_TOLERANCE)
+    print("OK" if ok else "FAIL")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

requirements.txt

@@ -3,8 +3,17 @@ libusb1>=3.1
 pyserial>=3.5,<4
 pyvisa>=1.14
 PyVISA-py>=0.7  # pure-Python VISA backend ("@py"), required by the SN9000 (and any visa_library="@py") path
-PyQt6>=6.6
+# PyQt6 6.8+ ships only manylinux_2_39 aarch64 wheels (glibc >= 2.39); Jetson /
+# Ubuntu 22.04 has glibc 2.35, so pip would fall back to a source build that
+# dies on qmake. 6.7.1 is the last release with a manylinux_2_28 aarch64 wheel.
+PyQt6>=6.6,<6.8; platform_machine == "aarch64"
+PyQt6>=6.6; platform_machine != "aarch64"
 pyqtgraph>=0.13.7
 rpi-hardware-pwm>=0.2.2,<1
 fastapi>=0.110           # embedded web UI (browser view + controls), served in-process
 uvicorn[standard]>=0.29  # ASGI server for the web UI, run on a background thread
+# CUDA headers + libnvrtc for building the vendored gpr_cpp library (3D SAR).
+# x86_64 dev machines only: on Jetson (aarch64) CUDA comes with JetPack at
+# /usr/local/cuda and build_cmake.sh falls back to it automatically.
+nvidia-cuda-nvrtc==13.3.33; platform_machine == "x86_64"   # nvrtc.h + libnvrtc
+nvidia-cuda-runtime==13.3.29; platform_machine == "x86_64" # cuda.h (Driver API)

run_config_examples/run_config_replay_vna.example.json

@@ -0,0 +1,205 @@
+{
+  "_comment": "Replay of the recorded VNA_AlGo tank005 dataset through the full pipeline (no hardware). The replay producer feeds the raw ring; pair it with NEUTRAL preprocess sets (calibration=1, reference=0) so the already-preprocessed recording passes through unchanged. Create them via GUI 'Create neutral sets' (name: neutral_replay) or python -m python_app.scripts.create_neutral_preprocess_sets --config <this file>.",
+  "radar": {
+    "model": "librevna_multi",
+    "serial": "206830985532",
+    "remote_host": "127.0.0.1",
+    "remote_port": 50209,
+    "driver_mode": "mock",
+    "mock_signal_hz": 5000000.0,
+    "visa_library": "",
+    "multi_device": {
+      "slave_serials": [
+        "206930965532",
+        "206930A15532"
+      ],
+      "force_external_reference": true,
+      "recovery_attempts": 3,
+      "output_switch_positions": 1,
+      "input_switch_positions": 1,
+      "stimulus_switch_positions": 1
+    },
+    "replay": {
+      "dataset_dir": "/home/awe/Documents/VNA_AlGo/librevna_multi_2-6GHz_751pts_-3dBm_tank005/librevna_multi_2-6GHz_751pts_-3dBm_tank005/preprocessed",
+      "loop": true,
+      "rate_scale": 1.0
+    },
+    "sweep": {
+      "start_hz": 2000000000.0,
+      "stop_hz": 6000000000.0,
+      "if_bandwidth_hz": 50000.0,
+      "stimulus_power_dbm": -3.0,
+      "points": 751
+    }
+  },
+  "switches": {
+    "port1": {
+      "name": "port1",
+      "driver_mode": "mock",
+      "driver": "h7992",
+      "radar_port": 1,
+      "positions": 2,
+      "default_position": 0,
+      "gpio_chip": "/dev/gpiochip0",
+      "pin_a": 17,
+      "pin_b": 27,
+      "invert_logic": false
+    },
+    "port2": {
+      "name": "port2",
+      "driver_mode": "mock",
+      "driver": "h7992",
+      "radar_port": 2,
+      "positions": 4,
+      "default_position": 0,
+      "gpio_chip": "/dev/gpiochip0",
+      "pin_a": 22,
+      "pin_b": 23,
+      "invert_logic": false
+    }
+  },
+  "control_button": {
+    "enabled": false,
+    "gpio_chip": "/dev/gpiochip0",
+    "pin": -1,
+    "active_low": true,
+    "bias": "",
+    "debounce_ms": 50,
+    "action": "capture_tmp_reference"
+  },
+  "run": {
+    "settling_ms": 0,
+    "idle_sleep_ms": 2,
+    "continuous": true,
+    "processing_live_config_path": "python_app/runtime/processing_live.json",
+    "locator_server": {
+      "device_id": 3,
+      "protocol_version": 1,
+      "host": "0.0.0.0",
+      "port": 8888,
+      "max_payload_bytes": 65536,
+      "client_queue_size": 32,
+      "logger_name": "locator_runtime"
+    },
+    "combos": [
+      { "input": 0, "output": 0 },
+      { "input": 1, "output": 0 },
+      { "input": 2, "output": 0 },
+      { "input": 3, "output": 0 },
+      { "input": 0, "output": 1 },
+      { "input": 1, "output": 1 },
+      { "input": 2, "output": 1 },
+      { "input": 3, "output": 1 }
+    ]
+  },
+  "preprocess": {
+    "s21": {
+      "calibration": {
+        "set_name": "neutral_replay",
+        "bundle_path": ""
+      },
+      "reference": {
+        "set_name": "neutral_replay",
+        "bundle_path": ""
+      }
+    },
+    "s11": {
+      "calibration": {
+        "open": { "set_name": "", "bundle_path": "" },
+        "short": { "set_name": "", "bundle_path": "" },
+        "load": { "set_name": "", "bundle_path": "" }
+      },
+      "reference": { "set_name": "", "bundle_path": "" }
+    },
+    "notch": {
+      "enabled": false,
+      "bands_hz": [],
+      "taper_width_hz": 40000000.0,
+      "taper_type": "cosine"
+    }
+  },
+  "gpr": {
+    "relative_permittivity": 1.0,
+    "tx_geometry": [
+      { "output_pos": 0, "x_m": 0.785, "y_m": 0.0, "z_m": 0.0 },
+      { "output_pos": 1, "x_m": -0.785, "y_m": 0.0, "z_m": 0.0 }
+    ],
+    "rx_geometry": [
+      { "input_pos": 0, "x_m": -0.42, "y_m": 0.0, "z_m": 0.0 },
+      { "input_pos": 1, "x_m": 0.48, "y_m": 0.0, "z_m": 0.0 },
+      { "input_pos": 2, "x_m": 0.18, "y_m": 0.0, "z_m": 0.0 },
+      { "input_pos": 3, "x_m": -0.12, "y_m": 0.0, "z_m": 0.0 }
+    ]
+  },
+  "rings": {
+    "raw": {
+      "name": "/radar_raw_simulator",
+      "capacity": 50,
+      "slot_size_bytes": 2097152
+    },
+    "raw_tap": {
+      "name": "/radar_raw_tap_simulator",
+      "capacity": 50,
+      "slot_size_bytes": 2097152
+    },
+    "preprocessed": {
+      "name": "/radar_preprocessed_simulator",
+      "capacity": 50,
+      "slot_size_bytes": 2097152
+    },
+    "preprocessed_tap": {
+      "name": "/radar_preprocessed_tap_simulator",
+      "capacity": 50,
+      "slot_size_bytes": 2097152
+    },
+    "results": {
+      "name": "/radar_results_simulator",
+      "capacity": 50,
+      "slot_size_bytes": 2097152
+    }
+  },
+  "gui": {
+    "version": 1,
+    "switches": {
+      "combo_mode": "text",
+      "combos_text": "0:0,1:0,2:0,3:0,0:1,1:1,2:1,3:1",
+      "single_input": "0",
+      "single_output": "0"
+    },
+    "processing": {
+      "selected_mode": "sar3d",
+      "sar3d": {
+        "input_positions": "0,1,2,3",
+        "output_positions": "0,1",
+        "min_depth_m": 3.2,
+        "max_depth_m": 10.0,
+        "start_freq_mhz": 2000.0,
+        "stop_freq_mhz": 6000.0,
+        "speed_m_s": 0.854,
+        "ignore_socket_speed_enabled": true,
+        "look_angle_deg": 6.0,
+        "direction_sign": 1.0,
+        "apply_freq_phase_correction": true,
+        "frame_radius": 6,
+        "edge_frame_weight": 0.75,
+        "pitch_deg": 6.0,
+        "center_depth_m": 5.6,
+        "half_width_x_m": 1.8,
+        "half_width_y_m": 1.0,
+        "half_width_z_m": 1.8,
+        "grid_nx": 150,
+        "grid_ny": 120,
+        "grid_nz": 160,
+        "use_compensation": true,
+        "normalize_pairs": true,
+        "bottom_view_deg": 0.0
+      }
+    },
+    "preprocess_dialog": {
+      "set_name": "neutral_replay",
+      "radar_config_dir": "",
+      "use_all_radar_configs": false,
+      "median_sweep_count": 5
+    }
+  }
+}

start.sh

@@ -225,14 +225,29 @@ run_privileged() {
 }
 
 ensure_system_dependencies() {
-    if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists libusb-1.0; then
+    # Qt >= 6.5 xcb platform plugin needs libxcb-cursor0; aarch64/Jetson images
+    # (and some minimal desktops) ship without it, and the GUI then dies at
+    # startup with "could not load the Qt platform plugin xcb". apt-only: other
+    # distros/managers name these differently and usually have them preinstalled.
+    local qt_gui_packages_missing=0
+    if command -v apt-get >/dev/null 2>&1 && command -v dpkg-query >/dev/null 2>&1; then
+        local package
+        for package in libxcb-cursor0 libxkbcommon-x11-0; do
+            if ! dpkg-query -W -f='${Status}' "${package}" 2>/dev/null | grep -q "install ok installed"; then
+                qt_gui_packages_missing=1
+            fi
+        done
+    fi
+
+    if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists libusb-1.0 \
+        && ((qt_gui_packages_missing == 0)); then
         return
     fi
 
     echo "[start.sh] Installing system dependency: libusb-1.0 dev headers..."
     if command -v apt-get >/dev/null 2>&1; then
         run_privileged apt-get update
-        run_privileged apt-get install -y pkg-config libusb-1.0-0-dev
+        run_privileged apt-get install -y pkg-config libusb-1.0-0-dev libxcb-cursor0 libxkbcommon-x11-0
     elif command -v dnf >/dev/null 2>&1; then
         run_privileged dnf install -y pkgconf-pkg-config libusb1-devel
     elif command -v yum >/dev/null 2>&1; then