Skip to content

Commit

Permalink
docs: update readme of ground segmentation (autowarefoundation#764) (a…
Browse files Browse the repository at this point in the history 
…utowarefoundation#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>
  • Loading branch information
@wep21 @tkimura4
3 people authored Dec 8, 2021
1 parent 14af4bb commit f34431d
Show file tree
Hide file tree
Showing 6 changed files with 186 additions and 65 deletions.
92 changes: 27 additions & 65 deletions perception/ground_segmentation/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,88 +2,50 @@

## Purpose

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

## Inner-workings / Algorithms

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

This algorithm is SAC-based ground segmentation.

See: <https://pcl.readthedocs.io/projects/tutorials/en/latest/planar_segmentation.html>

### Ray Ground Filter

This algorithm is deprecated in current architecture.

### Scan Ground Filter

This algorithm works by following steps,

1. Divide whole pointclouds into groups by horizontal angle and sort by xy-distance.
2. Check the distance and vertical angle of the point one by one.
3. Set a center of the ground contact point of the rear or front wheels as the initial point.
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".
5. If the angle from the previous point is larger than "local_max_slope", the point is classified as "no ground".
6. Otherwise the point is labeled as "ground point".
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.
| Filter Name | Description | Detail |
| -------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| 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) |
| scan_ground_filter | Almost the same method as `ray_ground_filter`, but with slightly improved performance | [link](docs/scan-ground-filter.md) |
| ransac_ground_filter | A method of removing the ground by approximating the ground to a plane | [link](docs/ransac-ground-filter.md) |

## Inputs / Outputs

### Input

| Name | Type | Description |
| -------- | -------------------------- | --------------------------- |
| `~input` | `sensor_msgs::PointCloud2` | outlier filtered pointcloud |
| Name | Type | Description |
| ----------------- | ------------------------------- | ----------------- |
| `~/input/points` | `sensor_msgs::msg::PointCloud2` | reference points |
| `~/input/indices` | `pcl_msgs::msg::Indices` | reference indices |

### Output

| Name | Type | Description |
| --------- | -------------------------- | -------------------- |
| `~output` | `sensor_msgs::PointCloud2` | no ground pointcloud |
| Name | Type | Description |
| ----------------- | ------------------------------- | --------------- |
| `~/output/points` | `sensor_msgs::msg::PointCloud2` | filtered points |

## Parameters

### Ransac Ground Filter

#### Core Parameters

| Name | Type | Default Value | Description |
| ----------------------- | ------ | ------------- | --------------------------------------------------------------- |
| `base_frame` | string | "base_link" | base_link frame |
| `unit_axis` | string | "z" | The axis which we need to search ground plane |
| `max_iterations` | int | 1000 | The maximum number of iterations |
| `outlier_threshold` | double | 0.01 | The distance threshold to the model [m] |
| `plane_slope_threshold` | double | 10.0 | The slope threshold to prevent mis-fitting [deg] |
| `voxel_size_x` | double | 0.04 | voxel size x [m] |
| `voxel_size_y` | double | 0.04 | voxel size y [m] |
| `voxel_size_z` | double | 0.04 | voxel size z [m] |
| `height_threshold` | double | 0.01 | The height threshold from ground plane for no ground points [m] |
| `debug` | bool | false | whether to output debug information |

### Scan Ground Filter

#### Core Parameters

| Name | Type | Default Value | Description |
| --------------------------------- | ------ | ------------- | ----------------------------------------------------------------------------- |
| `base_frame` | string | "base_link" | base_link frame |
| `global_slope_max` | double | 8.0 | The global angle to classify as the ground or object [deg] |
| `local_max_slope` | double | 6.0 | The local angle to classify as the ground or object [deg] |
| `radial_divider_angle` | double | 1.0 | The angle which divide the whole pointcloud to sliced group [deg] |
| `split_points_distance_tolerance` | double | 0.2 | The xy-distance threshold to to distinguishing far and near [m] |
| `split_height_distance` | double | 0.2 | The height threshold to distinguishing far and near [m] |
| `use_virtual_ground_point` | bool | true | whether to use the ground center of front wheels as the virtual ground point. |

## Assumptions / Known limits
### Node Parameters

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

## (Optional) Performance characterization
## Assumptions / Known limits

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

## (Optional) Future extensions / Unimplemented parts
## References/External links

- Horizontal check for classification is not implemented yet.
- Output ground visibility for diagnostic is not implemented yet.
[1] <https://github.com/ros-perception/perception_pcl/blob/ros2/pcl_ros/src/pcl_ros/filters/filter.cpp>
4 changes: 4 additions & 0 deletions perception/ground_segmentation/docs/image/ground_filter-ray-xy.drawio.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions perception/ground_segmentation/docs/image/ground_filter-ray-xz.drawio.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
49 changes: 49 additions & 0 deletions perception/ground_segmentation/docs/ransac-ground-filter.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# RANSAC Ground Filter

