refactor(lidar_centerpoint): rework parameters

launch/tier4_perception_launch/launch/object_recognition/detection/detector/lidar_dnn_detector.launch.xml

@@ -45,7 +45,7 @@
         <arg name="output/objects" value="$(var output/objects)"/>
         <arg name="model_name" value="$(var centerpoint_model_name)"/>
         <arg name="model_path" value="$(var centerpoint_model_path)"/>
-        <arg name="model_param_path" value="$(var lidar_model_param_path)/$(var centerpoint_model_name).param.yaml"/>
+        <arg name="model_param_path" value="$(var lidar_model_param_path)/$(var centerpoint_model_name)_base.param.yaml"/>
         <arg name="ml_package_param_path" value="$(var centerpoint_model_path)/$(var centerpoint_model_name)_ml_package.param.yaml"/>
         <arg name="class_remapper_param_path" value="$(var centerpoint_model_path)/detection_class_remapper.param.yaml"/>
 

perception/lidar_centerpoint/README.md

@@ -28,33 +28,21 @@ We trained the models using <https://github.com/open-mmlab/mmdetection3d>.
 
 ## Parameters
 
-### Core Parameters
-
-| Name                                             | Type         | Default Value             | Description                                                   |
-| ------------------------------------------------ | ------------ | ------------------------- | ------------------------------------------------------------- |
-| `encoder_onnx_path`                              | string       | `""`                      | path to VoxelFeatureEncoder ONNX file                         |
-| `encoder_engine_path`                            | string       | `""`                      | path to VoxelFeatureEncoder TensorRT Engine file              |
-| `head_onnx_path`                                 | string       | `""`                      | path to DetectionHead ONNX file                               |
-| `head_engine_path`                               | string       | `""`                      | path to DetectionHead TensorRT Engine file                    |
-| `build_only`                                     | bool         | `false`                   | shutdown the node after TensorRT engine file is built         |
-| `trt_precision`                                  | string       | `fp16`                    | TensorRT inference precision: `fp32` or `fp16`                |
-| `post_process_params.score_threshold`            | double       | `0.4`                     | detected objects with score less than threshold are ignored   |
-| `post_process_params.yaw_norm_thresholds`        | list[double] | [0.3, 0.3, 0.3, 0.3, 0.0] | An array of distance threshold values of norm of yaw [rad].   |
-| `post_process_params.iou_nms_target_class_names` | list[string] | -                         | target classes for IoU-based Non Maximum Suppression          |
-| `post_process_params.iou_nms_search_distance_2d` | double       | -                         | If two objects are farther than the value, NMS isn't applied. |
-| `post_process_params.iou_nms_threshold`          | double       | -                         | IoU threshold for the IoU-based Non Maximum Suppression       |
-| `post_process_params.has_twist`                  | boolean      | false                     | Indicates whether the model outputs twist value.              |
-| `densification_params.world_frame_id`            | string       | `map`                     | the world frame id to fuse multi-frame pointcloud             |
-| `densification_params.num_past_frames`           | int          | `1`                       | the number of past frames to fuse with the current frame      |
+### Core Parameters for base methods
 
-### The `build_only` option
+{{ json_to_markdown("perception/lidar_centerpoint/schema/centerpoint_base.schema.json") }}
 
-The `lidar_centerpoint` node has `build_only` option to build the TensorRT engine file from the ONNX file.
-Although it is preferred to move all the ROS parameters in `.param.yaml` file in Autoware Universe, the `build_only` option is not moved to the `.param.yaml` file for now, because it may be used as a flag to execute the build as a pre-task. You can execute with the following command:
+### Core Parameters for ML methods
 
-```bash
-ros2 launch lidar_centerpoint lidar_centerpoint.launch.xml model_name:=centerpoint_tiny model_path:=/home/autoware/autoware_data/lidar_centerpoint model_param_path:=$(ros2 pkg prefix lidar_centerpoint --share)/config/centerpoint_tiny.param.yaml build_only:=true
-```
+{{ json_to_markdown("perception/lidar_centerpoint/schema/centerpoint_ml_package.schema.json") }}
+
+### Remapper
+
+{{ json_to_markdown("perception/lidar_centerpoint/schema/detection_class_remapper.schema.json") }}
+
+### The `build_only` option
+
+The `lidar_centerpoint` node has a `build_only` option to build the required TensorRT engine file from an ONNX file. This parameter is set in the launch file of this package, whereas all other parameters are set via `.param.yaml` files.
 
 ## Assumptions / Known limits
 
