Beyond Endpoints: Path-Centric Reasoning for Vectorized Off-Road Network Extraction

[ArXiv Paper] | [Interactive Tool] | [WildRoad Dataset]

📖 Introduction

MagRoad introduces a novel path-centric reasoning approach for extracting vectorized road networks, specifically designed to handle the challenges of off-road and wild environments. Unlike node-centric methods (sam_road series), our model focuses on the connectivity and topology of paths, enabling robust extraction in complex terrains.

Extended for GPS Heatmap Data: This repository now includes support for training and inference on GPS heatmap data (e.g., AllTrails hiking trails), in addition to the original satellite imagery datasets. GPS heatmaps represent user activity intensity and pose unique challenges compared to satellite imagery.

Node-centric models suffer from path ambiguity due to sparse features, path-centric sampling resolves path ambiguity by leveraging evidence along the entire edge.

Key Features:

• 🤖 Robust Extraction Pipeline: Path-centric reasoning for reliability in complex terrains.
• 🗺️ GPS Heatmap Support: Train and infer on GPS activity heatmaps (hiking trails, running routes, etc.)
• 🖱️ Interactive Annotation: Lightweight tool for faster, low-effort annotation and refinement.
• 🌍 WildRoad Dataset: A new benchmark for challenging scenarios.

Supported Datasets:

Dataset	Input Type	Patch Size	Config File	Status
WildRoad	Satellite RGB	1024×1024	toponet_vitb_1024_wild_road.yaml	✅ Official
Global-Scale	Satellite RGB	512×512	toponet_vitb_512_globalscale.yaml	✅ Official
City-Scale	Satellite RGB	512×512	See cityspace branch	✅ Legacy
SpaceNet	Satellite RGB	400×400	See cityspace branch	✅ Legacy
AllTrails	GPS Heatmap	512×512	toponet_vitb_512_at_data.yaml	✅ New

📊 Demo

🤖 Automated Extraction

MaGRoad demonstrates effective road extraction results across four diverse datasets: City-Scale, Global-Scale, SpaceNet, and WildRoad.

🖱️ Interactive Annotation Tool

Manual Annotation (QGIS)	Interactive Annotation (Ours)

To address the bottleneck of creating large-scale vectorized datasets, we developed the first interactive road extraction algorithm and integrated it into a seamless Web Application. It transforms the workflow: instead of tedious manual plotting (e.g., QGIS), our model intelligently automates path connectivity based on sparse user clicks, drastically reducing annotation time.

📢 Open Source: The full codebase for both the interactive algorithm and the annotation tool has been released here.

---

🛠️ Quick Start

1. Clone the repository

   git clone https://github.com/xiaofei-guan/MaGRoad.git
   cd MaGRoad

2. Environment Setup

   conda create -n magroad python=3.8 # we use python 3.8.19
   conda activate magroad
   pip install -r requirements.txt

   Note: Ensure you have PyTorch and CUDA installed compatible with your system.

📥 Model Preparation

Please download the ViT-B checkpoint from the official SAM repository and place it under sam/ckpt:

mkdir -p sam/ckpt
# Save sam_vit_b_01ec64.pth here

📂 Data Preparation

We support:

• WildRoad benchmark (off-road satellite imagery)
• Global-Scale dataset (satellite imagery)
• AllTrails GPS Heatmap Data (hiking trails from GPS activity)

WildRoad Dataset:

cd wildroad
bash preprocess_data/preprocess.sh ./wild_road ./wild_road_GLG ./wild_road_mask 16

GlobalScale Dataset:

cd globalscale
bash preprocess_data/preprocess.sh ./Globalscale ./Globalscale_GLG ./Globalscale_mask 16

AllTrails GPS Heatmap Data:

Data Format Requirements:

