Skip to content

Commit b95367b

Browse files
scepter914pre-commit-ci[bot]HansRobomiursh
authored
chore(radar_object_clustering): fix README (#6260)
* chore(radar_object_clustering): fix README Signed-off-by: scepter914 <scepter914@gmail.com> * style(pre-commit): autofix * Update perception/radar_object_clustering/README.md Co-authored-by: Shunsuke Miura <37187849+miursh@users.noreply.github.com> Signed-off-by: scepter914 <scepter914@gmail.com> --------- Signed-off-by: scepter914 <scepter914@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Kotaro Yoshimoto <pythagora.yoshimoto@gmail.com> Co-authored-by: Shunsuke Miura <37187849+miursh@users.noreply.github.com>
1 parent 4bb003d commit b95367b

File tree

1 file changed

+78
-31
lines changed

1 file changed

+78
-31
lines changed

‎perception/radar_object_clustering/README.md

+78-31
Original file line numberDiff line numberDiff line change
@@ -7,22 +7,22 @@ In other word, this package can combine multiple radar detections from one objec
77

88
![radar_clustering](docs/radar_clustering.drawio.svg)
99

10-
## Algorithm
10+
## Design
1111

1212
### Background
1313

1414
In radars with object output, there are cases that multiple detection results are obtained from one object, especially for large vehicles such as trucks and trailers.
1515
Its multiple detection results cause separation of objects in tracking module.
1616
Therefore, by this package the multiple detection results are clustered into one object in advance.
1717

18-
### Detail Algorithm
18+
### Algorithm
1919

20-
- Sort by distance from `base_link`
20+
- 1. Sort by distance from `base_link`
2121

2222
At first, to prevent changing the result from depending on the order of objects in DetectedObjects, input objects are sorted by distance from `base_link`.
2323
In addition, to apply matching in closeness order considering occlusion, objects are sorted in order of short distance in advance.
2424

25-
- Clustering
25+
- 2. Clustering
2626

2727
If two radar objects are near, and yaw angle direction and velocity between two radar objects is similar (the degree of these is defined by parameters), then these are clustered.
2828
Note that radar characteristic affect parameters for this matching.
@@ -32,13 +32,13 @@ For example, if resolution of range distance or angle is low and accuracy of vel
3232

3333
After grouping for all radar objects, if multiple radar objects are grouping, the kinematics of the new clustered object is calculated from average of that and label and shape of the new clustered object is calculated from top confidence in radar objects.
3434

35-
- Fixed label correction
35+
- 3. Fixed label correction
3636

3737
When the label information from radar outputs lack accuracy, `is_fixed_label` parameter is recommended to set `true`.
3838
If the parameter is true, the label of a clustered object is overwritten by the label set by `fixed_label` parameter.
3939
If this package use for faraway dynamic object detection with radar, the parameter is recommended to set to `VEHICLE`.
4040

41-
- Fixed size correction
41+
- 4. Fixed size correction
4242

4343
When the size information from radar outputs lack accuracy, `is_fixed_size` parameter is recommended to set `true`.
4444
If the parameter is true, the size of a clustered object is overwritten by the label set by `size_x`, `size_y`, and `size_z` parameters.
@@ -51,28 +51,75 @@ Note that to use for [multi_objects_tracker](https://github.com/autowarefoundati
5151
For now, size estimation for clustered object is not implemented.
5252
So `is_fixed_size` parameter is recommended to set `true`, and size parameters is recommended to set to value near to average size of vehicles.
5353

54-
## Input
55-
56-
| Name | Type | Description |
57-
| ----------------- | ----------------------------------------------------- | -------------- |
58-
| `~/input/objects` | autoware_auto_perception_msgs/msg/DetectedObjects.msg | Radar objects. |
59-
60-
## Output
61-
62-
| Name | Type | Description |
63-
| ------------------ | ----------------------------------------------------- | -------------- |
64-
| `~/output/objects` | autoware_auto_perception_msgs/msg/DetectedObjects.msg | Output objects |
65-
66-
## Parameters
67-
68-
| Name | Type | Description | Default value |
69-
| :------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
70-
| `angle_threshold` | double | Angle threshold to judge whether radar detections come from one object. [rad] | 0.174 |
71-
| `distance_threshold` | double | Distance threshold to judge whether radar detections come from one object. [m] | 4.0 |
72-
| `velocity_threshold` | double | Velocity threshold to judge whether radar detections come from one object. [m/s] | 2.0 |
73-
| `is_fixed_label` | bool | If this parameter is true, the label of a clustered object is overwritten by the label set by `fixed_label` parameter. | false |
74-
| `fixed_label` | string | If `is_fixed_label` is true, the label of a clustered object is overwritten by this parameter. | "UNKNOWN" |
75-
| `is_fixed_size` | bool | If this parameter is true, the size of a clustered object is overwritten by the label set by `size_x`, `size_y`, and `size_z` parameters. | false |
76-
| `size_x` | double | If `is_fixed_size` is true, the x-axis size of a clustered object is overwritten by this parameter. [m] | 4.0 |
77-
| `size_y` | double | If `is_fixed_size` is true, the y-axis size of a clustered object is overwritten by this parameter. [m] | 1.5 |
78-
| `size_z` | double | If `is_fixed_size` is true, the z-axis size of a clustered object is overwritten by this parameter. [m] | 1.5 |
54+
## Interface
55+
56+
### Input
57+
58+
- `~/input/objects` (`autoware_auto_perception_msgs/msg/DetectedObjects.msg`)
59+
- Radar objects
60+
61+
### Output
62+
63+
- `~/output/objects` (`autoware_auto_perception_msgs/msg/DetectedObjects.msg`)
64+
- Output objects
65+
66+
### Parameter
67+
68+
- `angle_threshold` (double) [rad]
69+
- Default parameter is 0.174.
70+
- `distance_threshold` (double) [m]
71+
- Default parameter is 4.0.
72+
- `velocity_threshold` (double) [m/s]
73+
- Default parameter is 2.0.
74+
75+
These parameter are thresholds for angle, distance, and velocity to judge whether radar detections come from one object in "clustering" processing, which is written in detail at algorithm section.
76+
If all of the difference in angle/distance/velocity from two objects is less than the thresholds, then the two objects are merged to one clustered object.
77+
If these parameter is larger, more objects are merged to one clustered object.
78+
79+
These are used in `isSameObject` function as below.
80+
81+
```cpp
82+
83+
bool RadarObjectClusteringNode::isSameObject(
84+
const DetectedObject & object_1, const DetectedObject & object_2)
85+
{
86+
const double angle_diff = std::abs(tier4_autoware_utils::normalizeRadian(
87+
tf2::getYaw(object_1.kinematics.pose_with_covariance.pose.orientation) -
88+
tf2::getYaw(object_2.kinematics.pose_with_covariance.pose.orientation)));
89+
const double velocity_diff = std::abs(
90+
object_1.kinematics.twist_with_covariance.twist.linear.x -
91+
object_2.kinematics.twist_with_covariance.twist.linear.x);
92+
const double distance = tier4_autoware_utils::calcDistance2d(
93+
object_1.kinematics.pose_with_covariance.pose.position,
94+
object_2.kinematics.pose_with_covariance.pose.position);
95+
96+
if (
97+
distance < node_param_.distance_threshold && angle_diff < node_param_.angle_threshold &&
98+
velocity_diff < node_param_.velocity_threshold) {
99+
return true;
100+
} else {
101+
return false;
102+
}
103+
}
104+
```
105+
106+
- `is_fixed_label` (bool)
107+
- Default parameter is false.
108+
- `fixed_label` (string)
109+
- Default parameter is "UNKNOWN".
110+
111+
`is_fixed_label` is the flag to use fixed label.
112+
If it is true, the label of a clustered object is overwritten by the label set by `fixed_label` parameter.
113+
If the radar objects do not have label information, then it is recommended to use fixed label.
114+
115+
- `is_fixed_size` (bool)
116+
- Default parameter is false.
117+
- `size_x` (double) [m]
118+
- Default parameter is 4.0.
119+
- `size_y` (double) [m]
120+
- Default parameter is 1.5.
121+
- `size_z` (double) [m]
122+
- Default parameter is 1.5.
123+
124+
`is_fixed_size` is the flag to use fixed size parameters.
125+
If it is true, the size of a clustered object is overwritten by the label set by `size_x`, `size_y`, and `size_z` parameters.

0 commit comments

Comments
 (0)