Skip to content

Commit dc5f45c

Browse files
omigeftomigeft
committed
improve documentations
1 parent 2d867d3 commit dc5f45c

9 files changed

Lines changed: 140 additions & 109 deletions

‎README.md‎

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -49,31 +49,34 @@ The code was tested in python=3.10. To install other dependencies, please run th
4949
pip install -r requirements.txt
5050
```
5151

52-
## Run Example
53-
To start simulation, open the folder `example` and select the algorithm, for example
52+
## Run
53+
Below are some simple examples.
5454

55+
1. Run planning and animation separately
5556
```python
56-
if __name__ == '__main__':
57-
'''
58-
path searcher constructor
59-
'''
60-
search_factory = SearchFactory()
61-
62-
'''
63-
graph search
64-
'''
65-
# build environment
66-
start = (5, 5)
67-
goal = (45, 25)
68-
env = Grid(51, 31)
69-
70-
# creat planner
71-
planner = search_factory("a_star", start=start, goal=goal, env=env)
72-
# animation
73-
planner.run()
57+
import python_motion_planning as pmp
58+
planner = pmp.AStar(start=(5, 5), goal=(45, 25), env=pmp.Grid(51, 31))
59+
cost, path, expand = planner.plan()
60+
planner.plot.animation(path, str(planner), cost, expand) # animation
7461
```
7562

76-
You can also refer to the examples in the documentations generated using the following method.
63+
2. Run planning and animation in one step
64+
```python
65+
import python_motion_planning as pmp
66+
planner = pmp.AStar(start=(5, 5), goal=(45, 25), env=pmp.Grid(51, 31))
67+
planner.run() # run both planning and animation
68+
```
69+
70+
3. Create planner in factory mode
71+
```python
72+
import python_motion_planning as pmp
73+
search_factory = pmp.SearchFactory()
74+
planner = search_factory("a_star", start=(5, 5), goal=(45, 25), env=pmp.Grid(51, 31))
75+
planner.run() # run both planning and animation
76+
```
77+
78+
More examples can be found in the folder `examples`. You can also refer to the examples in the documentations generated using the following method.
79+
7780
## Documentation
7881

7982
This repository also support auto-generated documentation using mkdocs. Enter the root directory and run
@@ -83,7 +86,7 @@ python generate_mkdocs.py
8386
mkdocs serve
8487
```
8588