• Heatmaps: TIF files (512x512, grayscale 0-255) representing GPS activity intensity
• Graphs: GraphML files with LINESTRING geometry (EPSG:4326 coordinates)
• Directory structure:

  at_data/
  ├── train/
  │   └── {area_name}/
  │       ├── heatmap/
  │       │   └── {tile_x}_{tile_y}_16_heatmap.tif
  │       └── graph/
  │           └── {area_name}_area_graph_final.graphml
  ├── val/
  └── test/
  

Preprocessing:

# Preprocess GPS heatmaps and graphs into training format
python preprocess_at_data.py \
    --input_dir ./at_data \
    --output_dir ./wildroad/at_data_processed \
    --tile_size 512 \
    --zoom 16

# Precompute GLG (Graph Label Generator) files for topology training
python precompute_at_glg.py

Key Differences from Satellite Data:

• Input: GPS activity heatmaps (0-255 intensity) instead of RGB satellite images
• Edge Width: 10-pixel-wide edge masks optimal for GPS positioning tolerance
• Tile Size: 512x512 throughout (no stitching needed)
• Filtering: Includes tiles with edges but no junction nodes (improved preprocessing)

The expected directory structures after preprocessing are shown below:

WildRoad Structure	Global-Scale Structure	AllTrails Structure
wildroad/ ├── preprocess_data/ ├── wild_road/ # Raw Data │ ├── train_patches/ │ ├── val_patches/ │ └── test_patches/ ├── wild_road_GLG/ # Processed Graphs │ ├── train_patches/ │ ├── val_patches/ │ └── test_patches/ └── wild_road_mask/ # Processed Masks ├── train_patches/ ├── val_patches/ └── test_patches/	globalscale/ ├── preprocess_data/ ├── Globalscale/ # Raw Data │ ├── train/ │ ├── val/ │ ├── in-domain-test/ │ └── out_of_domain/ ├── Globalscale_GLG/ # Processed Graphs │ ├── train_GLG/ │ └── out_of_domain_GLG/ └── Globalscale_mask/ # Processed Masks ├── train/ └── out_of_domain/	at_data/ # Raw GPS Data ├── train/ │ └── {area_name}/ │ ├── heatmap/ │ └── graph/ ├── val/ └── test/ wildroad/ └── at_data_processed/ # Processed ├── wild_road/ │ ├── train_patches/ │ ├── val_patches/ │ └── test_patches/ └── wild_road_mask/ ├── train_patches/ ├── val_patches/ └── test_patches/

Note for City-Scale and SpaceNet: The main branch is dedicated to WildRoad and Global-Scale experiments. To reproduce results on City-Scale or SpaceNet (following the sam_road data preparation), please switch to the legacy branch:

git checkout cityspace

🚀 Usage

1. Training

Train the model with the specified configuration.

WildRoad (satellite imagery):

python train.py --config=config/toponet_vitb_1024_wild_road.yaml
# Example with resume
python train.py --config=config/toponet_vitb_1024_wild_road.yaml --resume=<your_ckpt_path>

AllTrails GPS Heatmap Data:

python train.py --config=config/toponet_vitb_512_at_data.yaml
# Training optimized for 8GB GPU with 512x512 patches and batch_size=2

2. Compute Thresholds

Compute the mask and topo connectivity threshold on validation data.

WildRoad:

bash compute_threshold/test.sh \
    --config config/toponet_vitb_1024_wild_road.yaml \
    --checkpoint <your_ckpt_path>

AllTrails:

bash compute_threshold/test.sh \
    --config config/toponet_vitb_512_at_data.yaml \
    --checkpoint <your_ckpt_path>

3. Inference

Update the thresholds in the config file, then run inference.

WildRoad Thresholds:

• ITSC_THRESHOLD: 0.133
• ROAD_THRESHOLD: 0.839
• TOPO_THRESHOLD: 0.373

AllTrails Thresholds (10px edge width, optimal):

• ITSC_THRESHOLD: 0.761 (Keypoint F1: 32.2%)
• ROAD_THRESHOLD: 0.741 (Road F1: 80.8% ⭐)
• TOPO_THRESHOLD: 0.406

