NLOS: Physics-Guided Training and Evaluation Pipeline

This repository contains the core code for physics-guided NLOS reconstruction experiments used in our paper workflow, including:

• Training (train_256.py)
• Synthetic seen/unseen evaluation (eval_only.py)
• Real-world evaluation from checkpoint (eval_real_from_ckpt.py)
• Model and data pipeline (DL_inference/)
• Figure/evaluation utilities (tools/eval/)

1. Environment

Recommended: conda with CUDA-enabled PyTorch.

Example:

conda create -n nlos python=3.9 -y
conda activate nlos
# install torch/cu117 and dependencies according to your GPU/CUDA

2. Data

• Synthetic training data (LFE motorbike benchmark):
  • https://drive.google.com/file/d/183VAD_wuVtwkyvfaBoguUHZgHu065BNW/view
• Real-world benchmark references:
  • FK: https://github.com/computational-imaging/nlos-fk
  • NLOST: https://github.com/Depth2World/NLOST
• Self-captured real measurements:
  • https://drive.google.com/drive/folders/1DcmH7jZFZgFOA6lACIkks2rQnIxSiIuJ

Set dataset paths in your runtime config (see DL_inference/inference/config.py), or export the environment variables below. No absolute machine-specific paths are hard-coded in this repository; every default is either repo-relative or a /path/to/... placeholder you are expected to override.

Variable	Used by	Default	Meaning
DATA_ROOT	scripts/*.sh	/path/to/nlos_dataset	Root of the datasets (bike, Unseen_spad, preFK, ...)
REPO_ROOT	scripts/*.sh	auto-detected from the script location	Repository checkout
PYTHON_BIN	scripts/*.sh	python	Python interpreter to use
CONDA_SH	scripts/run_eval_only.sh	$HOME/miniconda3/etc/profile.d/conda.sh	conda shell hook
NLOS_DATA_ROOT	tools/eval/*.py, DL_inference/inference/config.py	/path/to/nlos_dataset	Same as DATA_ROOT, for Python entry points
NLOS_PROJECT_ROOT	tools/eval/*.py	repository root	Where reports/ and results live
NLOS_PYTHON	tools/eval/run_full_eval6.py	python	Interpreter used for spawned eval jobs
NLOS_FK_STATUE_MAT	DL_inference/utils/fk.py	/path/to/nlos-fk/statue.mat	Optional FK demo input

Example:

export DATA_ROOT=/mnt/datasets/nlos
export NLOS_DATA_ROOT="$DATA_ROOT"
bash scripts/run_train_physguard_trtlike_10ep.sh

3. Core Workflow

3.1 Training

python train_256.py

Also available via scripts:

bash scripts/run_train_physguard_trtlike_10ep.sh
bash scripts/run_train_sensorcalib_physguard_ep9.sh

3.2 Seen/Unseen Evaluation

python eval_only.py \
  --ckpt /path/to/epoch9.pth \
  --seen_datafolder /path/to/seen \
  --unseen_datafolder /path/to/unseen \
  --run_real 0 \
  --out_json eval_summary.json

3.3 Real-World Evaluation

python eval_real_from_ckpt.py \
  --ckpt /path/to/epoch9.pth \
  --real_datafolder /path/to/real_measurements \
  --real_svfolder eval_real_outputs

4. Per-Epoch Stability / Collapse Analysis

Tools in tools/eval/ support per-epoch evaluation and plotting, including:

• eval_physguard_unseen_per_epoch.py
• plot_physguard_unseen_per_epoch.py

These are used to analyze late-epoch degradation trends.

5. Data/Code Availability Statement (Paper)

Code and scripts are released in this repository. Datasets are linked above according to their original licenses/availability.

6. Notes

• This repository intentionally excludes heavy artifacts (checkpoints, archives, generated results).
• If you need reproducibility bundles, keep them in a separate storage/release package.