@@ -236,33 +224,27 @@ python projects/AutowareCenterPoint/centerpoint_onnx_converter.py --cfg projects
 
 #### Create the config file for the custom model
 
-Create a new config file named **centerpoint_custom.param.yaml** under the config file directory of the lidar_centerpoint node. Sets the parameters of the config file like
-point_cloud_range, point_feature_size, voxel_size, etc. according to the training config file.
-
-```yaml
-/**:
-  ros__parameters:
-    class_names: ["CAR", "TRUCK", "BUS", "BICYCLE", "PEDESTRIAN"]
-    point_feature_size: 4
-    max_voxel_size: 40000
-    point_cloud_range: [-51.2, -51.2, -3.0, 51.2, 51.2, 5.0]
-    voxel_size: [0.2, 0.2, 8.0]
-    downsample_factor: 1
-    encoder_in_feature_size: 9
-    # post-process params
-    circle_nms_dist_threshold: 0.5
-    iou_nms_target_class_names: ["CAR"]
-    iou_nms_search_distance_2d: 10.0
-    iou_nms_threshold: 0.1
-    yaw_norm_thresholds: [0.3, 0.3, 0.3, 0.3, 0.0]
+Create a new config file named centerpoint_custom.param.yaml under the config file directory of the lidar_centerpoint node. Sets the parameters of the ml model's config file according to the default ml config file [centerpoint_ml_package.param.yaml](/perception/lidar_centerpoint/config/centerpoint_ml_package.param.yaml). For detailed explanations and additional parameters, refer to the [Core Parameters for ML methods](#core-parameters-for-ml-methods) section.
+
+Start by creating a new file named centerpoint_custom.param.yaml. This naming convention helps in distinguishing between different model configurations. Open your newly created .param.yaml file and set the necessary parameters based on your model's requirements. 
+Common parameters to configure include:
+```
+point_cloud_range: Define the range of the point cloud data. Example: [-76.8, -76.8, -4.0, 76.8, 76.8, 6.0]
+point_feature_size: Specify the number of features each point in the point cloud should have. Example: 4
+voxel_size: Set the size of each voxel in the point cloud. Example: [0.32, 0.32, 10.0]
+max_voxel_size: Set the maximum size of voxel grid. Example: 40000
+downsample_factor: Set the scale factor of downsampling points. Example: 1
+encoder_in_feature_size: A size of encoder input feature channels. Example: 9
+has_variance: Flag indicating if the model includes variance estimation. Example: false
+has_twist: Flag indicating if the model includes twist estimation. Example: false
 ```
 
 #### Launch the lidar_centerpoint node
 
 ```bash
 cd /YOUR/AUTOWARE/PATH/Autoware
 source install/setup.bash
