# MaGRoad-Prompt
**Repository Path**: labiao/MaGRoad-Prompt
## Basic Information
- **Project Name**: MaGRoad-Prompt
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-25
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
MaGRoad-Prompt
The First Interactive Road Network Annotation Tool
[](https://opensource.org/licenses/MIT)
[](https://pytorch.org/)
[](https://reactjs.org/)
[](https://fastapi.tiangolo.com/)
[**[ArXiv Paper]**](https://arxiv.org/abs/2512.10416v2) | [**[Automated Extraction]**](https://github.com/xiaofei-guan/MaGRoad) | [**[WildRoad Dataset]**](#)
This repository contains the official implementation of the **Interactive Algorithm** and **Annotation Tool** from the paper: **Beyond Endpoints: Path-Centric Reasoning for Vectorized Off-Road Network Extraction**.
## 📖 Introduction
**MaGRoad-Prompt** is the **first interactive road network extraction algorithm and tool**, designed to bridge the gap between automated extraction and human expertise. It serves as an Interactive Road Network Annotation Tool based on MaGRoad, providing a user-friendly application for generating precise road masks and graph structures via interactive prompting.
Figure 1: The architecture of the interactive algorithm based on MaGRoad. If you are interested in MaGRoad, please refer to the MaGRoad code.
## 💻 Interactive Annotation Tool
Our web-based application transforms the annotation workflow. Below is the main interface of the tool:
### Efficient Workflow vs. Manual Annotation
Compared to traditional manual plotting (e.g., QGIS), MaGRoad-Prompt significantly reduces effort by intelligently inferring path connectivity from sparse user clicks.
| **Manual Annotation (QGIS)** | **Interactive Annotation (Ours)** |
|:----------------------------:|:---------------------------------:|
| 
| 
|
### Diverse Scenarios
**Satellite Imagery**: The model handles complex large-scale road networks effectively.
**UAV Generalization**: Although trained only on satellite imagery, the model demonstrates strong generalization capabilities on UAV images.
---
## 🚀 Usage
Follow these steps to set up and run the annotation tool.
### 1. Environment Setup
```bash
conda create -n magroad-prompt python=3.8
conda activate magroad-prompt
```
**Backend (Algorithm)**
```bash
cd app/backend
pip install -r requirements.txt
```
**Frontend (Interface)**
Ensure Node.js is installed.
```bash
cd app/frontend
npm install # npm==10.8.2
```
### 2. Model Preparation
Download the provided open-source checkpoint from [**here**](https://drive.google.com/file/d/1eOEcR7LRm8jBw6utUCPccjj4z-fHRou6/view?usp=sharing) and place it under `./app/backend/app/models/weights`:
```bash
mkdir -p app/backend/app/models/weights
# Save the downloaded checkpoint here
```
### 3. Start the Application
**Start Backend**
```bash
cd app/backend
uvicorn main:app --reload --port 8000
```
**Start Frontend**
```bash
cd app/frontend
npm run dev
```
Open your browser (typically `http://localhost:5173`) to start using the tool.
---
## 🧠 Interactive Algorithm (Training)
If you wish to train the interactive algorithm on your own data or the WildRoad dataset, follow the steps below.
### 1. Data Preparation
Generate masks for the WildRoad dataset:
```bash
python wildroad/generate_masks_for_wild_road.py --input_dir ./wildroad/wild_road --output_dir ./wildroad/wild_road_mask
```
### 2. Model Preparation
Download the **ViT-B** checkpoint from the [SAM repository](https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth) and place it under `ckpt`:
```bash
mkdir -p ckpt
# Save sam_vit_b_01ec64.pth here
```
### 3. Training
Train the model to understand path connectivity from sparse prompts.
```bash
python train.py --config=config/toponet_vitb_1024_wild_road.yaml
```
### 4. Testing & Configuration Update
Evaluate the model to find the optimal thresholds.
```bash
python test.py --config=config/toponet_vitb_1024_wild_road.yaml --checkpoint=
```
**Integrating Custom Models into the Tool:**
After training, update the backend configuration to use your new model:
1. Copy your checkpoint to `app/backend/app/models/weights/`.
2. Edit `app/backend/app/models/road_extraction_algorithm/config_road_extraction.yaml`.
3. Update `ROAD_EXTRACTION_MODEL_CKPT_PATH` with your checkpoint filename.
4. Update `ITSC_THRESHOLD`, `ROAD_THRESHOLD`, and `TOPO_THRESHOLD` with the values obtained from the test step.
## 📍 Citation
If you use MaGRoad-Prompt or the WildRoad dataset in your research, please cite:
```bibtex
@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, Cheng and Hu, Yu},
journal={arXiv preprint arXiv:2512.10416},
year={2025}
}
``` 