## Purpose

The purpose of this node is that remove the ground points from the input pointcloud.

## Inner-workings / Algorithms

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.

## Inputs / Outputs

This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).

## Parameters

### Node Parameters

This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).

#### Core Parameters

| Name | Type | Description |
| ----------------------- | ------ | --------------------------------------------------------------- |
| `base_frame` | string | base_link frame |
| `unit_axis` | string | The axis which we need to search ground plane |
| `max_iterations` | int | The maximum number of iterations |
| `outlier_threshold` | double | The distance threshold to the model [m] |
| `plane_slope_threshold` | double | The slope threshold to prevent mis-fitting [deg] |
| `voxel_size_x` | double | voxel size x [m] |
| `voxel_size_y` | double | voxel size y [m] |
| `voxel_size_z` | double | voxel size z [m] |
| `height_threshold` | double | The height threshold from ground plane for no ground points [m] |
| `debug` | bool | whether to output debug information |

## Assumptions / Known limits

- This method can't handle slopes.
- The input points is filtered so that it is almost flat.

## (Optional) Error detection and handling

## (Optional) Performance characterization

## References/External links

<https://pcl.readthedocs.io/projects/tutorials/en/latest/planar_segmentation.html>

## (Optional) Future extensions / Unimplemented parts
50 changes: 50 additions & 0 deletions perception/ground_segmentation/docs/ray-ground-filter.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Ray Ground Filter

## Purpose

The purpose of this node is that remove the ground points from the input pointcloud.

## Inner-workings / Algorithms

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.

![ray-xy](./image/ground_filter-ray-xy.drawio.svg)

## Inputs / Outputs

This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).

## Parameters

### Node Parameters

This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).

### Core Parameters

![ray-xz](./image/ground_filter-ray-xz.drawio.svg)

| Name | Type | Description |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `base_frame` | string | The target frame of input points |
| `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 |
| `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` |
| `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 |
| `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. |
| `radial_divider_angle` | double | The angle of ray |
| `concentric_divider_distance` | double | Only check points which radius is larger than `concentric_divider_distance` |
| `reclass_distance_threshold` | double | To check if point is to far from previous one, if so classify again |
| `min_x` | double | The parameter to set vehicle footprint manually |
| `max_x` | double | The parameter to set vehicle footprint manually |
| `min_y` | double | The parameter to set vehicle footprint manually |
| `max_y` | double | The parameter to set vehicle footprint manually |

## Assumptions / Known limits

## (Optional) Error detection and handling

## (Optional) Performance characterization

## (Optional) References/External links

## (Optional) Future extensions / Unimplemented parts
52 changes: 52 additions & 0 deletions perception/ground_segmentation/docs/scan-ground-filter.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Scan Ground Filter

## Purpose

The purpose of this node is that remove the ground points from the input pointcloud.

## Inner-workings / Algorithms

This algorithm works by following steps,

1. Divide whole pointclouds into groups by horizontal angle and sort by xy-distance.
2. Check the distance and vertical angle of the point one by one.
3. Set a center of the ground contact point of the rear or front wheels as the initial point.
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".
5. If the angle from the previous point is larger than "local_max_slope", the point is classified as "no ground".
6. Otherwise the point is labeled as "ground point".
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.

## Inputs / Outputs

This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).

## Parameters

### Node Parameters

This implementation inherits `pointcloud_preprocessor::Filter` class, please refer [README](../README.md).

#### Core Parameters

| Name | Type | Default Value | Description |
| --------------------------------- | ------ | ------------- | ----------------------------------------------------------------------------- |
| `base_frame` | string | "base_link" | base_link frame |
| `global_slope_max` | double | 8.0 | The global angle to classify as the ground or object [deg] |
| `local_max_slope` | double | 6.0 | The local angle to classify as the ground or object [deg] |
| `radial_divider_angle` | double | 1.0 | The angle which divide the whole pointcloud to sliced group [deg] |
| `split_points_distance_tolerance` | double | 0.2 | The xy-distance threshold to to distinguishing far and near [m] |
| `split_height_distance` | double | 0.2 | The height threshold to distinguishing far and near [m] |
| `use_virtual_ground_point` | bool | true | whether to use the ground center of front wheels as the virtual ground point. |

## Assumptions / Known limits

## (Optional) Error detection and handling

## (Optional) Performance characterization

## (Optional) References/External links

## (Optional) Future extensions / Unimplemented parts

- Horizontal check for classification is not implemented yet.
- Output ground visibility for diagnostic is not implemented yet.

0 comments on commit f34431d

Please sign in to comment.