Skip to content

Commit 392c448

Browse files
omigeftomigeft
committed
readme & mkdocs
1 parent 6ca5414 commit 392c448

3 files changed

Lines changed: 209 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 182 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,184 @@
1-
Examples:
21

3-
```bash
4-
pip install mike
5-
git checkout v1.0
6-
python generate_mkdocs.py
7-
mike deploy v1.0 --push
8-
git checkout v1.1
2+
# Introduction
3+
4+
`Motion planning` plans the state sequence of the robot without conflict between the start and goal.
5+
6+
`Motion planning` mainly includes `Path planning` and `Trajectory planning`.
7+
8+
* `Path Planning`: It's based on path constraints (such as obstacles), planning the optimal path sequence for the robot to travel without conflict between the start and goal.
9+
* `Trajectory planning`: It plans the motion state to approach the global path based on kinematics, dynamics constraints and path sequence.
10+
11+
This repository provides the implementations of common `Motion planning` algorithms. **Your stars and forks are welcome**. Maintaining this repository requires a huge amount of work. **Therefore, you are also welcome to contribute to this repository by opening issues, submitting pull requests or joining our development team**.
12+
13+
The theory analysis can be found at [motion-planning](https://blog.csdn.net/frigidwinter/category_11410243.html).
14+
15+
We also provide [ROS C++](https://github.com/ai-winter/ros_motion_planning) version and [Matlab](https://github.com/ai-winter/matlab_motion_planning) version.
16+
17+
# Quick Start
18+
19+
## Overview
20+
The file structure is shown below
21+
22+
```
23+
python_motion_planning
24+
├─assets
25+
├─docs
26+
├─examples
27+
└─python_motion_planning
28+
├─global_planner
29+
| ├─graph_search
30+
| ├─sample_search
31+
| └─evolutionary_search
32+
├─local_planner
33+
├─curve_generation
34+
└─utils
35+
├─agent
36+
├─environment
37+
├─helper
38+
├─planner
39+
└─plot
40+
```
41+
* The global planning algorithm implementation is in the folder `global_planner` with `graph_search`, `sample_search` and `evolutionary search`.
42+
* The local planning algorithm implementation is in the folder `local_planner`.
43+
* The curve generation algorithm implementation is in the folder `curve_generation`.
44+
45+
## Install
46+
*(Optional)* The code was tested in python=3.10. We recommend using `conda` to install the dependencies.
47+
48+
```shell
49+
conda create -n pmp python=3.10
50+
conda activate pmp
51+
```
52+
53+
To install the repository, please run the following command in shell.
54+
55+
```shell
56+
pip install python-motion-planning
57+
```
58+
59+
## Run
60+
Below are some simple examples.
61+
62+
1. Run planning and animation separately
63+
```python
64+
import python_motion_planning as pmp
65+
planner = pmp.AStar(start=(5, 5), goal=(45, 25), env=pmp.Grid(51, 31))
66+
cost, path, expand = planner.plan()
67+
planner.plot.animation(path, str(planner), cost, expand) # animation
68+
```
69+
70+
2. Run planning and animation in one step
71+
```python
72+
import python_motion_planning as pmp
73+
planner = pmp.AStar(start=(5, 5), goal=(45, 25), env=pmp.Grid(51, 31))
74+
planner.run() # run both planning and animation
75+
```
76+
77+
3. Create planner in factory mode
78+
```python
79+
import python_motion_planning as pmp
80+
search_factory = pmp.SearchFactory()
81+
planner = search_factory("a_star", start=(5, 5), goal=(45, 25), env=pmp.Grid(51, 31))
82+
planner.run() # run both planning and animation
83+
```
84+
85+
More examples can be found in the folder `examples` in the repository.
86+
87+
## Documentation
88+
89+
For more details, you can refer to [online documentation](https://ai-winter.github.io/python_motion_planning/).
90+
91+
The documentation is auto-generated using mkdocs. To do this, enter the root directory and run
92+
93+
```shell
994
python generate_mkdocs.py
10-
mike deploy v1.1 latest --push
11-
```
95+
mkdocs serve
96+
```
97+
98+
Then open the browser and go to [http://127.0.0.1:8000](http://127.0.0.1:8000). That is the generated documentation.
99+
100+
# Version
101+
## Global Planner
102+
103+
Planner | Version | Animation
104+
------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------
105+
**GBFS** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/gbfs.py) | ![gbfs_python.png](assets/gbfs_python.png)
106+
**Dijkstra** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/dijkstra.py) | ![dijkstra_python.png](assets/dijkstra_python.png)
107+
**A*** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/a_star.py) | ![a_star_python.png](assets/a_star_python.png)
108+
**JPS** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/jps.py) | ![jps_python.png](assets/jps_python.png)
109+
**D*** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/d_star.py) | ![d_star_python.png](assets/d_star_python.png)
110+
**LPA*** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/lpa_star.py) | ![lpa_star_python.png](assets/lpa_star_python.png)
111+
**D\* Lite** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/d_star_lite.py) | ![d_star_lite_python.png](assets/d_star_lite_python.png)
112+
**Theta\*** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/theta_star.py) | ![theta_star_python.png](assets/theta_star_python.png)
113+
**Lazy Theta\*** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/lazy_theta_star.py) | ![lazy_theta_star_python.png](assets/lazy_theta_star_python.png)
114+
**S-Theta\*** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/s_theta_star.py) | ![s_theta_star_python.png](assets/s_theta_star_python.png)
115+
**Anya** | [![Status](https://img.shields.io/badge/develop-v1.0-red)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/anya.py) | ![Status](https://img.shields.io/badge/gif-none-yellow)
116+
**Voronoi** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/graph_search/voronoi.py) | ![voronoi_python.png](assets/voronoi_python.png)
117+
**RRT** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/sample_search/rrt.py) | ![rrt_python.png](assets/rrt_python.png)
118+
**RRT*** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/sample_search/rrt_star.py) | ![rrt_star_python.png](assets/rrt_star_python.png)
119+
**Informed RRT** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/sample_search/informed_rrt.py) | ![informed_rrt_python.png](assets/informed_rrt_python.png)
120+
**RRT-Connect** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/sample_search/rrt_connect.py) | ![rrt_connect_python.png](assets/rrt_connect_python.png)
121+
| **ACO** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/evolutionary_search/aco.py) | ![aco_python.png](assets/aco_python.png)
122+
| **GA** | ![Status](https://img.shields.io/badge/develop-v1.0-red) | ![Status](https://img.shields.io/badge/gif-none-yellow)
123+
| **PSO** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/global_planner/evolutionary_search/pso.py) | ![pso_python.png](assets/pso_python.svg) ![pso_python_cost.png](assets/pso_python_cost.svg)
124+
125+
126+
## Local Planner
127+
| Planner | Version | Animation
128+
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| --------------------------------------------------
129+
| **PID** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/local_planner/pid.py) | ![pid_python.svg](assets/pid_python.svg)
130+
| **APF** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/local_planner/apf.py) | ![apf_python.svg](assets/apf_python.svg)
131+
| **DWA** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/local_planner/dwa.py) | ![dwa_python.svg](assets/dwa_python.svg)
132+
| **RPP** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/local_planner/rpp.py) | ![rpp_python.svg](assets/rpp_python.svg)
133+
| **LQR** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/local_planner/lqr.py) | ![lqr_python.svg](assets/lqr_python.svg)
134+
| **TEB** | ![Status](https://img.shields.io/badge/develop-v1.0-red) | ![Status](https://img.shields.io/badge/gif-none-yellow)
135+
| **MPC** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/local_planner/mpc.py) | ![mpc_python.svg](assets/mpc_python.svg)
136+
| **MPPI** | ![Status](https://img.shields.io/badge/develop-v1.0-red) |![Status](https://img.shields.io/badge/gif-none-yellow)
137+
| **Lattice** | ![Status](https://img.shields.io/badge/develop-v1.0-red) |![Status](https://img.shields.io/badge/gif-none-yellow)
138+
| **DQN** | ![Status](https://img.shields.io/badge/develop-v1.0-red) |![Status](https://img.shields.io/badge/gif-none-yellow)
139+
| **DDPG** | ![Status](https://img.shields.io/badge/develop-v1.0-red) |![Status](https://img.shields.io/badge/gif-none-yellow)
140+
141+
## Curve Generation
142+
143+
| Planner | Version | Animation |
144+
| ------- | -------------------------------------------------------- | --------------------------------------------------------
145+
| **Polynomia** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/curve_generation/polynomial_curve.py) | ![polynomial_curve_python.gif](assets/polynomial_curve_python.gif)
146+
| **Bezier** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/curve_generation/bezier_curve.py) | ![bezier_curve_python.png](assets/bezier_curve_python.png)
147+
| **Cubic Spline** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/curve_generation/cubic_spline.py) | ![cubic_spline_python.png](assets/cubic_spline_python.png)
148+
| **BSpline** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/curve_generation/bspline_curve.py) | ![bspline_curve_python.png](assets/bspline_curve_python.png)
149+
| **Dubins** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/curve_generation/dubins_curve.py) | ![dubins_curve_python.png](assets/dubins_curve_python.png)
150+
| **Reeds-Shepp** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/curve_generation/reeds_shepp.py) | ![reeds_shepp_python.png](assets/reeds_shepp_python.gif)
151+
| **Fem-Pos Smoother** | [![Status](https://img.shields.io/badge/done-v1.0-brightgreen)](https://github.com/ai-winter/python_motion_planning/blob/master/curve_generation/fem_pos_smooth.py) | ![fem_pos_smoother_python.png](assets/fem_pos_smoother_python.png)
152+
153+
154+
155+
156+
# Papers
157+
## Global Planning
158+
* [A*: ](https://ieeexplore.ieee.org/document/4082128) A Formal Basis for the heuristic Determination of Minimum Cost Paths
159+
* [JPS:](https://ojs.aaai.org/index.php/AAAI/article/view/7994) Online Graph Pruning for Pathfinding On Grid Maps
160+
* [Lifelong Planning A*: ](https://www.cs.cmu.edu/~maxim/files/aij04.pdf) Lifelong Planning A*
161+
* [D*: ](http://web.mit.edu/16.412j/www/html/papers/original_dstar_icra94.pdf) Optimal and Efficient Path Planning for Partially-Known Environments
162+
* [D* Lite: ](http://idm-lab.org/bib/abstracts/papers/aaai02b.pdf) D* Lite
163+
* [Theta*: ](https://www.jair.org/index.php/jair/article/view/10676) Theta*: Any-Angle Path Planning on Grids
164+
* [Lazy Theta*: ](https://ojs.aaai.org/index.php/AAAI/article/view/7566) Lazy Theta*: Any-Angle Path Planning and Path Length Analysis in 3D
165+
* [S-Theta*: ](https://link.springer.com/chapter/10.1007/978-1-4471-4739-8_8) S-Theta*: low steering path-planning algorithm
166+
* [Anya: ](http://www.grastien.net/ban/articles/hgoa-jair16.pdf) Optimal Any-Angle Pathfinding In Practice
167+
* [RRT: ](http://msl.cs.uiuc.edu/~lavalle/papers/Lav98c.pdf) Rapidly-Exploring Random Trees: A New Tool for Path Planning
168+
* [RRT-Connect: ](http://www-cgi.cs.cmu.edu/afs/cs/academic/class/15494-s12/readings/kuffner_icra2000.pdf) RRT-Connect: An Efficient Approach to Single-Query Path Planning
169+
* [RRT*: ](https://journals.sagepub.com/doi/abs/10.1177/0278364911406761) Sampling-based algorithms for optimal motion planning
170+
* [Informed RRT*: ](https://arxiv.org/abs/1404.2334) Optimal Sampling-based Path Planning Focused via Direct Sampling of an Admissible Ellipsoidal heuristic
171+
* [ACO: ](http://www.cs.yale.edu/homes/lans/readings/routing/dorigo-ants-1999.pdf) Ant Colony Optimization: A New Meta-Heuristic
172+
173+
## Local Planning
174+
175+
* [DWA: ](https://www.ri.cmu.edu/pub_files/pub1/fox_dieter_1997_1/fox_dieter_1997_1.pdf) The Dynamic Window Approach to Collision Avoidance
176+
* [APF: ](https://ieeexplore.ieee.org/document/1087247) Real-time obstacle avoidance for manipulators and mobile robots
177+
* [RPP: ](https://arxiv.org/pdf/2305.20026.pdf) Regulated Pure Pursuit for Robot Path Tracking
178+
* [DDPG: ](https://arxiv.org/abs/1509.02971) Continuous control with deep reinforcement learning
179+
180+
## Curve Generation
181+
* [Dubins: ]() On curves of minimal length with a constraint on average curvature, and with prescribed initial and terminal positions and tangents
182+
183+
# Acknowledgment
184+
* Our visualization and animation framework of Python Version refers to [https://github.com/zhm-real/PathPlanning](https://github.com/zhm-real/PathPlanning). Thanks sincerely.

‎generate_mkdocs.py‎

Lines changed: 25 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
import os
88
import ast
99
import yaml
10+
import shutil
1011

1112

1213
def extract_classes(file_path: str):
@@ -28,7 +29,7 @@ def extract_classes(file_path: str):
2829
return class_names
2930

3031

31-
def generate_api_docs(root_folder: str, output_folder: str, index_file: str, mkdocs_file: str):
32+
def generate_api_docs(root_folder: str, output_folder: str, index_file: str, mkdocs_file: str, ex_home_file: str, ex_assets_folder: str):
3233
"""
3334
Automatically generate Markdown files for API documentation, update the homepage, and modify mkdocs.yml.
3435
@@ -73,21 +74,28 @@ def generate_api_docs(root_folder: str, output_folder: str, index_file: str, mkd
7374
class_name: os.path.relpath(os.path.join(output_dir, f"{class_name}.md"), output_folder)
7475
} for class_name in class_names])
7576

77+
if os.path.exists(ex_assets_folder):
78+
shutil.copytree(ex_assets_folder, os.path.join(output_folder, ex_assets_folder), dirs_exist_ok=True)
79+
80+
with open(ex_home_file, 'r', encoding='utf-8') as f:
81+
ex_home_content = f.read()
82+
7683
# Generate the content for the homepage
7784
with open(index_file, 'w', encoding='utf-8') as f:
78-
f.write("# Python Motion Planning Documentation\n\n")
79-
def write_nav(current_nav, level=1):
80-
for category, subcategories in sorted(current_nav.items()):
81-
f.write(f"{'#' * level} {category.capitalize()}\n\n")
82-
if isinstance(subcategories, dict):
83-
write_nav(subcategories, level + 1)
84-
else:
85-
for item in sorted(subcategories, key=lambda x: list(x.keys())[0]):
86-
class_name = list(item.keys())[0]
87-
doc_path = item[class_name].replace('\\', '/')
88-
f.write(f"- [{class_name}]({doc_path})\n")
89-
f.write("\n")
90-
write_nav(nav_structure)
85+
f.write(ex_home_content)
86+
# f.write("\n\n# Documentation Contents\n\n")
87+
# def write_nav(current_nav, level=2):
88+
# for category, subcategories in sorted(current_nav.items()):
89+
# f.write(f"{'#' * level} {category.capitalize()}\n\n")
90+
# if isinstance(subcategories, dict):
91+
# write_nav(subcategories, level + 1)
92+
# else:
93+
# for item in sorted(subcategories, key=lambda x: list(x.keys())[0]):
94+
# class_name = list(item.keys())[0]
95+
# doc_path = item[class_name].replace('\\', '/')
96+
# f.write(f"- [{class_name}]({doc_path})\n")
97+
# f.write("\n")
98+
# write_nav(nav_structure)
9199

92100
# Build the nav section of mkdocs.yml
93101
nav = [{"Home": "index.md"}]
@@ -118,5 +126,7 @@ def build_nav(current_nav) -> list:
118126
root_folder='src/python_motion_planning', # Code directory
119127
output_folder='docs/', # Directory for the generated documentation
120128
index_file='docs/index.md', # Path to the homepage file
121-
mkdocs_file='mkdocs.yml' # Path to the mkdocs.yml file
129+
mkdocs_file='mkdocs.yml', # Path to the mkdocs.yml file
130+
ex_home_file='README.md', # Extern homepage file
131+
ex_assets_folder='assets/' # Extern assets folder
122132
)

‎mkdocs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -223,12 +223,12 @@ plugins:
223223
show_symbol_type: true
224224
show_symbol_type_toc: true
225225
show_symbol_type_heading: true
226-
show_source: false
226+
show_source: true
227227
show_submodules: true
228228
selection:
229229
docstring_style: google
230230
extra:
231231
version:
232232
provider: mike
233233
default: latest
234-
alias: true
234+
alias: true

0 commit comments

Comments
 (0)