projector version

README.md

@@ -74,6 +74,10 @@ 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 the external `gpr_cpp` library from the VNA_AlGo project. It
+  must be built **before** `make` (see below); its location is configurable via
+  the `GPR_CPP_DIR` make variable (default `/home/awe/Documents/VNA_AlGo/gpr_cpp`).
 
 ## Build and run
 
@@ -83,9 +87,20 @@ From the repository root:
 python3 -m venv .venv
 .venv/bin/python -m pip install --upgrade pip
 .venv/bin/python -m pip install -r requirements.txt
+# 3D SAR library (external, CMake + NVRTC; CUDA headers come from pip nvidia-* packages):
+bash /home/awe/Documents/VNA_AlGo/gpr_cpp/build_cmake.sh
 make                     # build the C++ binaries into build/bin/
 ```
 
+To verify the sar3d processor against the VNA_AlGo 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 gpr_cpp's ./build/standalone_bp on the same arguments
+```
+
 Run the desktop GUI:
 
 ```bash
@@ -99,6 +114,45 @@ 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.
 
+## 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.