Skip to content

Commit 0cc97ca

Browse files
wep21Taichi Higashidetkimura4
authored
docs: update readme of ground segmentation (autowarefoundation#764) (autowarefoundation#139)
* docs: update readme of ground segmentation (autowarefoundation#764) Signed-off-by: wep21 <border_goldenmarket@yahoo.co.jp> * Apply suggestions from code review Co-authored-by: Taichi Higashide <taichi.higashide@tier4.jp> Co-authored-by: Tomoya Kimura <tomoya.kimura@tier4.jp>
1 parent f5f392d commit 0cc97ca

6 files changed

+186
-65
lines changed

‎perception/ground_segmentation/README.md

+27-65
Original file line numberDiff line numberDiff line change
@@ -2,88 +2,50 @@
22

33
## Purpose
44

5-
The `ground_segmentation` is a node that filters the ground points from the input pointcloud.
5+
The `ground_segmentation` is a node that remove the ground points from the input pointcloud.
66

77
## Inner-workings / Algorithms
88

9-
### Ransac Ground Filter
9+
Detail description of each ground segmentation algorithm is in the following links.
1010

11-
This algorithm is SAC-based ground segmentation.
12-
13-
See: <https://pcl.readthedocs.io/projects/tutorials/en/latest/planar_segmentation.html>
14-
15-
### Ray Ground Filter
16-
17-
This algorithm is deprecated in current architecture.
18-
19-
### Scan Ground Filter
20-
21-
This algorithm works by following steps,
22-
23-
1. Divide whole pointclouds into groups by horizontal angle and sort by xy-distance.
24-
2. Check the distance and vertical angle of the point one by one.
25-
3. Set a center of the ground contact point of the rear or front wheels as the initial point.
26-
4. Check vertical angle between the points. If the angle from the initial point is larger than "global_slope_max", the point is classified as "no ground".
27-
5. If the angle from the previous point is larger than "local_max_slope", the point is classified as "no ground".
28-
6. Otherwise the point is labeled as "ground point".
29-
7. If the distance from the last checked point is close, ignore any vertical angle and set current point attribute to the same as the last point.
11+
| Filter Name | Description | Detail |
12+
| -------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------ |
13+
| ray_ground_filter | A method of removing the ground based on the geometrical relationship between points lined up on radiation | [link](docs/ray-ground-filter.md) |
14+
| scan_ground_filter | Almost the same method as `ray_ground_filter`, but with slightly improved performance | [link](docs/scan-ground-filter.md) |
15+
| ransac_ground_filter | A method of removing the ground by approximating the ground to a plane | [link](docs/ransac-ground-filter.md) |
3016

3117
## Inputs / Outputs
3218

3319
### Input
3420

35-
| Name | Type | Description |
36-
| -------- | -------------------------- | --------------------------- |
37-
| `~input` | `sensor_msgs::PointCloud2` | outlier filtered pointcloud |
21+
| Name | Type | Description |
22+
| ----------------- | ------------------------------- | ----------------- |
23+
| `~/input/points` | `sensor_msgs::msg::PointCloud2` | reference points |
24+
| `~/input/indices` | `pcl_msgs::msg::Indices` | reference indices |
3825

3926
### Output
4027

41-
| Name | Type | Description |
42-
| --------- | -------------------------- | -------------------- |
43-
| `~output` | `sensor_msgs::PointCloud2` | no ground pointcloud |
28+
| Name | Type | Description |
29+
| ----------------- | ------------------------------- | --------------- |
30+
| `~/output/points` | `sensor_msgs::msg::PointCloud2` | filtered points |
4431

4532
## Parameters
4633

47-
### Ransac Ground Filter
48-
49-
#### Core Parameters
50-
51-
| Name | Type | Default Value | Description |
52-
| ----------------------- | ------ | ------------- | --------------------------------------------------------------- |
53-
| `base_frame` | string | "base_link" | base_link frame |
54-
| `unit_axis` | string | "z" | The axis which we need to search ground plane |
55-
| `max_iterations` | int | 1000 | The maximum number of iterations |
56-
| `outlier_threshold` | double | 0.01 | The distance threshold to the model [m] |
57-
| `plane_slope_threshold` | double | 10.0 | The slope threshold to prevent mis-fitting [deg] |
58-
| `voxel_size_x` | double | 0.04 | voxel size x [m] |
59-
| `voxel_size_y` | double | 0.04 | voxel size y [m] |
60-
| `voxel_size_z` | double | 0.04 | voxel size z [m] |
61-
| `height_threshold` | double | 0.01 | The height threshold from ground plane for no ground points [m] |
62-
| `debug` | bool | false | whether to output debug information |
63-
64-
### Scan Ground Filter
65-
66-
#### Core Parameters
67-
68-
| Name | Type | Default Value | Description |
69-
| --------------------------------- | ------ | ------------- | ----------------------------------------------------------------------------- |
70-
| `base_frame` | string | "base_link" | base_link frame |
71-
| `global_slope_max` | double | 8.0 | The global angle to classify as the ground or object [deg] |
72-
| `local_max_slope` | double | 6.0 | The local angle to classify as the ground or object [deg] |
73-
| `radial_divider_angle` | double | 1.0 | The angle which divide the whole pointcloud to sliced group [deg] |
74-
| `split_points_distance_tolerance` | double | 0.2 | The xy-distance threshold to to distinguishing far and near [m] |
75-
| `split_height_distance` | double | 0.2 | The height threshold to distinguishing far and near [m] |
76-
| `use_virtual_ground_point` | bool | true | whether to use the ground center of front wheels as the virtual ground point. |
77-
78-
## Assumptions / Known limits
34+
### Node Parameters
7935

80-
## (Optional) Error detection and handling
36+
| Name | Type | Default Value | Description |
37+
| ------------------ | ------ | ------------- | ------------------------------------- |
38+
| `input_frame` | string | " " | input frame id |
39+
| `output_frame` | string | " " | output frame id |
40+
| `max_queue_size` | int | 5 | max queue size of input/output topics |
41+
| `use_indices` | bool | false | flag to use pointcloud indices |
42+
| `latched_indices` | bool | false | flag to latch pointcloud indices |
43+
| `approximate_sync` | bool | false | flag to use approximate sync option |
8144

82-
## (Optional) Performance characterization
45+
## Assumptions / Known limits
8346

84-
## (Optional) References/External links
47+
`pointcloud_preprocessor::Filter` is implemented based on pcl_perception [1] because of [this issue](https://github.com/ros-perception/perception_pcl/issues/9).
8548

86-
## (Optional) Future extensions / Unimplemented parts
49+
## References/External links
8750

88-
- Horizontal check for classification is not implemented yet.
89-
- Output ground visibility for diagnostic is not implemented yet.
51+
[1] <https://github.com/ros-perception/perception_pcl/blob/ros2/pcl_ros/src/pcl_ros/filters/filter.cpp>

‎perception/ground_segmentation/docs/image/ground_filter-ray-xy.drawio.svg

+4
Loading

‎perception/ground_segmentation/docs/image/ground_filter-ray-xz.drawio.svg

+4
Loading

‎perception/ground_segmentation/docs/ransac-ground-filter.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# RANSAC Ground Filter
2+
3+
## Purpose
4+
5+
The purpose of this node is that remove the ground points from the input pointcloud.
6+
7+
## Inner-workings / Algorithms
8+
9+
Apply the input points to the plane, and set the points at a certain distance from the plane as points other than the ground. Normally, whn using this method, the input points is filtered so that it is almost flat before use. Since the drivable area is often flat, there are methods such as filtering by lane.
10+
11+
## Inputs / Outputs
12+
13+
This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).
14+
15+
## Parameters
16+
17+
### Node Parameters
18+
19+
This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).
20+
21+
#### Core Parameters
22+
23+
| Name | Type | Description |
24+
| ----------------------- | ------ | --------------------------------------------------------------- |
25+
| `base_frame` | string | base_link frame |
26+
| `unit_axis` | string | The axis which we need to search ground plane |
27+
| `max_iterations` | int | The maximum number of iterations |
28+
| `outlier_threshold` | double | The distance threshold to the model [m] |
29+
| `plane_slope_threshold` | double | The slope threshold to prevent mis-fitting [deg] |
30+
| `voxel_size_x` | double | voxel size x [m] |
31+
| `voxel_size_y` | double | voxel size y [m] |
32+
| `voxel_size_z` | double | voxel size z [m] |
33+
| `height_threshold` | double | The height threshold from ground plane for no ground points [m] |
34+
| `debug` | bool | whether to output debug information |
35+
36+
## Assumptions / Known limits
37+
38+
- This method can't handle slopes.
39+
- The input points is filtered so that it is almost flat.
40+
41+
## (Optional) Error detection and handling
42+
43+
## (Optional) Performance characterization
44+
45+
## References/External links
46+
47+
<https://pcl.readthedocs.io/projects/tutorials/en/latest/planar_segmentation.html>
48+
49+
## (Optional) Future extensions / Unimplemented parts

‎perception/ground_segmentation/docs/ray-ground-filter.md

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Ray Ground Filter
2+
3+
## Purpose
4+
5+
The purpose of this node is that remove the ground points from the input pointcloud.
6+
7+
## Inner-workings / Algorithms
8+
9+
The points is separated radially (Ray), and the ground is classified for each Ray sequentially from the point close to ego-vehicle based on the geometric information such as the distance and angle between the points.
10+
11+
![ray-xy](./image/ground_filter-ray-xy.drawio.svg)
12+
13+
## Inputs / Outputs
14+
15+
This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).
16+
17+
## Parameters
18+
19+
### Node Parameters
20+
21+
This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).
22+
23+
### Core Parameters
24+
25+
![ray-xz](./image/ground_filter-ray-xz.drawio.svg)
26+
27+
| Name | Type | Description |
28+
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
29+
| `base_frame` | string | The target frame of input points |
30+
| `general_max_slope` | double | The triangle created by `general_max_slope` is called the global cone. If the point is outside the global cone, it is judged to be a point that is no on the ground |
31+
| `initial_max_slope` | double | Generally, the point where the object first hits is far from ego-vehicle because of sensor blind spot, so resolution is different from that point and thereafter, so this parameter exists to set a separate `local_max_slope` |
32+
| `local_max_slope` | double | The triangle created by `local_max_slope` is called the local cone. This parameter for classification based on the continuity of points |
33+
| `min_height_threshold` | double | This parameter is used instead of `height_threshold` because it's difficult to determine continuity in the local cone when the points are too close to each other. |
34+
| `radial_divider_angle` | double | The angle of ray |
35+
| `concentric_divider_distance` | double | Only check points which radius is larger than `concentric_divider_distance` |
36+
| `reclass_distance_threshold` | double | To check if point is to far from previous one, if so classify again |
37+
| `min_x` | double | The parameter to set vehicle footprint manually |
38+
| `max_x` | double | The parameter to set vehicle footprint manually |
39+
| `min_y` | double | The parameter to set vehicle footprint manually |
40+
| `max_y` | double | The parameter to set vehicle footprint manually |
41+
42+
## Assumptions / Known limits
43+
44+
## (Optional) Error detection and handling
45+
46+
## (Optional) Performance characterization
47+
48+
## (Optional) References/External links
49+
50+
## (Optional) Future extensions / Unimplemented parts

