PolyFly: Polytopic Optimal Planning for Collision-Free Cable-Suspended Aerial Payload Transportation

▶️ Video

PolyFly is an optimal global planner for aerial transportation with a cable-suspended payload. Unlike conservative geometric over-approximations, PolyFly models each physical component - quadrotor, cable, and payload - as distinct polytopes, and incorporates orientation-aware geometry. Using duality, polytopic collision constraints are converted into smooth differentiable constraints, enabling efficient optimization and aggressive, collision-free trajectories in cluttered environments.

For the full method, results, and hardware validation, see the paper: PolyFly: Polytopic Optimal Planning for Collision-Free Cable-Suspended Aerial Payload Transportation.

---

Highlights

• Non-conservative, orientation-aware polytopic modeling of quadrotor, cable, and payload
• Smooth differentiable collision constraints via duality for efficient optimization
• Global trajectories for maze-like, tightly constrained environments
• Real-world validation with low tracking error and agile maneuvers

---

Repository Structure

• src/poly_fly/optimal_planner/: Core global planner and collision constraints
• src/poly_fly/forest_planner/: Synthetic environment generation, viewers, and video utilities
• data/params/: Parameter files for environments and studies
• data/csvs/: Generated environments produced by the code
• scripts/: Convenience scripts for running planner and generating environments

---

Important Notes

• By default, the code uses the MA57 solver. This is significantly faster than the default solvers. Refer to README_INSTALL_HSL on how to set this up.

Quick Start (Docker)

Add the following to your .bashrc export POLYFLY_DIR= <directory that points to polyfly's root>

Use Docker for the fastest setup and consistent environment:

1. Build the image

docker build -t poly-fly:latest .

2. Start the container

./scripts/docker_run_dev.sh

This mounts your workspace at /workspace inside the container so edits on your host are immediately reflected inside the container.

3. Create a .env at the project root with your OpenAI API key (optional if not using features that need it)

OPENAI_API_KEY="my-openai-api-key"

4. Inside the container, run commands

# Run the optimal planner (with plots)
./scripts/run_planner.sh

# Or run Python commands directly:
cd /workspace
python src/poly_fly/optimal_planner/planner.py --plot

5. Exit the container

exit

---

Forest Environments

Interested in generating trajectories through forest environments?

Run

./scripts/run_generate_forest.sh -n 1 --forest-type 0 --plot

to generate trajectories through a randomly generated forest, with different robot start and end positions

Parallel Computation To SpeedUp Data Generation

If you'd like to use PolyFly to generate a large number of trajectories (eg. for imitation learning), we offer support to run multiple solver instances in parallel. Pass in the --mp flag to use multiprocessing, and specify the number of environments via the --n arg.

For example

./scripts/run_generate_forest.sh -n 5 --mp --forest-type 0

will run multiple solver instances (the number is determined based on the available CPU cores) for 5 randomly generated environments. This results in an effective speed up of about 5-10x. Results are saved in the associated csv directory.

Custom Obstacles

The obstacles are defined through yaml files located in the data/params directory. To create a new custom environment

1. Create a new directory, eg. myexp under data/params. This would be data/params/myexp
2. Create a base.yaml file, that defines the default parameters. Using experiments/base.yaml is a good starting point
3. Create a new environment yaml file, eg. myexp/env_1.yaml. See experiments/maze_1.yaml for an example. Update the obstacles field to define the obstacle positions. payload_pos_init can be set to [] if use_global_planner=True
4. Run the solver script ./scripts/run_planner.sh --yaml myexp/env_1.yaml

Generate an obstacle course using ChatGPT

Want to use an LLM to generate obstacle positions?

./scripts/run_interactive_forest.sh

When prompted, enter the description of the environment you'd like to create. For example, you can say Use 10 small obstacles to create a letter X. Refer to compose_gpt_prompt in interactive_generate_forest.py for insight on the prompt engineering.

Visualizing Results

To visualize the results in a given csv directory, eg. csvs/experiments, run python src/poly_fly/forest_planner/create_video.py --inspect --no-video --combined --csv_folder experiments. This will open up a GUI to visualize all the csvs in the given directory.

Docker Notes

• The container bind-mounts your project at /workspace for live-edit development.

Datasets and Environments

• After planning is complete, CSVs are generated by the code and saved to data/csvs/.
• Parameter files to configure obstacles, robot, and planner are in data/params/.
• To procedurally create forests, use ./scripts/run_generate_forest.sh or src/poly_fly/forest_planner/generate_forest.py.

---

Citation

If you use this repository or build on PolyFly, please cite:

@article{Sarvaiya2025PolyFly,
  title   = {PolyFly: Polytopic Optimal Planning for Collision-Free Cable-Suspended Aerial Payload Transportation},
  author  = {Mrunal Sarvaiya and Guanrui Li and Giuseppe Loianno},
  journal = {arXiv preprint arXiv:2510.15226},
  year    = {2025},
  url     = {https://arxiv.org/pdf/2510.15226}
}

---

Contributors and Maintainers

• Mrunal Sarvaiya (Maintainer) — [email protected]
• Rohit Kulkarni (Maintainer) — [email protected]