Skip to content

Commit fc35627

Browse files
AtsushiSakaiAtsushiSakai
authored
update getting started (AtsushiSakai#1131)
1 parent 53f1ba3 commit fc35627

File tree

4 files changed

+140
-116
lines changed

4 files changed

+140
-116
lines changed

‎docs/getting_started_main.rst‎

Lines changed: 6 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -3,120 +3,10 @@
33
Getting Started
44
===============
55

6-
.. _`What is PythonRobotics?`:
7-
8-
What is PythonRobotics?
9-
------------------------
10-
11-
This is an Open Source Software (OSS) project: PythonRobotics, which is a Python code collection of robotics algorithms.
12-
These codes are developed under `MIT license`_ and on `GitHub`_.
13-
14-
This project has three main philosophies below:
15-
16-
1. Easy to understand each algorithm's basic idea.
17-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18-
19-
The goal is for beginners in robotics to understand the basic ideas behind each algorithm.
20-
If the code is not easy to read, it would be difficult to achieve our goal of
21-
allowing beginners to understand the algorithms.
22-
23-
Python[12] programming language is adopted in this project.
24-
Python has great libraries for matrix operation, mathematical and scientific operation,
25-
and visualization, which makes code more readable because such operations
26-
don’t need to be re-implemented.
27-
Having the core Python packages allows the user to focus on the algorithms,
28-
rather than the implementations.
29-
30-
It includes intuitive animations to understand the behavior of the simulation.
31-
32-
about documenttion
33-
34-
2. Widely used and practical algorithms are selected.
35-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36-
37-
The second philosophy is that implemented algorithms have to be practical
38-
and widely used in both academia and industry.
39-
We believe learning these algorithms will be useful in many applications.
40-
For example, Kalman filters and particle filter for localization,
41-
grid mapping for mapping,
42-
dynamic programming based approaches and sampling based approaches for path planning,
43-
and optimal control based approach for path tracking.
44-
These algorithms are implemented in this project.
45-
46-
3. Minimum dependency.
47-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48-
49-
Each sample code is written in Python3 and only depends on some standard
50-
modules for readability and ease of use.
51-
52-
53-
.. _GitHub: https://github.com/AtsushiSakai/PythonRobotics
54-
.. _`MIT license`: https://github.com/AtsushiSakai/PythonRobotics/blob/master/LICENSE
55-
56-
57-
See this paper for more details:
58-
59-
- PythonRobotics: a Python code collection of robotics algorithms: https://arxiv.org/abs/1808.10703
60-
61-
.. _`Requirements`:
62-
63-
Requirements
64-
-------------
65-
66-
- `Python 3.12.x`_
67-
- `NumPy`_
68-
- `SciPy`_
69-
- `Matplotlib`_
70-
- `cvxpy`_
71-
72-
For development:
73-
74-
- `pytest`_ (for unit tests)
75-
- `pytest-xdist`_ (for parallel unit tests)
76-
- `mypy`_ (for type check)
77-
- `sphinx`_ (for document generation)
78-
- `ruff`_ (for code style check)
79-
80-
.. _`Python 3.12.x`: https://www.python.org/
81-
.. _`NumPy`: https://numpy.org/
82-
.. _`SciPy`: https://scipy.org/
83-
.. _`Matplotlib`: https://matplotlib.org/
84-
.. _`cvxpy`: https://www.cvxpy.org/
85-
.. _`pytest`: https://docs.pytest.org/en/latest/
86-
.. _`pytest-xdist`: https://github.com/pytest-dev/pytest-xdist
87-
.. _`mypy`: https://mypy-lang.org/
88-
.. _`sphinx`: https://www.sphinx-doc.org/en/master/index.html
89-
.. _`ruff`: https://github.com/astral-sh/ruff
90-
91-
92-
How to use
93-
----------
94-
95-
1. Clone this repo and go into dir.
96-
97-
.. code-block::
98-
99-
>$ git clone https://github.com/AtsushiSakai/PythonRobotics.git
100-
101-
>$ cd PythonRobotics
102-
103-
104-
2. Install the required libraries.
105-
106-
using conda :
107-
108-
.. code-block::
109-
110-
>$ conda env create -f requirements/environment.yml
111-
112-
using pip :
113-
114-
.. code-block::
115-
116-
>$ pip install -r requirements/requirements.txt
117-
118-
119-
3. Execute python script in each directory.
120-
121-
4. Add star to this repo if you like it 😃.
6+
.. toctree::
7+
:maxdepth: 2
8+
:caption: Contents
1229

10+
what_is_python_robotics
11+
how_to_use
12+
how_to_read_textbook

‎docs/how_to_read_textbook_main.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
How To read this textbook
2+
--------------------------
3+
4+
TBD

‎docs/how_to_use_main.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
How to use
2+
----------
3+
4+
1. Clone this repo and go into dir.
5+
6+
.. code-block::
7+
8+
>$ git clone https://github.com/AtsushiSakai/PythonRobotics.git
9+
10+
>$ cd PythonRobotics
11+
12+
13+
2. Install the required libraries.
14+
15+
using conda :
16+
17+
.. code-block::
18+
19+
>$ conda env create -f requirements/environment.yml
20+
21+
using pip :
22+
23+
.. code-block::
24+
25+
>$ pip install -r requirements/requirements.txt
26+
27+
28+
3. Execute python script in each directory.
29+
30+
4. Add star to this repo if you like it 😃.

‎docs/what_is_python_robotics_main.rst‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
.. _`What is PythonRobotics?`:
2+
3+
What is PythonRobotics?
4+
------------------------
5+
6+
This is an Open Source Software (OSS) project: PythonRobotics, which is a Python code collection of robotics algorithms.
7+
These codes are developed under `MIT license`_ and on `GitHub`_.
8+
9+
This project has three main philosophies below:
10+
11+
1. Easy to understand each algorithm's basic idea.
12+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
13+
14+
The goal is for beginners in robotics to understand the basic ideas behind each algorithm.
15+
16+
`Python`_ programming language is adopted in this project to achieve the goal.
17+
Python is a high-level programming language that is easy to read and write.
18+
If the code is not easy to read, it would be difficult to achieve our goal of
19+
allowing beginners to understand the algorithms.
20+
Python has great libraries for matrix operation, mathematical and scientific operation,
21+
and visualization, which makes code more readable because such operations
22+
don’t need to be re-implemented.
23+
Having the core Python packages allows the user to focus on the algorithms,
24+
rather than the implementations.
25+
26+
PythonRobotics provides not only the code but also intuitive animations that
27+
visually demonstrate the process and behavior of each algorithm over time.
28+
This is an example of an animation gif file that shows the process of the
29+
path planning in a highway scenario for autonomous vehicle.
30+
31+
.. image:: https://github.com/AtsushiSakai/PythonRoboticsGifs/raw/master/PathPlanning/FrenetOptimalTrajectory/high_speed_and_velocity_keeping_frenet_path.gif
32+
33+
This animation is a gif file and is created using the `Matplotlib`_ library.
34+
All animaion gif files are stored in the `PythonRoboticsGifs`_ repository and
35+
all animation movies are uploaded to this `YouTube channel`_.
36+
37+
PythonRobotics also provides a textbook that explains the basic ideas of each algorithm.
38+
39+
.. _`Python`: https://www.python.org/
40+
.. _`PythonRoboticsGifs`: https://github.com/AtsushiSakai/PythonRoboticsGifs
41+
.. _`YouTube channel`: https://youtube.com/playlist?list=PL12URV8HFpCozuz0SDxke6b2ae5UZvIwa&si=AH2fNPPYufPtK20S
42+
43+
44+
2. Widely used and practical algorithms are selected.
45+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46+
47+
The second philosophy is that implemented algorithms have to be practical
48+
and widely used in both academia and industry.
49+
We believe learning these algorithms will be useful in many applications.
50+
For example, Kalman filters and particle filter for localization,
51+
grid mapping for mapping,
52+
dynamic programming based approaches and sampling based approaches for path planning,
53+
and optimal control based approach for path tracking.
54+
These algorithms are implemented in this project.
55+
56+
3. Minimum dependency.
57+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58+
59+
Each sample code is written in Python3 and only depends on some standard
60+
modules for readability and ease of use.
61+
62+
63+
.. _GitHub: https://github.com/AtsushiSakai/PythonRobotics
64+
.. _`MIT license`: https://github.com/AtsushiSakai/PythonRobotics/blob/master/LICENSE
65+
66+
67+
See this paper for more details:
68+
69+
- PythonRobotics: a Python code collection of robotics algorithms: https://arxiv.org/abs/1808.10703
70+
71+
.. _`Requirements`:
72+
73+
Requirements
74+
============
75+
76+
- `Python 3.12.x`_
77+
- `NumPy`_
78+
- `SciPy`_
79+
- `Matplotlib`_
80+
- `cvxpy`_
81+
82+
For development:
83+
84+
- `pytest`_ (for unit tests)
85+
- `pytest-xdist`_ (for parallel unit tests)
86+
- `mypy`_ (for type check)
87+
- `sphinx`_ (for document generation)
88+
- `ruff`_ (for code style check)
89+
90+
.. _`Python 3.12.x`: https://www.python.org/
91+
.. _`NumPy`: https://numpy.org/
92+
.. _`SciPy`: https://scipy.org/
93+
.. _`Matplotlib`: https://matplotlib.org/
94+
.. _`cvxpy`: https://www.cvxpy.org/
95+
.. _`pytest`: https://docs.pytest.org/en/latest/
96+
.. _`pytest-xdist`: https://github.com/pytest-dev/pytest-xdist
97+
.. _`mypy`: https://mypy-lang.org/
98+
.. _`sphinx`: https://www.sphinx-doc.org/en/master/index.html
99+
.. _`ruff`: https://github.com/astral-sh/ruff
100+

0 commit comments

Comments
 (0)