sar3d: GPU port of the notebook with four views

The sar3d processor is rewritten as a checked port of Multi_antenna_3D_clean_v1.ipynb:
NVRTC kernels, timing from the trace stamps, notebook parameter names and one cubic
SAR_VOXEL_M. It adds front, side, top and 3D views, drops gpr_cpp and the parity tools,
and the GUI speed now applies only while the socket speed is ignored.

README.md

@@ -23,9 +23,9 @@ simply skips to the freshest frame:
 2. **Preprocessing** — `data_preprocessor` applies through/OSL calibration,
    reference subtraction, and optional frequency-domain notch filtering.
 3. **Processing** — `data_processor` runs the selected processing mode and emits
-   results (pass-through traces, B-scan images, or GPR images with detected
-   objects). Detected objects are additionally broadcast to subscribers over a TCP
-   locator server.
+   results (pass-through traces, B-scan images, GPR images with detected objects,
+   or 3D SAR views). Detected objects are additionally broadcast to subscribers
+   over a TCP locator server.
 
 The **Python application** (`python_app`) starts and monitors the C++ binaries,
 reads the result rings, renders the live view with pyqtgraph, and exposes the same
@@ -55,12 +55,19 @@ controls plus a pixel-identical live plot through an embedded web UI.
 - **bscan** — depth-versus-sweep B-scan heatmap.
 - **gpr** — coherent back-projection GPR imaging with object detection.
 - **legacy_gpr** — ellipse-intersection MIMO localization (point and extended/region modes).
+- **sar3d** — 3D SAR of the reference notebook `Multi_antenna_3D_clean_v1.ipynb`
+  on an NVIDIA GPU: front (X-Y), side (Z-Y), top (X-Z) and 3D views of the imaged
+  volume. Its settings carry the notebook's parameter names; the scene window is
+  fixed (X −2…2 m, height −0.5…2 m above the ground), its range extent follows
+  `MIN_DEPTH`/`MAX_DEPTH`, and the voxels are cubes with edge `SAR_VOXEL_M`
+  (default 2 cm). The radar motion is corrected from each trace's capture
+  timestamps, so the sweep timing needs no parameters.
 
 ## Repository layout
 
 | Path | Contents |
 | --- | --- |
-| `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). |
+| `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). |
 | `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,13 +81,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`).
+- For the `sar3d` processor: an NVIDIA GPU with its driver (`libcuda`). The
+  kernels are compiled at run time by NVRTC, so there is no nvcc step; `make`
+  needs only `nvrtc.h`, `cuda.h` and `libnvrtc`, taken from the pip
+  `nvidia-cuda-*` packages in `.venv` (`requirements.txt`, x86_64; CUDA 13 covers
+  Turing and newer GPUs) or from a system toolkit in `/usr/local/cuda` (Jetson).
+  Without them everything else still builds, and sar3d reports that CUDA is
+  missing — a Raspberry Pi needs none of it.
 
 ## Build and run
 
@@ -93,20 +100,9 @@ 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
-```
+`make` builds the sar3d GPU code when it finds CUDA (see Requirements) and
+prints a note when it does not. After installing the CUDA requirements into an
+existing venv, run `make` again: it notices the change and rebuilds that part.
 
 Run the desktop GUI:
 
@@ -134,17 +130,12 @@ for the CUDA-backed `sar3d` processor:
 #    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):
+# 2. normal launch; make takes the JetPack CUDA from /usr/local/cuda
+#    (requirements.txt installs no pip nvidia-* packages on aarch64) and the
+#    driver's /usr/lib/aarch64-linux-gnu/nvidia/libcuda.so.1:
 ./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:
@@ -175,14 +166,13 @@ A ready profile for the VNA_AlGo tank005 dataset is provided:
     --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 sar3d processor keeps about 75 MB of buffers on the GPU at the default
+2 cm voxel and depth 2…8 m (plus the CUDA context). The volume grows as
+1/`SAR_VOXEL_M`³: 1 cm takes about 600 MB and ran about 6 times slower in
+testing. If the GPU has no room, it logs the CUDA error once and publishes empty
+results until memory frees.
 
 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.