diff --git a/perception/ground_segmentation/README.md b/perception/ground_segmentation/README.md index abc974b86f58c..ec52e33e6db0a 100644 --- a/perception/ground_segmentation/README.md +++ b/perception/ground_segmentation/README.md @@ -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: - -### 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] diff --git a/perception/ground_segmentation/docs/image/ground_filter-ray-xy.drawio.svg b/perception/ground_segmentation/docs/image/ground_filter-ray-xy.drawio.svg new file mode 100644 index 0000000000000..0222f5b75dd55 --- /dev/null +++ b/perception/ground_segmentation/docs/image/ground_filter-ray-xy.drawio.svg @@ -0,0 +1,4 @@ + + + +
Radiation direction
Radiation directionViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/perception/ground_segmentation/docs/image/ground_filter-ray-xz.drawio.svg b/perception/ground_segmentation/docs/image/ground_filter-ray-xz.drawio.svg new file mode 100644 index 0000000000000..fb2cbe364b2eb --- /dev/null +++ b/perception/ground_segmentation/docs/image/ground_filter-ray-xz.drawio.svg @@ -0,0 +1,4 @@ + + + +
initial_max_slope
initial_max_slope
min_height_threshold
min_height_threshold
p0
p0
p1
p1
p2
p2
p3
p3
p4
p4
p5
p5
p6
p6
general_max_slope
general_max_slope
local_max_slope
local_max_slopeViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/perception/ground_segmentation/docs/ransac-ground-filter.md b/perception/ground_segmentation/docs/ransac-ground-filter.md new file mode 100644 index 0000000000000..8bec24ea34d0c --- /dev/null +++ b/perception/ground_segmentation/docs/ransac-ground-filter.md @@ -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 + + + +## (Optional) Future extensions / Unimplemented parts diff --git a/perception/ground_segmentation/docs/ray-ground-filter.md b/perception/ground_segmentation/docs/ray-ground-filter.md new file mode 100644 index 0000000000000..9360b38a272b1 --- /dev/null +++ b/perception/ground_segmentation/docs/ray-ground-filter.md @@ -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 diff --git a/perception/ground_segmentation/docs/scan-ground-filter.md b/perception/ground_segmentation/docs/scan-ground-filter.md new file mode 100644 index 0000000000000..d854860b2c6c5 --- /dev/null +++ b/perception/ground_segmentation/docs/scan-ground-filter.md @@ -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.