86-
Then open the browser and go to `http://127.0.0.1:8000`. That is the generated documentation.
89+
Then open the browser and go to [http://127.0.0.1:8000](http://127.0.0.1:8000). That is the generated documentation.
8790

8891
# Version
8992
## Global Planner

‎examples/common_examples.py‎

Lines changed: 70 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,72 @@
1+
"""
2+
@file: common_examples.py
3+
@breif: Examples of Python Motion Planning library
4+
@author: Wu Maojia
5+
@update: 2024.11.22
6+
"""
7+
import sys, os
8+
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
19
from python_motion_planning import *
210

3-
# -------------global planners-------------
4-
# plt = AStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
5-
# plt = DStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
6-
# plt = DStarLite(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
7-
# plt = Dijkstra(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
8-
# plt = GBFS(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
9-
# plt = JPS(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
10-
# plt = ThetaStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
11-
# plt = LazyThetaStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
12-
# plt = SThetaStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
13-
# plt = LPAStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
14-
# plt = VoronoiPlanner(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
15-
16-
# plt = RRT(start=(18, 8), goal=(37, 18), env=Map(51, 31))
17-
# plt = RRTConnect(start=(18, 8), goal=(37, 18), env=Map(51, 31))
18-
# plt = RRTStar(start=(18, 8), goal=(37, 18), env=Map(51, 31))
19-
# plt = InformedRRT(start=(18, 8), goal=(37, 18), env=Map(51, 31))
20-
21-
# plt = ACO(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
22-
# plt = PSO(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
23-
24-
# plt.run()
25-
26-
# -------------local planners-------------
27-
# plt = PID(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
28-
# plt = DWA(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
29-
# plt = APF(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
30-
# plt = LQR(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
31-
# plt = RPP(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
32-
# plt = MPC(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
33-
# plt.run()
34-
35-
36-
# Train the model, only for learning-based planners, such as DDPG
37-
# It costs a lot of time to train the model, please be patient.
38-
# If you want a faster training, try reducing num_episodes and batch_size,
39-
# or increasing update_steps and evaluate_episodes, or fine-tuning other hyperparameters
40-
# if you are familiar with them, usually in a cost of performance, however.
41-
# plt = DDPG(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31),
42-
# actor_save_path="models/actor_best.pth", critic_save_path="models/critic_best.pth")
43-
# plt.train(num_episodes=10000)
44-
45-
# load the trained model and run
46-
plt = DDPG(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31),
47-
actor_load_path="models/actor_best_example.pth", critic_load_path="models/critic_best_example.pth")
48-
plt.run()
49-
50-
# -------------curve generators-------------
51-
# points = [(0, 0, 0), (10, 10, -90), (20, 5, 60), (30, 10, 120),
52-
# (35, -5, 30), (25, -10, -120), (15, -15, 100), (0, -10, -90)]
53-
54-
# plt = Dubins(step=0.1, max_curv=0.25)
55-
# plt = Bezier(step=0.1, offset=3.0)
56-
# plt = Polynomial(step=2, max_acc=1.0, max_jerk=0.5)
57-
# plt = ReedsShepp(step=0.1, max_curv=0.25)
58-
# plt = CubicSpline(step=0.1)
59-
# plt = BSpline(step=0.01, k=3)
60-
61-
# plt.run(points)
11+
if __name__ == '__main__':
12+
# -------------global planners-------------
13+
plt = AStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
14+
# plt = DStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
15+
# plt = DStarLite(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
16+
# plt = Dijkstra(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
17+
# plt = GBFS(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
18+
# plt = JPS(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
19+
# plt = ThetaStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
20+
# plt = LazyThetaStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
21+
# plt = SThetaStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
22+
# plt = LPAStar(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
23+
# plt = VoronoiPlanner(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
24+
25+
# plt = RRT(start=(18, 8), goal=(37, 18), env=Map(51, 31))
26+
# plt = RRTConnect(start=(18, 8), goal=(37, 18), env=Map(51, 31))
27+
# plt = RRTStar(start=(18, 8), goal=(37, 18), env=Map(51, 31))
28+
# plt = InformedRRT(start=(18, 8), goal=(37, 18), env=Map(51, 31))
29+
30+
# plt = ACO(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
31+
# plt = PSO(start=(5, 5), goal=(45, 25), env=Grid(51, 31))
32+
33+
plt.run()
34+
35+
# -------------local planners-------------
36+
# plt = PID(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
37+
# plt = DWA(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
38+
# plt = APF(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
39+
# plt = LQR(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
40+
# plt = RPP(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
41+
# plt = MPC(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31))
42+
# plt.run()
43+
44+
45+
# Train the model, only for learning-based planners, such as DDPG
46+
# It costs a lot of time to train the model, please be patient.
47+
# If you want a faster training, try reducing num_episodes and batch_size,
48+
# or increasing update_steps and evaluate_episodes, or fine-tuning other hyperparameters
49+
# if you are familiar with them, usually in a cost of performance, however.
50+
51+
# plt = DDPG(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31),
52+
# actor_save_path="models/actor_best.pth", critic_save_path="models/critic_best.pth")
53+
# plt.train(num_episodes=10000)
54+
55+
# load the trained model and run
56+
57+
# plt = DDPG(start=(5, 5, 0), goal=(45, 25, 0), env=Grid(51, 31),
58+
# actor_load_path="models/actor_best_example.pth", critic_load_path="models/critic_best_example.pth")
59+
# plt.run()
60+
61+
# -------------curve generators-------------
62+
# points = [(0, 0, 0), (10, 10, -90), (20, 5, 60), (30, 10, 120),
63+
# (35, -5, 30), (25, -10, -120), (15, -15, 100), (0, -10, -90)]
64+
65+
# plt = Dubins(step=0.1, max_curv=0.25)
66+
# plt = Bezier(step=0.1, offset=3.0)
67+
# plt = Polynomial(step=2, max_acc=1.0, max_jerk=0.5)
68+
# plt = ReedsShepp(step=0.1, max_curv=0.25)
69+
# plt = CubicSpline(step=0.1)
70+
# plt = BSpline(step=0.01, k=3)
71+
72+
# plt.run(points)

examples/curve_example.py renamed to examples/curve_examples.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
"""
2-
@file: curve_example.py
2+
@file: curve_examples.py
33
@breif: curve generation application examples
4-
@author: Winter
5-
@update: 2023.7.25
4+
@author: Yang Haodong, Wu Maojia
5+
@update: 2024.11.22
66
"""
77
import sys, os
8-
sys.path.append(os.path.abspath(os.path.join(__file__, "../")))
8+
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
99
from python_motion_planning.utils import CurveFactory
1010

1111
if __name__ == '__main__':

