Skip to content

Commit 3b383b3

Browse files
soblinsoblin
committed
adding nomenclature and figures
Signed-off-by: Mamoru Sobue <mamoru.sobue@tier4.jp>
1 parent 3579819 commit 3b383b3

27 files changed

+553
-40
lines changed

‎common/autoware_trajectory/CMakeLists.txt

+2
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ if(BUILD_TESTING)
2727
add_definitions("-Wno-attributes")
2828
find_package(ament_lint_auto REQUIRED)
2929
find_package(autoware_pyplot REQUIRED)
30+
find_package(range-v3 REQUIRED)
3031
ament_lint_auto_find_test_dependencies()
3132
include_directories(${autoware_pyplot_INCLUDE_DIRS})
3233
foreach(example_file ${example_files})
@@ -37,6 +38,7 @@ if(BUILD_TESTING)
3738
target_link_libraries(${example_name}
3839
autoware_trajectory
3940
${autoware_pyplot_LIBRARIES}
41+
range-v3::range-v3
4042
)
4143
endforeach()
4244
endif()

‎common/autoware_trajectory/README.md

+35-16
Original file line numberDiff line numberDiff line change
@@ -2,35 +2,54 @@
22

33
This package provides classes to manage/manipulate Trajectory.
44

5-
## Nomenclature
6-
7-
TODO
8-
95
## Overview
106

117
### Interpolators
128

9+
The _Trajectory_ class provides mathematical continuous representation and object oriented interface for discrete array of following point types
10+
11+
- [x] `geometry_msgs::Point`
12+
- [x] `geometry_msgs::Pose`
13+
- [x] `autoware_planning_msgs::PathPoint`
14+
- [x] `autoware_planning_msgs::PathPointWithLaneId`
15+
- [x] `autoware_planning_msgs::TrajectoryPoint`
16+
- [ ] `lanelet::ConstPoint3d`
17+
18+
by interpolating the given _underlying_ points. Once built, arbitrary point on the curve is continuously parametrized by a single `s` coordinate.
19+
1320
![interpolators](./images/interpolators.drawio.svg)
1421
[View in Drawio]({{ drawio("/common/autoware_trajectory/images/interpolators.drawio.svg") }})
1522

1623
Given `bases` and `values`, the builder internally executes interpolation and return the result in the form of `expected<T, E>`. If successful, it contains the interpolator object.
1724

18-
```cpp title="./examples/example_readme.cpp:43:62"
25+
```cpp title="./examples/example_readme.cpp:48:67"
1926
--8<--
20-
common/autoware_trajectory/examples/example_readme.cpp:43:62
27+
common/autoware_trajectory/examples/example_readme.cpp:48:67
2128
--8<--
2229
```
2330

2431
Otherwise it contains the error object representing the failure reason. In the below snippet, cubic spline interpolation fails because the number of input points is 3, which is below the `minimum_required_points() = 4` of `CubicSpline`.
2532

26-
```cpp title="./examples/example_readme.cpp:104:114"
33+
```cpp title="./examples/example_readme.cpp:109:119"
2734
--8<--
28-
common/autoware_trajectory/examples/example_readme.cpp:104:114
35+
common/autoware_trajectory/examples/example_readme.cpp:109:119
2936
--8<--
3037
```
3138

3239
In such cases the result `expected` object contains `InterpolationFailure` type with an error message like **"base size 3 is less than minimum required 4"**.
3340

