How princeton-computational-imaging/radarfields works
1. What this repo is
Radar Fields is a Python/CUDA-oriented research codebase for learning a neural scene representation of FMCW radar in frequency space. The core workflow is: load radar sequences and preprocessing metadata, build a neural field, optimize it against radar observations, and optionally render/demo a pre-trained model.
2. Primary entry points
- main.py is the main training entry point.
- demo.py runs inference/demo mode using a pre-trained model.
- parse.py likely centralizes CLI/config parsing so both scripts can share the same runtime options.
The README indicates execution is heavily config-driven via configs/radarfields.ini plus a per-sequence preprocessing JSON.
3. Configuration and experiment wiring
configs/radarfields.ini is the main experiment config and likely defines model, data, and optimization settings. The CLI also accepts:
- --seq for the radar sequence name
- --preprocess_file for the preprocessing metadata
- --name for the run name
This makes the repo’s architecture centered around reproducible experiment configuration rather than hardcoded scripts.
4. Data ingestion boundary
radarfields/dataset.py and utils/data.py are the data-loading layer. They likely handle:
- loading radar frames / measurements
- reading preprocessing outputs such as calibration, poses, or sample geometry
- exposing training batches to the model
This is the main boundary between raw radar data on disk and the learning system.
5. Radar-specific signal handling
radarfields/radar.py contains the radar-domain abstraction: FMCW radar measurements, ranges, frequencies, and likely how observations are represented internally. This module is important because the project is not just generic neural rendering; it explicitly works in radar frequency space.
6. Sampling and field evaluation
radarfields/sampler.py likely defines how points or rays are sampled through the scene/radar volume before being passed to the network. In architecture terms, this sits between the dataset and the model: it converts loaded radar/pose data into the specific coordinates or samples the network learns from.
7. Neural field implementation
The model stack lives in radarfields/nn/:
- encoding.py for input encodings
- models.py for the core network definitions
- tcnn_utils.py for integration with tiny-cuda-nn
- pose_refinement.py for optimizing or correcting sensor pose estimates
This is the compute-heavy center of the repo and depends on GPU acceleration.
8. Pose optimization is a separate subsystem
radarfields/nn/pose_refinement.py and the README’s mention of Nerfstudio indicate pose refinement is treated as a distinct optimization step, not just a side effect of training. Architecturally, the system can jointly learn scene representation and improve pose accuracy, which matters for diagramming the optimization loop.
9. Training orchestration
radarfields/train.py and utils/train.py appear to manage the training loop, loss computation, logging, checkpoints, and evaluation hooks. The likely flow is:
dataset → sampler/radar representation → neural field → losses/metrics → optimizer update → saved checkpoint.
This layer is where the repo turns model + data into a usable experiment pipeline.
10. Visualization and outputs
radarfields/figures.py and utils/vis.py handle visualization of learned radar fields, reconstructions, or qualitative figures for the paper/demo. assets/ contains teaser media, and pre-trained models can be used without downloading the original datasets, which suggests the repo supports both research reproduction and standalone inference.
11. Repository structure and boundaries
The radarfields/ package contains the reusable core library, while utils/ contains supporting helpers for scripts and visualization. This separation suggests the package is designed so the main algorithmic pieces are importable, while top-level scripts provide the runnable experiment/application layer.
12. Technology/runtime constraints
The codebase is Python-based but assumes GPU execution through CUDA-enabled dependencies, especially tiny-cuda-nn. The README also explicitly calls out Nerfstudio for pose optimization. Those dependencies materially shape the architecture: the model and encoding layers are designed around high-performance CUDA-backed neural field training.
Main entry points: train.py train.py · models.py models.py · demo.py demo.py · dataset.py dataset.py
Components 18
Entry points
Top-level scripts for training and demo execution.
Core radarfields
Reusable package with data, radar representation, sampling, model, and training logic.
- dataset.py · Radar dataset boundary for loading sequences and preprocessing metadata.
radarfields/dataset.py - radar.py · Radar-specific representation of FMCW measurements and frequency-space quantities.
radarfields/radar.py - sampler.py · Converts loaded radar data into samples or coordinates for field evaluation.
radarfields/sampler.py - train.py · Orchestrates optimization, losses, metrics, logging, and checkpoints.
radarfields/train.py - figures.py · Figure generation and qualitative result assembly.
radarfields/figures.py
Neural field
GPU-oriented neural components and pose refinement.
- models.py · Core neural scene representation model definitions.
radarfields/nn/models.py - encoding.py · Feature encodings used before field evaluation.
radarfields/nn/encoding.py - tcnn_utils.py · Integration helpers for tiny-cuda-nn accelerated components.
radarfields/nn/tcnn_utils.py - pose_refinement.py · Pose correction and refinement subsystem.
radarfields/nn/pose_refinement.py
Utilities
Supporting data, training, and visualization helpers.
- data.py · Supporting data utilities for scripts and loading.
utils/data.py - train utils · Supporting helpers for training workflows.
utils/train.py - vis.py · Rendering and visualization helpers for figures and demos.
utils/vis.py
Configuration
Experiment configuration and packaging.
- radarfields.ini · Main experiment configuration for model, data, and optimization settings.
configs/radarfields.ini - setup.py · Package installation and distribution metadata.
setup.py
Connections 21
- main.py → parse.py: reads args · Main training uses shared CLI/runtime options.
- demo.py → parse.py: reads args · Demo mode shares the same configuration parsing.
- parse.py → radarfields.ini: loads config · CLI options are combined with experiment config.
- main.py → train.py: starts · Training entry invokes the training pipeline.
- demo.py → train.py: runs eval · Demo mode reuses model loading and evaluation flow.
- train.py → dataset.py: consumes · Training pulls radar sequences and metadata from the dataset layer.
- train.py → sampler.py: samples · Training requests spatial or radar samples for learning.
- dataset.py → radar.py: wraps · Dataset uses radar-domain representation of observations.
- dataset.py → data.py: uses · Dataset relies on supporting loading utilities.
- sampler.py → encoding.py: prepares · Samples are encoded before entering the neural field.
- sampler.py → models.py: feeds · Sampled inputs are evaluated by the field model.
- models.py → encoding.py: uses · Model construction depends on input encodings.
- models.py → tcnn_utils.py: accelerates · Core model can use CUDA-backed tiny-cuda-nn helpers.
- train.py → models.py: optimizes · Training updates the neural field parameters.
- train.py → pose_refinement.py: refines · Training can jointly refine sensor pose estimates.
- pose_refinement.py → tcnn_utils.py: gpu path · Pose refinement sits alongside GPU-accelerated neural components.
- train.py → train utils: uses · Training loop depends on shared helper routines.
- figures.py → vis.py: renders · Figure generation uses visualization helpers.
- figures.py → assets: exports · Qualitative outputs are paired with repository media assets.
- demo.py → vis.py: renders · Demo mode visualizes learned radar fields and reconstructions.
- setup.py → tcnn_utils.py: packages · Distribution targets the CUDA-oriented dependencies used by the core model.