How ebhrz/tdl-gnss works
1. Overall shape
- This repo is a command-line GNSS learning pipeline, not a general-purpose application.
- The architecture is centered on a single flow: dataset/config → preprocessing cache → model training or evaluation → GNSS position output.
2. Primary entry points
- preprocess.py prepares data and builds cached intermediate artifacts.
- train.py trains the deep model using cached GNSS features and ground truth.
- evaluate.py runs inference and produces final positioning results.
- baseline.py runs a non-learning comparison baseline, described in the README as GoGPS.
3. Configuration is the main control boundary
- The project is entirely config-driven through JSON files in config/.
- There are two data modes:
- Custom datasets: specify obs, gt, start_utc, end_utc, etc.
- KLT datasets: specify prefix plus a list of dataset config files under datasets.
- The config also controls mode, loss_type, save_path, model_path, device, and epoch.
4. Dataset boundary and input sources
- Input data is external to the codebase and expected to live under a local folder such as data/ or KLTDataset/.
- The repo consumes:
- GNSS observation files,
- ephemeris files,
- ground-truth CSVs,
- and, for KLT, dataset metadata configs.
- This makes the repo a processing and learning layer on top of dataset files, not a dataset host.
5. Preprocessing/cache layer
- The README says preprocessing generates preprocess.pkl files in the target folder.
- This layer exists to avoid recomputing positioning-related quantities during training.
- Architecturally, it is the key performance boundary: expensive GNSS feature generation is moved out of the inner training loop.
6. GNSS computation core lives outside this repo
- The README explicitly says core functionality has moved to TASGNSS and the project is built on pyrtklib and TASGNSS.
- That means this repo mainly orchestrates:
- feature extraction,
- learning,
- and feedback into GNSS positioning,
while the underlying GNSS math/solver functions come from external libraries.
7. Model subsystem
- The only model code in-tree is model/model.py, so the learned component is intentionally compact.
- The README describes the network as predicting pseudorange corrections and weights from GNSS-derived features such as:
- C/N0,
- elevation angle,
- residuals from an equal-weight WLS solution,
- and in the newer update, azimuth and system one-hot encoding.
- This is a tightly coupled model, not a standalone classifier or regressor.
8. Training loop and feedback path
- During training, the network output is fed back into a weighted least squares (WLS) GNSS solver.
- The solver produces the final position estimate, which is compared against ground truth.
- The loss is computed on the position error rather than directly on the network outputs, so the model learns through the GNSS solver boundary.
- This is the repo’s most important data flow: raw GNSS features → neural adjustments → WLS position → loss vs GT.
9. Inference/evaluation path
- evaluate.py uses the same preprocessing and solver path, but without backpropagation.
- The README states that the WLS output is the final predicted position during prediction.
- This implies training and inference share the same GNSS/solver pipeline, with only the learning step removed at evaluation time.
10. Model variants and training behavior
- The README mentions bias-only, weight-only, and hybrid network training behavior.
- This suggests the model layer is configurable in terms of what it predicts, but the repository keeps those details behind the training script and model/model.py.
11. Outputs and artifacts
- Results are written under save_path.
- Typical artifacts include:
- cached preprocessing files,
- trained model checkpoints,
- evaluation outputs/results.
- The filesystem layout is therefore part of the architecture: each experiment is isolated by config and output directory.
12. Technology/runtime boundaries that matter
- The repo is a Python project with pip-based dependencies in requirements.txt.
- It is designed to run on CPU as a practical default; the README notes training is often faster on CPU because the workload is logic-heavy rather than GPU-heavy.
- The project is therefore best understood as a Python GNSS processing pipeline with a lightweight learned module, rather than a large deep-learning stack.
13. External integrations
- The dataset boundary is important: KLT support is special-cased, and custom datasets must match the expected GNSS/GT file conventions.
- The baseline comparison is external to the learned pipeline.
- The repo also references linked external projects and datasets as part of the broader system: TASGNSS, pyrtklib, and KLTDataset.
Main entry points: evaluate.py Evaluate · train.py Train · preprocess.py Preprocess · baseline.py Baseline
Components 17
Entry points
CLI scripts that drive preprocessing, training, evaluation, and baseline comparison.
- Preprocess · Builds cached GNSS preprocessing artifacts for later runs.
preprocess.py - Train · Runs model training against cached features and ground truth.
train.py - Evaluate · Runs inference and emits final positioning results.
evaluate.py - Baseline · Runs the GoGPS comparison baseline.
baseline.py
Config layer
JSON experiment definitions and dataset selection boundary.
- Train config · Main training experiment settings and dataset selection.
config/train.json - Cross config · Alternative training configuration for cross-dataset setup.
config/train_cross.json - KLT test 1 · KLT evaluation configuration for one dataset set.
config/test_klt1.json - KLT test 2 · KLT evaluation configuration for another dataset set.
config/test_klt2.json - Whampoa · Dataset-specific configuration example.
config/whampoa_0521.json
GNSS pipeline
Preprocessing, solver-backed training, and inference flow.
- Preprocess cache · Cached preprocessing output such as preprocess.pkl.
- WLS solver · Weighted least squares position solver used in both training and inference.
- Position loss · Compares solver-derived position against ground truth.
Learning module
Compact neural network used to predict GNSS corrections and weights.
- Model · Predicts pseudorange corrections and weights from GNSS features.
model/model.py - GNSS features · Inputs such as C/N0, elevation, residuals, azimuth, and system encoding.
External systems
Datasets and third-party GNSS libraries that sit outside the repository.
- Dataset files · Observation files, ephemeris, ground truth, and dataset metadata outside the repo.
- TASGNSS · External GNSS core functionality used by the pipeline.
- pyrtklib · Underlying RTK/GNSS library dependency.
Connections 21
- Train config → Preprocess: drives · Config selects dataset mode, paths, and preprocessing behavior.
- KLT test 1 → Evaluate: drives · Evaluation config selects KLT datasets and output paths.
- KLT test 2 → Evaluate: drives · Evaluation config selects KLT datasets and output paths.
- Whampoa → Preprocess: drives · Dataset-specific config is consumed by preprocessing.
- Whampoa → Train: drives · Same config family controls training runs and experiment output.
- Preprocess → Dataset files: reads · Consumes observation, ephemeris, and ground-truth files.
- Preprocess → Preprocess cache: writes · Generates cached preprocessing artifacts.
- Train → Preprocess cache: reads · Uses cached features instead of recomputing preprocessing.
- Evaluate → Preprocess cache: reads · Uses the same cached preprocessing path for inference.
- Train → GNSS features: consumes · Builds model inputs from GNSS-derived features.
- Evaluate → GNSS features: consumes · Builds inference inputs from the same feature set.
- GNSS features → Model: inputs · Feature vectors feed the compact prediction model.
- Model → WLS solver: predicts corrections · Model outputs adjust pseudorange weights/corrections used by WLS.
- WLS solver → Position loss: produces position · Solver returns the estimated position used for supervision.
- Position loss → Train: backpropagates · Training optimizes position error rather than raw network outputs.
- WLS solver → Evaluate: final output · Inference returns WLS position as the final predicted result.
- Train → TASGNSS: depends on · Training pipeline relies on external GNSS functionality.
- Evaluate → TASGNSS: depends on · Evaluation uses the same external GNSS computation layer.
- TASGNSS → pyrtklib: built on · External GNSS stack sits on pyrtklib.
- Baseline → Dataset files: reads · Baseline compares against the same dataset inputs.
- Baseline → WLS solver: compares against · GoGPS baseline is used as a non-learning reference.