41+
## Nomenclature
42+
43+
This section introduces strict definition of several words used in this package to clarify the description of API and help the developers understand and grasp the geometric meaning of algorithms.
44+
45+
| Word | Meaning | Illustration |
46+
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47+
| `curve` | `curve` is an oriented bounded curve denoted as `(x(s), y(s), z(s))` with additional properties, parameterized by `s` (`s = 0` at the start). | ![curve](./images/nomenclature/curve.drawio.svg)<br>[View in Drawio]({{ drawio("/common/autoware_trajectory/images/nomenclature/curve.drawio.svg") }})<br>There are 5 `underlying` points<br>$\mathrm{P0} = (0, 0, 0)$<br>$\mathrm{P1} = (1/ \sqrt{2}, 1/ \sqrt{2}, 0)$<br>$\mathrm{P2} = (1/ \sqrt{2}, 1+1/ \sqrt{2}, 0)$<br>$\mathrm{P3} = (2/ \sqrt{2}, 1+2/ \sqrt{2}, 0)$<br>$\mathrm{P4} = (2/ \sqrt{2} + 1/ \sqrt{6}, 1+2/ \sqrt{2} + 1 / \sqrt{3}, 1 / \sqrt{2})$<br>and the `arc length` between each interval is $1, 2, 1, 1$ respectively, so $\mathrm{start} = 0$ and $\mathrm{end} = 5$. |
48+
| `underlying` | `underlying` points of a curve refers to the list of 3D points from which the curve was interpolated. | |
49+
| `arc length`[m] | `arc length` denotes the approximate **3D** length of of a curve and is computed based on the discrete `underlying` points. | |
50+
| `s`[m] | `s` denotes the **3D** `arc length` coordinate starting from the base point (mostly the start point) of the curve and a point is identified by `trajectory(s)`.<br>Due to this definition, the actual _curve length_ and `arc length` have subtle difference as illustrated. | ![approximation](./images/nomenclature/approximation.drawio.svg)<br>[View in Drawio]({{ drawio("/common/autoware_trajectory/images/nomenclature/approximation.drawio.svg") }})<br>The point for $s = 0.5$ is the purple dot, but the _curve length_ from $\mathrm{P0}$ to this point does not equal to $0.5$. |
51+
| `curvature` | `curvature` is computed **using only X-Y 2D coordinate**. This is based on the normal and natural assumption that _roads are flat_. Mathematically, it asserts that [Gaussian curvature](https://en.wikipedia.org/wiki/Gaussian_curvature) of road is uniformly 0.<br>The sign of curvature is positive if the center of turning circle is on the left side, otherwise negative. | ![curvature](./images/nomenclature/curvature.drawio.svg)<br>[View in Drawio]({{ drawio("/common/autoware_trajectory/images/nomenclature/curvature.drawio.svg") }}) |
52+
3453
## API
3554

3655
### Interpolators
@@ -45,9 +64,9 @@ In such cases the result `expected` object contains `InterpolationFailure` type
4564

4665
`AkimaSpline` requires at least **5** points to interpolate.
4766

48-
```cpp title="./examples/example_readme.cpp:132:146"
67+
```cpp title="./examples/example_readme.cpp:137:151"
4968
--8<--
50-
common/autoware_trajectory/examples/example_readme.cpp:132:146
69+
common/autoware_trajectory/examples/example_readme.cpp:137:151
5170
--8<--
5271
```
5372

@@ -56,9 +75,9 @@ common/autoware_trajectory/examples/example_readme.cpp:132:146
5675

5776
`CubicSpline` requires at least **4** points to interpolate.
5877

59-
```cpp title="./examples/example_readme.cpp:187:196"
78+
```cpp title="./examples/example_readme.cpp:192:201"
6079
--8<--
61-
common/autoware_trajectory/examples/example_readme.cpp:187:196
80+
common/autoware_trajectory/examples/example_readme.cpp:192:201
6281
--8<--
6382
```
6483

@@ -67,9 +86,9 @@ common/autoware_trajectory/examples/example_readme.cpp:187:196
6786

6887
`Linear` requires at least **2** points to interpolate.
6988

70-
```cpp title="./examples/example_readme.cpp:237:245"
89+
```cpp title="./examples/example_readme.cpp:242:250"
7190
--8<--
72-
common/autoware_trajectory/examples/example_readme.cpp:237:245
91+
common/autoware_trajectory/examples/example_readme.cpp:242:250
7392
--8<--
7493
```
7594

@@ -78,9 +97,9 @@ common/autoware_trajectory/examples/example_readme.cpp:237:245
7897

7998
`StairStep` requires at least **2** points to interpolate.
8099

81-
```cpp title="./examples/example_readme.cpp:286:295"
100+
```cpp title="./examples/example_readme.cpp:291:300"
82101
--8<--
83-
common/autoware_trajectory/examples/example_readme.cpp:286:295
102+
common/autoware_trajectory/examples/example_readme.cpp:291:300
84103
--8<--
85104
```
86105

0 commit comments

Comments
 (0)