FlexPath: Adapting Learned Connectivity Guidance to Path Preferences

TL;DR

Train a neural network to predict where paths can go (Stage 1), then adapt it to decide which path you actually want (Stage 2), shortest, safest, semantic-aware, or waypoint-guided, all from the same pretrained model.

Optimal	Obstacle Avoidance	Semantic Avoidance	Waypoint

The model predicts a heuristic in a single-shot fashion, then a classical search algorithms (Focal Search) navigates the map. Dark green nodes were expanded, the last frame shows the final path. Our heuristic strongly pushes the search algorithm towards the target almost without unnecessary exploration, all while aligning with the trained preference.

---

This Repository Contains

• ✅ Training code for Stage I (pretraining) and Stage II (fine-tuning)
• ✅ Implementation of all PSOs
• ✅ Basic evaluation scripts

Note

This branch is kept lightweight for easier extendability. See the full branch for baseline implementations used in the paper.

---

1) Basic setup

Requirements

• Python 3.9 (see pyproject.toml)
• CUDA GPU recommended for training

Clone repo:

git clone https://github.com/FraunhoferIVI/FlexPath

Install dependencies

Compilation dependencies::

apt install g++

(for cstar dependency and torch.compile)

Python dependencies: Option 1 (uv):

uv sync

Option 2 (pip):

python -m venv .venv
source .venv/bin/activate
pip install .

Download Checkpoints:

curl -L -o experiments.zip https://owncloud.fraunhofer.de/index.php/s/txWP34AQoYTi8Sb/download
unzip experiments.zip

Download Datasets

mkdir data
cd data

# TMP (512/64/64k)
curl -L -o TMP_640k_rgb.zip https://owncloud.fraunhofer.de/index.php/s/Md4nGgqQCGrUii8/download
unzip TMP_640k_rgb.zip

# CSM 1.9k (test only)
curl -L -o csm_1900.zip https://owncloud.fraunhofer.de/index.php/s/OdaJnfZwU1NGu4Z/download
unzip csm_1900.zip

# Starcraft 6k (test only)
curl -L -o starcraft_6k.zip https://owncloud.fraunhofer.de/index.php/s/51Dc4CPEwtztXYd/download
unzip starcraft_6k.zip

256x256

If you are interested in 256x256 checkpoints, you can download them from here. We pretrained and finetuned a model on the shortest-path objective, the exact configuration can be found in the corresponding config file within the experiment directory.

# checkpoints
curl -L -o 256x256_experiments.zip https://owncloud.fraunhofer.de/s/64nI0v2AwIrc11i/download
unzip 256x256_experiments.zip
mv basemodel_pretrained_256x256_64k experiments/pretraining/basemodel_pretrained_256x256_64k
mv basemodel_mindist_256x256_64k experiments/runs/basemodel_mindist_256x256_64k

# data
curl -L -o TMP_64k256x256_rgb.zip https://owncloud.fraunhofer.de/s/fcDJv8sDjLcLadi/download
unzip TMP_64k256x256_rgb.zip
mv TMP_64k256x256_rgb data/TMP_64k256x256_rgb

The used dataset is a 256x256 variant of TMP with 64k samples (51.2k/6.4k/6.4k split).

Generate semantic dataset extensions

This is only required if you want to retrain or evaluate the waypoint/semantic obstacle avoidance objectives.

uv run python scripts/datagen/generate_semantic_obstacle_dataset.py
uv run python scripts/datagen/generate_waypoint_dataset.py

Repository layout (high level)

• scripts/pretraining/train_actor.py: actor pretraining entrypoint
• scripts/training/train_singleshot_pso.py: single-shot fine-tuning entrypoint
• configs/: Hydra configs for training, models, and datasets
• docs/: detailed guides for pretraining, finetuning, and evaluation
• src/: core code (datasets, models, PSO objectives, training loops)
• experiments/: default output location for runs

2) Pretraining and fine-tuning

Stage I (Pretraining)

Entrypoint: scripts/pretraining/train_actor.py

For a detailed guide, see docs/pretraining.md.

Run with defaults:

python scripts/pretraining/train_actor.py

Stage II (Finetuning)

Entrypoint: scripts/training/train_singleshot_pso.py

For a detailed guide, see docs/finetuning.md.

Run with defaults:

python scripts/training/train_singleshot_pso.py

3) Evaluation

See docs/evaluation.md for how to run the evaluation script and interpret its outputs.

Take a look at the notebooks folder for visualizations.

4) Extending the system

See docs/pretraining.md and docs/finetuning.md on how to add new backbones, PSOs or datasets.

Notes

• All scripts are Hydra entrypoints; any config value can be overridden at the CLI with key=value syntax.
• Always use the 'latest' checkpoint over the 'best'. This is because the scaling of some components increase over the course of the training, which causes total loss / reward to become worse.

Citation

@misc{kim2026flexpathadaptinglearnedconn,
      title={FlexPath: Adapting Learned Connectivity Guidance to Path Preferences}, 
      author={Taehyoung Kim and Tim Schoenbrod and David Eckel and Henri Meeß},
      year={2026},
      eprint={2606.10167},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2606.10167}, 
}