# WildRoad
python inferencer.py \
    --config=config/toponet_vitb_1024_wild_road.yaml \
    --checkpoint=<your_ckpt_path>

# AllTrails
python inferencer.py \
    --config=config/toponet_vitb_512_at_data.yaml \
    --checkpoint=<your_ckpt_path> \
    --output_dir=./at_inference_results

Note on Edge Width for GPS Heatmaps: We tested different ground truth edge widths (2px, 10px) and found that 10px edges achieve the best F1 score (80.8%) for GPS heatmap data. This accounts for GPS positioning tolerance and provides a stronger learning signal.

4. Evaluation

Evaluate the model using APLS and TOPO metrics.

# Usage: bash <script> <gt_dir> <pred_dir> <output_dir> <params...>
bash wildroad_metrics/apls_topo_parallel.sh wildroad/wild_road/test pred_dir wildroad_metrics/result/ 32 32

🗺️ Working with GPS Heatmap Data

Data Characteristics

GPS heatmap data (e.g., from AllTrails, Strava) differs significantly from satellite imagery:

Aspect	Satellite Imagery	GPS Heatmaps
Input Type	RGB images (roads visible)	Grayscale intensity (activity density)
Clarity	Clear visual features	Fuzzy, activity-based traces
Junctions	Clearly visible	Often unclear (overlapping traces)
Edge Width	Thin, precise	Variable width based on activity
Challenges	Occlusion, lighting	GPS noise, sparse coverage

Best Practices for GPS Heatmap Training

Based on our experiments with AllTrails data:

1. Edge Width: Use 10px edge masks for optimal results (F1: 80.8%)

   • Provides tolerance for GPS positioning errors
   • Better learning signal than thin edges (2px: 67.9% F1)
   • Higher recall (88.4%) captures more trail segments

2. Tile Processing: Use 512x512 tiles throughout

   • No stitching required (simpler pipeline)
   • Better GPU memory efficiency
   • Works well with SAM encoder position embeddings

3. Filtering Strategy: Include tiles with edges but no nodes

   • Many trail segments have no junctions
   • Improves topology learning (+21.6% F1)
   • Modified preprocessing handles this automatically

4. Performance Expectations:

   • Road F1: 70-80% (excellent)
   • Keypoint F1: 30-35% (GPS heatmaps don't show clear junctions)
   • Topology F1: 85-90% (benefits from edge-only tiles)

Configuration Files

• config/toponet_vitb_512_at_data.yaml: Optimized for AllTrails GPS data
  • PATCH_SIZE: 512
  • BATCH_SIZE: 2 (for 8GB GPU)
  • 10px edge width in ground truth
  • Thresholds computed from validation data

🎁 Model Zoo

🎉 Great News! We have released the pre-trained checkpoints for all major datasets! You can now directly reproduce our results without training from scratch.

Dataset	Download Link
WildRoad	Google Drive
Global-Scale	Google Drive
SpaceNet	Google Drive

Download the weights and place them in your checkpoint directory to get started!

📝 To-Do List

• Release automated extraction code (Training & Inference).
• Organize and clean up dataset preparation scripts.
• Release WildRoad Dataset.
• Release pre-trained model checkpoints.
• Release Interactive Annotation Tool and GUI.
• Add support for GPS heatmap data (AllTrails).
• Optimize preprocessing for edge-only tiles.
• Test different edge widths for GPS data (2px vs 10px).

📍 Citation

If you find this work useful for your research, please cite our paper:

@article{magroad2025,
  title={Beyond Endpoints: Path-Centric Reasoning for Vectorized Off-Road Network Extraction},
  author={Guan, Wenfei and Mei, Jilin and Shen, Tong and Wu, Xumin and Wang, Shuo and Min, Chen and Hu, Yu},
  journal={arXiv preprint arXiv:2512.10416},
  year={2025}
}

🤝 Acknowledgements

We sincerely thank the authors of the following open-source projects for their contributions, which served as important foundations for our work:

• Sam_Road
• Sam_Road++
• Sat2Graph
• Segment Anything Model