‎perception/ground_segmentation/docs/scan-ground-filter.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Scan Ground Filter
2+
3+
## Purpose
4+
5+
The purpose of this node is that remove the ground points from the input pointcloud.
6+
7+
## Inner-workings / Algorithms
8+
9+
This algorithm works by following steps,
10+
11+
1. Divide whole pointclouds into groups by horizontal angle and sort by xy-distance.
12+
2. Check the distance and vertical angle of the point one by one.
13+
3. Set a center of the ground contact point of the rear or front wheels as the initial point.
14+
4. Check vertical angle between the points. If the angle from the initial point is larger than "global_slope_max", the point is classified as "no ground".
15+
5. If the angle from the previous point is larger than "local_max_slope", the point is classified as "no ground".
16+
6. Otherwise the point is labeled as "ground point".
17+
7. If the distance from the last checked point is close, ignore any vertical angle and set current point attribute to the same as the last point.
18+
19+
## Inputs / Outputs
20+
21+
This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).
22+
23+
## Parameters
24+
25+
### Node Parameters
26+
27+
This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).
28+
29+
#### Core Parameters
30+
31+
| Name | Type | Default Value | Description |
32+
| --------------------------------- | ------ | ------------- | ----------------------------------------------------------------------------- |
33+
| `base_frame` | string | "base_link" | base_link frame |
34+
| `global_slope_max` | double | 8.0 | The global angle to classify as the ground or object [deg] |
35+
| `local_max_slope` | double | 6.0 | The local angle to classify as the ground or object [deg] |
36+
| `radial_divider_angle` | double | 1.0 | The angle which divide the whole pointcloud to sliced group [deg] |
37+
| `split_points_distance_tolerance` | double | 0.2 | The xy-distance threshold to to distinguishing far and near [m] |
38+
| `split_height_distance` | double | 0.2 | The height threshold to distinguishing far and near [m] |
39+
| `use_virtual_ground_point` | bool | true | whether to use the ground center of front wheels as the virtual ground point. |
40+
41+
## Assumptions / Known limits
42+
43+
## (Optional) Error detection and handling
44+
45+
## (Optional) Performance characterization
46+
47+
## (Optional) References/External links
48+
49+
## (Optional) Future extensions / Unimplemented parts
50+
51+
- Horizontal check for classification is not implemented yet.
52+
- Output ground visibility for diagnostic is not implemented yet.

0 commit comments

Comments
 (0)