# princeton-computational-imaging/radarfields architecture

> Architecture diagram of the GitHub repository princeton-computational-imaging/radarfields, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/princeton-computational-imaging/radarfields
- Repository: https://github.com/princeton-computational-imaging/radarfields

## Overview

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: [`radarfields/train.py`](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/train.py) (train.py), [`radarfields/nn/models.py`](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/models.py) (models.py), [`demo.py`](https://github.com/princeton-computational-imaging/radarfields/blob/main/demo.py) (demo.py), [`radarfields/dataset.py`](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/dataset.py) (dataset.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entry points"]
  node_node_main["main.py<br/>train entry<br/>[main.py]"]
  node_node_demo["demo.py<br/>demo entry<br/>[demo.py]"]
  node_node_parse["parse.py<br/>cli config<br/>[parse.py]"]
end

subgraph group_group_core["Core radarfields"]
  node_node_dataset[("dataset.py<br/>data loader<br/>[dataset.py]")]
  node_node_radar["radar.py<br/>radar domain<br/>[radar.py]"]
  node_node_sampler["sampler.py<br/>sampling<br/>[sampler.py]"]
  node_node_train["train.py<br/>training loop<br/>[train.py]"]
  node_node_figures["figures.py<br/>[figures.py]"]
end

subgraph group_group_nn["Neural field"]
  node_node_nn_models{{"models.py<br/>field models<br/>[models.py]"}}
  node_node_nn_encoding["encoding.py<br/>input encodings<br/>[encoding.py]"]
  node_node_nn_tcnn["tcnn_utils.py<br/>cuda bridge<br/>[tcnn_utils.py]"]
  node_node_pose["pose_refinement.py<br/>pose optimization<br/>[pose_refinement.py]"]
end

subgraph group_group_utils["Utilities"]
  node_node_data_utils["data.py<br/>data helpers<br/>[data.py]"]
  node_node_train_utils["train utils<br/>training helpers<br/>[train.py]"]
  node_node_vis["vis.py<br/>visualization<br/>[vis.py]"]
end

subgraph group_group_config["Configuration"]
  node_node_config["radarfields.ini<br/>experiment config<br/>[radarfields.ini]"]
  node_node_setup["setup.py<br/>packaging<br/>[setup.py]"]
end

subgraph group_group_assets["Assets"]
  node_node_assets["assets<br/>media"]
end

node_node_main -->|"reads args"| node_node_parse
node_node_demo -->|"reads args"| node_node_parse
node_node_parse -->|"loads config"| node_node_config
node_node_main -->|"starts"| node_node_train
node_node_demo -->|"runs eval"| node_node_train
node_node_train -->|"consumes"| node_node_dataset
node_node_train -->|"samples"| node_node_sampler
node_node_dataset -->|"wraps"| node_node_radar
node_node_dataset -->|"uses"| node_node_data_utils
node_node_sampler -->|"prepares"| node_node_nn_encoding
node_node_sampler -->|"feeds"| node_node_nn_models
node_node_nn_models -->|"uses"| node_node_nn_encoding
node_node_nn_models -->|"accelerates"| node_node_nn_tcnn
node_node_train -->|"optimizes"| node_node_nn_models
node_node_train -->|"refines"| node_node_pose
node_node_pose -.->|"gpu path"| node_node_nn_tcnn
node_node_train -->|"uses"| node_node_train_utils
node_node_figures -->|"renders"| node_node_vis
node_node_figures -->|"exports"| node_node_assets
node_node_demo -->|"renders"| node_node_vis
node_node_setup -.->|"packages"| node_node_nn_tcnn

click node_node_main "https://github.com/princeton-computational-imaging/radarfields/blob/main/main.py"
click node_node_demo "https://github.com/princeton-computational-imaging/radarfields/blob/main/demo.py"
click node_node_parse "https://github.com/princeton-computational-imaging/radarfields/blob/main/parse.py"
click node_node_config "https://github.com/princeton-computational-imaging/radarfields/blob/main/configs/radarfields.ini"
click node_node_dataset "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/dataset.py"
click node_node_radar "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/radar.py"
click node_node_sampler "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/sampler.py"
click node_node_train "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/train.py"
click node_node_nn_models "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/models.py"
click node_node_nn_encoding "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/encoding.py"
click node_node_nn_tcnn "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/tcnn_utils.py"
click node_node_pose "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/pose_refinement.py"
click node_node_data_utils "https://github.com/princeton-computational-imaging/radarfields/blob/main/utils/data.py"
click node_node_train_utils "https://github.com/princeton-computational-imaging/radarfields/blob/main/utils/train.py"
click node_node_vis "https://github.com/princeton-computational-imaging/radarfields/blob/main/utils/vis.py"
click node_node_figures "https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/figures.py"
click node_node_assets "https://github.com/princeton-computational-imaging/radarfields/tree/main/assets"
click node_node_setup "https://github.com/princeton-computational-imaging/radarfields/blob/main/setup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_demo,node_node_parse toneBlue
class node_node_dataset,node_node_radar,node_node_sampler,node_node_train,node_node_figures toneAmber
class node_node_nn_models,node_node_nn_encoding,node_node_nn_tcnn,node_node_pose toneMint
class node_node_data_utils,node_node_train_utils,node_node_vis toneRose
class node_node_config,node_node_setup toneIndigo
class node_node_assets toneTeal
```

## Components

### Entry points

Top-level scripts for training and demo execution.

- [main.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/main.py): train entry · Primary training entry point. · `main.py`
- [demo.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/demo.py): demo entry · Inference and demo entry point for pretrained models. · `demo.py`
- [parse.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/parse.py): cli config · Shared command-line and runtime option parsing. · `parse.py`

### Core radarfields

Reusable package with data, radar representation, sampling, model, and training logic.

- [dataset.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/dataset.py): data loader · Radar dataset boundary for loading sequences and preprocessing metadata. · `radarfields/dataset.py`
- [radar.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/radar.py): radar domain · Radar-specific representation of FMCW measurements and frequency-space quantities. · `radarfields/radar.py`
- [sampler.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/sampler.py): sampling · Converts loaded radar data into samples or coordinates for field evaluation. · `radarfields/sampler.py`
- [train.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/train.py): training loop · Orchestrates optimization, losses, metrics, logging, and checkpoints. · `radarfields/train.py`
- [figures.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/figures.py): figures · Figure generation and qualitative result assembly. · `radarfields/figures.py`

### Neural field

GPU-oriented neural components and pose refinement.

- [models.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/models.py): field models · Core neural scene representation model definitions. · `radarfields/nn/models.py`
- [encoding.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/encoding.py): input encodings · Feature encodings used before field evaluation. · `radarfields/nn/encoding.py`
- [tcnn_utils.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/tcnn_utils.py): cuda bridge · Integration helpers for tiny-cuda-nn accelerated components. · `radarfields/nn/tcnn_utils.py`
- [pose_refinement.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/radarfields/nn/pose_refinement.py): pose optimization · Pose correction and refinement subsystem. · `radarfields/nn/pose_refinement.py`

### Utilities

Supporting data, training, and visualization helpers.

- [data.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/utils/data.py): data helpers · Supporting data utilities for scripts and loading. · `utils/data.py`
- [train utils](https://github.com/princeton-computational-imaging/radarfields/blob/main/utils/train.py): training helpers · Supporting helpers for training workflows. · `utils/train.py`
- [vis.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/utils/vis.py): visualization · Rendering and visualization helpers for figures and demos. · `utils/vis.py`

### Configuration

Experiment configuration and packaging.

- [radarfields.ini](https://github.com/princeton-computational-imaging/radarfields/blob/main/configs/radarfields.ini): experiment config · Main experiment configuration for model, data, and optimization settings. · `configs/radarfields.ini`
- [setup.py](https://github.com/princeton-computational-imaging/radarfields/blob/main/setup.py): packaging · Package installation and distribution metadata. · `setup.py`

### Assets

Media and example outputs.

- [assets](https://github.com/princeton-computational-imaging/radarfields/tree/main/assets): media · Teaser and example media assets. · `assets`

## Connections

- 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.