-ros2 launch lidar_centerpoint lidar_centerpoint.launch.xml  model_name:=centerpoint_custom  model_path:=/PATH/TO/ONNX/FILE/
+ros2 launch lidar_centerpoint lidar_centerpoint.launch.xml  model_name:=centerpoint_(your_selection_of_model)  model_path:=/PATH/TO/ONNX/FILE/
 ```
 
 ### Changelog

perception/lidar_centerpoint/launch/lidar_centerpoint.launch.xml

@@ -5,7 +5,7 @@
   <arg name="data_path" default="$(env HOME)/autoware_data" description="packages data and artifacts directory path"/>
   <arg name="model_name" default="centerpoint_tiny" description="options: `centerpoint` or `centerpoint_tiny`"/>
   <arg name="model_path" default="$(var data_path)/lidar_centerpoint"/>
-  <arg name="model_param_path" default="$(find-pkg-share lidar_centerpoint)/config/$(var model_name).param.yaml"/>
+  <arg name="model_param_path" default="$(find-pkg-share lidar_centerpoint)/config/$(var model_name)_base.param.yaml"/>
   <arg name="ml_package_param_path" default="$(var model_path)/$(var model_name)_ml_package.param.yaml"/>
   <arg name="class_remapper_param_path" default="$(var model_path)/detection_class_remapper.param.yaml"/>
   <arg name="build_only" default="false" description="shutdown node after TensorRT engine file is built"/>

perception/lidar_centerpoint/schema/centerpoint.schemal.json → perception/lidar_centerpoint/schema/centerpoint_base.schema.json

@@ -3,9 +3,29 @@
   "title": "Parameters for Lidar Centerpoint Node",
   "type": "object",
   "definitions": {
-    "centerpoint": {
+    "centerpoint_base": {
       "type": "object",
       "properties": {
+        "encoder_onnx_path": {
+          "type": "string",
+          "description": "Path to VoxelFeatureEncoder ONNX file.",
+          "default": ""
+        },
+        "encoder_engine_path": {
+          "type": "string",
+          "description": "Path to VoxelFeatureEncoder TensorRT Engine file.",
+          "default": ""
+        },
+        "head_onnx_path": {
+          "type": "string",
+          "description": "Path to DetectionHead ONNX file.",
+          "default": ""
+        },
+        "head_engine_path": {
+          "type": "string",
+          "description": "Path to DetectionHead TensorRT Engine file.",
+          "default": ""
+        },
         "trt_precision": {
           "type": "string",
           "description": "TensorRT inference precision.",
@@ -54,11 +74,6 @@
               "default": 0.1,
               "minimum": 0.0,
               "maximum": 1.0
-            },
-            "has_twist": {
-              "type": "boolean",
-              "description": "Indicates whether the model outputs twist value.",
-              "default": false
             }
           }
         },

perception/lidar_centerpoint/schema/centerpoint_ml_package.schema.json

@@ -36,7 +36,7 @@
               "description": "An array of voxel grid sizes for PointPainting, this must have same length with `paint_class_names`.",
               "default": [0.32, 0.32, 10.0]
             },
-            "down_sample_factor": {
+            "downsample_factor": {
               "type": "integer",
               "description": "A scale factor of downsampling points",
               "default": 1,
@@ -46,6 +46,16 @@
               "type": "integer",
               "description": "A size of encoder input feature channels.",
               "default": 9
+            },
+            "has_variance": {
+              "type": "boolean",
+              "description": "Flag indicating if the model includes variance estimation.",
+              "default": false
+            },
+            "has_twist": {
+              "type": "boolean",
+              "description": "Flag indicating if the model includes twist estimation.",
+              "default": false
             }
           }
         }

perception/lidar_centerpoint/schema/centerpoint_sigma_ml_package.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Parameters for Centerpoint Sigma ML model",
+  "type": "object",
+  "definitions": {
+    "centerpoint_sigma_ml_package": {
+      "type": "object",
+      "properties": {
+        "model_params": {
+          "type": "object",
+          "description": "Parameters for model configuration.",
+          "properties": {
+            "class_names": {
+              "type": "array",
+              "description": "An array of class names will be predicted.",
+              "default": ["CAR", "TRUCK", "BUS", "BICYCLE", "PEDESTRIAN"],
+              "items": {
+                "type": "string"
+              },
+              "uniqueItems": true
+            },
+            "point_feature_size": {
+              "type": "integer",
+              "description": "A number of channels of point feature layer.",
+              "default": 4
+            },
+            "max_voxel_size": {
+              "type": "integer",
+              "description": "A maximum size of voxel grid.",
+              "default": 40000
+            },
+            "point_cloud_range": {
+              "type": "array",
+              "description": "An array of distance ranges of each class, this must have same length with `class_names`.",
+              "default": [-76.8, -76.8, -4.0, 76.8, 76.8, 6.0],
+              "items": {
+                "type": "number"
+              }
+            },
+            "voxel_size": {
+              "type": "array",
+              "description": "An array of voxel grid sizes for PointPainting, this must have same length with `paint_class_names`.",
+              "default": [0.32, 0.32, 10.0],
+              "items": {
+                "type": "number"
+              }
+            },
+            "downsample_factor": {
+              "type": "integer",
+              "description": "A scale factor of downsampling points.",
+              "default": 1,
+              "minimum": 1
+            },
+            "encoder_in_feature_size": {
+              "type": "integer",
+              "description": "A size of encoder input feature channels.",
+              "default": 9
+            },
+            "has_variance": {
+              "type": "boolean",
+              "description": "Flag indicating if the model includes variance estimation.",
+              "default": false
+            },
+            "has_twist": {
+              "type": "boolean",
+              "description": "Flag indicating if the model includes twist estimation.",
+              "default": false
+            }
+          },
+          "required": [
+            "class_names",
+            "point_feature_size",
+            "max_voxel_size",
+            "point_cloud_range",
+            "voxel_size",
+            "downsample_factor",
+            "encoder_in_feature_size",
+            "has_variance",
+            "has_twist"
+          ]
+        }
+      },
+      "required": ["model_params"]
+    }
+  },
+  "properties": {
+    "/**": {
+      "type": "object",
+      "properties": {
+        "ros__parameters": {
+          "$ref": "#/definitions/centerpoint_sigma_ml_package"
+        }
+      },
+      "required": ["ros__parameters"]
+    }
+  },
+  "required": ["/**"]
+}