README.md

# GRADE

**Single-Frame Generative Radar Depth Estimation Under Visual Degradation**

Bin Zhao, Patrick Chiou, Nakul Garg — Rice University
ACM MobiCom 2026 · Austin, TX

Dense 3D depth perception fails under smoke, fog, and darkness because optical sensors cannot
penetrate airborne particulates. mmWave radar works in these conditions but its limited angular
resolution gives depth that is metrically grounded yet structurally incomplete. GRADE grounds
pretrained generative priors in single-frame radar geometry to recover high-fidelity metric depth —
without SAR and without a reliable camera.

Trained and evaluated on ~95K synchronized frames across 12 buildings with real smoke using
leave-building-out splits, GRADE reaches an MAE of 0.303 m in clear conditions and 0.313 m under
smoke, ahead of every baseline on all reported metrics.

## Project page

<https://phi-lab-rice.github.io/GRADE/>

Served from [`docs/`](docs/) via GitHub Pages.

## Code and artifacts

The evaluation code is included directly in this repository under
[`evaluation/`](evaluation/) and [`src/`](src/). It includes inference, metric
computation, saved-result reproduction, and the evaluation configuration.

The [complete Hugging Face model repository](https://huggingface.co/phi-lab-rice/GRADE)
contains the executable code, all model checkpoints, and the complete
reference results. Download it with `hf download phi-lab-rice/GRADE --local-dir
grade-models` and run the commands below from `grade-models`.

### Artifact evaluation reproduction

After installing `environment.txt`, the CPU-only E1 command is:

```bash
python evaluation/reproduce_paper.py --mode saved
```

The GitHub checkout contains pointer files in place of some large reference
`.npz` assets. If running the GitHub source, pass
`--reference-root /path/to/grade-models/evaluation/reference_results` to use
the downloaded model package without changing the checkout. E1 writes regenerated
results under `evaluation/reproduced_results/saved/`.

For E2, run inference and metrics for each required model, then reproduce from
the fresh merged CSVs:

```bash
python evaluation/run_inference.py --model grade --gpuid 0
python evaluation/run_metrics.py --model grade --workers 1
python evaluation/reproduce_paper.py --mode local
```

`--mode local` includes the available model rows in Tables 2–6 and skips a
table or figure when none of its required inputs exist. The output lists each
skip. Table 7 states its source in the generated report: if
`evaluation/metric_results/sampling_step/sampling_step_ablation_pooled.csv`
exists, it uses that fresh file; otherwise it uses the released reference
sampling-step results. Ordinary E2 model runs do not recompute Table 7.

Use `--workers 1` for the 3D metric stage. Multiple workers have deadlocked on
at least one evaluation host and are not validated for this release. The 2D
stage does not use this setting.

The LPIPS metric may download the AlexNet weights (about 233 MB) from
`download.pytorch.org` on first use. For an offline metric run, populate the
TorchVision weight cache before disconnecting; running the LPIPS metric once
online in the same environment is sufficient. Set `TORCH_HOME` to keep that
cache in a known location.

Anonymous downloads of the many small Smoke-Eval files may be rate limited by
Hugging Face. Log in with `hf auth login` on the download host, or set `HF_TOKEN`
through the shell's secure credential mechanism, before `hf download`. The
repositories are public; authentication only increases download reliability.

### Dataset

The synchronized raw dataset is shared through
[Hugging Face](https://huggingface.co/datasets/phi-lab-rice/GRADE_Dataset). Please
follow its access and usage terms. The dataset-processing scripts are available
in [`processing_code/`](processing_code/) here and in that dataset repository.

The raw dataset repository is organized as follows:

```text
GRADE Dataset/
├── processing_code/  # dataset-processing scripts
├── GRADE_Eval_Raw/   # evaluation data
└── GRADE_Train_Raw/  # training data
```

For the artifact evaluation checkpoints and processed Smoke-Eval inputs, use the
[complete model repository](https://huggingface.co/phi-lab-rice/GRADE) and the
separate [evaluation dataset](https://huggingface.co/datasets/mypersonalsharingspot11/evaluation_dataset).
The model package includes release-relative checkpoint configurations.

To use the processing scripts locally from this repository:

```bash
cd processing_code

# Full radar + ZED + DJI processing
python processor.py --dataset /path/to/raw_dataset

# RGB/depth-only processing
python processor_rgb.py --dataset /path/to/raw_dataset

# Radar point-cloud extraction
python processor_pcd.py --dataset /path/to/raw_dataset
```

Each processor accepts `--sequences` to process selected sequences. The
generated files are written under `processed/<sequence_name>/`, including
synchronized timestamps and the processed radar, RGB, depth, or point-cloud
outputs appropriate to the selected pipeline. See the docstrings in the
processing scripts for optional modality skips and split-file arguments.

For reproducible evaluation, install the dependencies from
[`environment.txt`](environment.txt) before running the evaluation code. A
typical setup is:

```bash
python3.11 -m venv grade-venv
source grade-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r environment.txt
```

After preparing the environment, follow the command-line help and docstrings
in the scripts under [`evaluation/`](evaluation/). Full evaluation also
requires downloading the checkpoints and the required Smoke-Eval directories
from the artifact repositories linked above.

## Citation

```bibtex
@inproceedings{zhao2026grade,
  title     = {GRADE: Single-Frame Generative Radar Depth Estimation Under Visual Degradation},
  author    = {Zhao, Bin and Chiou, Patrick and Garg, Nakul},
  booktitle = {Proceedings of the 32nd Annual International Conference on
               Mobile Computing and Networking (MobiCom '26)},
  year      = {2026},
  doi       = {10.1145/3795866.3844478}
}
```

## Acknowledgement

The project page is based on the [Nerfies](https://nerfies.github.io/) template
(CC BY-SA 4.0), with the layout adapted from our
[RadarSFD project page](https://github.com/phi-lab-rice/RadarSFD/tree/main/docs).