examples/global_example.py renamed to examples/global_examples.py

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
"""
2-
@file: global_example.py
2+
@file: global_examples.py
33
@breif: global planner application examples
4-
@author: Winter
5-
@update: 2023.3.2
4+
@author: Yang Haodong, Wu Maojia
5+
@update: 2024.11.22
66
"""
7-
7+
import sys, os
8+
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
89
from python_motion_planning.utils import Grid, Map, SearchFactory
910

10-
1111
if __name__ == '__main__':
1212
'''
1313
path searcher constructor
@@ -23,7 +23,7 @@
2323
env = Grid(51, 31)
2424

2525
# creat planner
26-
# planner = search_factory("a_star", start=start, goal=goal, env=env)
26+
planner = search_factory("a_star", start=start, goal=goal, env=env)
2727
# planner = search_factory("dijkstra", start=start, goal=goal, env=env)
2828
# planner = search_factory("gbfs", start=start, goal=goal, env=env)
2929
# planner = search_factory("theta_star", start=start, goal=goal, env=env)
@@ -37,7 +37,7 @@
3737
# max_edge_len=10.0, inflation_r=1.0)
3838

3939
# animation
40-
# planner.run()
40+
planner.run()
4141

4242
# ========================================================
4343

@@ -64,5 +64,5 @@
6464
evolutionary search
6565
'''
6666
# planner = search_factory("aco", start=start, goal=goal, env=env)
67-
planner = search_factory("pso", start=start, goal=goal, env=env)
68-
planner.run()
67+
# planner = search_factory("pso", start=start, goal=goal, env=env)
68+
# planner.run()

examples/local_example.py renamed to examples/local_examples.py

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
"""
2-
@file: local_example.py
2+
@file: local_examples.py
33
@breif: local planner application examples
4-
@author: Winter
5-
@update: 2023.10.24
4+
@author: Yang Haodong, Wu Maojia
5+
@update: 2024.11.22
66
"""
7+
import sys, os
8+
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
79
from python_motion_planning.utils import Grid, ControlFactory
810

911
if __name__ == '__main__':

‎generate_mkdocs.py‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
@file: generate_mkdocs.py
33
@breif: Used to automatically generate MkDocs documentation for Python libraries.
44
@author: Wu Maojia
5-
@update: 2024.11.21
5+
@update: 2024.11.22
66
"""
77
import os
88
import ast
@@ -109,10 +109,11 @@ def build_nav(current_nav) -> list:
109109
yaml.dump(mkdocs_config, f, allow_unicode=True, sort_keys=False)
110110

111111

112-
# Example usage
113-
generate_api_docs(
114-
root_folder='python_motion_planning', # Code directory
115-
output_folder='docs/', # Directory for the generated documentation
116-
index_file='docs/index.md', # Path to the homepage file
117-
mkdocs_file='mkdocs.yml' # Path to the mkdocs.yml file
118-
)
112+
if __name__ == '__main__':
113+
# Example usage
114+
generate_api_docs(
115+
root_folder='python_motion_planning', # Code directory
116+
output_folder='docs/', # Directory for the generated documentation
117+
index_file='docs/index.md', # Path to the homepage file
118+
mkdocs_file='mkdocs.yml' # Path to the mkdocs.yml file
119+
)

‎mkdocs.yml‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -218,9 +218,18 @@ nav:
218218
- plot:
219219
- Plot: utils\plot\plot\Plot.md
220220
plugins:
221+
- search
222+
- autorefs
221223
- mkdocstrings:
224+
default_handler: python
222225
handlers:
223226
python:
224227
paths:
225-
- src
226-
- search
228+
- pykit_tools
229+
options:
230+
heading_level: 3
231+
show_root_heading: true
232+
show_symbol_type_heading: true
233+
show_source: false
234+
selection:
235+
docstring_style: google

‎pyproject.toml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ dependencies = [
1919
"torch",
2020
"torchvision",
2121
"tensorboard==2.12.0",
22-
"mkdocs"
22+
"mkdocs",
23+
"mkdocstrings",
24+
"mkdocs-material"
2325
]
2426
repository = {type = "git", url = "https://github.com/ai-winter/python_motion_planning.git"}
2527
classifiers = [

‎requirements.txt‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,7 @@ tqdm # >=4.66.4
77
torch # >=2.3.0
88
torchvision # >=0.18.0
99
tensorboard==2.12.0
10-
mkdocs # >=1.5.3
10+
mkdocs # >=1.5.3
11+
mkdocstrings # >=0.27.0
12+
mkdocstrings-python # >=1.12.2
13+
mkdocs-material # >=9.5.45

0 commit comments

Comments
 (0)