diff --git a/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md b/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md index 29c1252bd52..6e6bb4a61ee 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md +++ b/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md @@ -117,7 +117,10 @@ References: 1. Calibration of sensor - The conversion relationship between every sensor coordinate system and `base_link` can be obtained through sensor calibration technology. How to calibrating your sensors refer to this link [calibrating your sensors](../../../how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md). + The conversion relationship between every sensor coordinate system and `base_link` can be obtained through sensor calibration technology. + Please consult the following link + [calibrating your sensors](../../../how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/calibrating-sensors) for instructions + on how to calibrate your sensors. 2. Localization diff --git a/docs/how-to-guides/integrating-autoware/.pages b/docs/how-to-guides/integrating-autoware/.pages index d520a5f69a0..9fdb9974a05 100644 --- a/docs/how-to-guides/integrating-autoware/.pages +++ b/docs/how-to-guides/integrating-autoware/.pages @@ -1,7 +1,7 @@ nav: - overview.md - 1. Creating your Autoware repositories: creating-your-autoware-repositories - - 2. Creating vehicle and sensor description: creating-vehicle-and-sensor-description + - 2. Creating vehicle and sensor model: creating-vehicle-and-sensor-model - 3. Creating vehicle interface: creating-vehicle-interface-package - 4. Creating maps: creating-maps - 5. Launch Autoware: launch-autoware diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md deleted file mode 100644 index ab1b801fe54..00000000000 --- a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md +++ /dev/null @@ -1,204 +0,0 @@ -# Creating vehicle and sensor description - -## Introduction - -This page introduce following topics. - -1. YOUR_VEHICLE_description -2. YOUR_SENSOR_KIT_description -3. individual_parameter -4. YOUR_VEHICLE_launch -5. YOUR_SENSOR_KIT_launch - -## 1. YOUR_VEHICLE_description - -In `YOUR_VEHICLE_description`, the following configurations are set: - -1. vehicle_info.param.yaml (must be changed) -2. mesh file (\*.dae) -3. mirror.param.yaml(must be changed) -4. simulator_model.param.yaml -5. vehicle.xacro - -### 1. vehicle_info.param.yaml - -Defines the vehicle dimensions. For more details on each parameter, please click [here](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-dimensions). - -### 2. mesh file - -A 3D model file used for visualization in rviz. - -### 3. mirror.param.yaml - -Set according to the vehicle dimensions. Used in the [crop-box-filter](https://autowarefoundation.github.io/autoware.universe/main/sensing/pointcloud_preprocessor/docs/crop-box-filter) of [PointCloudPreprocessor](../../../design/autoware-architecture/sensing/data-types/point-cloud.md). - -### 4. simulator_model.param.yaml - -Configuration file for the [simulator environment](https://autowarefoundation.github.io/autoware.universe/main/simulator/simple_planning_simulator/design/simple_planning_simulator-design/). - -### 5. vehicle.xacro - -The entry point file that defines the entire URDF of the vehicle. It refers to `sensors.xacro`, which specifies the sensor mounting positions. - -## 2. YOUR_SENSOR_KIT_description - -In sensor_kit_description, the following files are configured: - -1. sensors.xacro (must be changed) -2. sensor_kit.xacro (must be changed) - -### 1. sensors.xacro - -Resolves the positions of sensors with `base_link` as the parent frame and defines the positions and orientations based on `sensors_calibration.yaml` in individual_params. - -> In Autoware, `/config/sensors_calibration.yaml` is not used. - -#### About sensor_kit_base_link - -A `sensor_kit` refers to a subset that includes multiple sensors, and `sensor_kit_base_link` is the name of its frame. -The positions and orientations within the kit are defined in `sensor_kit.xacro`. - -### 2. sensor_kit.xacro - -Resolves the positions of sensors with `sensor_kit_base_link` as the parent and defines the positions and orientations based on `sensor_kit_calibration.yaml` in individual_params. - -> In Autoware, `/config/sensor_kit_calibration.yaml` is not used. - -## 3. individual_parameter - -The `individual_parameter` is where parameters referenced by `sensors.xacro` and `sensor_kit.xacro` are stored. As the name imply, it is intended to manage parameters for multiple individual instances. - -### Introduction to Various Parameters - -1. sensors_calibration.yaml (must be changed) -2. sensor_kit_calibration.yaml (must be changed) -3. imu_corrector.param.yaml - -### 1. sensors_calibration.yaml - -A file that defines the mounting positions and orientations of sensors with `base_link` as the parent frame. - -### 2. sensor_kit_calibration.yaml - -A file that defines the mounting positions and orientations of sensors with `sensor_kit_base_link` as the parent frame. - -### 3. imu_corrector.param.yaml - -A file used by `imu_corrector`. - -### 4. Folder Structure - -Below is the default directory structure. - -```diff -individual_params/ -└─ config/ - └─ default/ - └─ sample_sensor_kit/ - ├─ imu_corrector.param.yaml - ├─ sensor_kit_calibration.yaml - └─ sensors_calibration.yaml -``` - -Copy and create a folder based on your `YOUR_SENSOR_KIT` name. - -```diff -individual_params/ -└─ config/ - └─ default/ -- └─ sample_sensor_kit/ -+ └─ / - ├─ imu_corrector.param.yaml - ├─ sensor_kit_calibration.yaml - └─ sensors_calibration.yaml -``` - -#### 4.1 Sample Usage - -Here is an example of managing parameters for multiple instances. -Add a `` directory and switch parameters using options at startup. - -```bash -# example1 (do not set vehicle_id) -$ ros2 launch autoware_launch autoware.launch.xml sensor_model:= vehicle_mode:= -# example2 (set vehicle_id as VEHICLE_1) -$ ros2 launch autoware_launch autoware.launch.xml sensor_model:= vehicle_mode:= vehicle_id:=VEHICLE_1 -# example3 (set vehicle_id as VEHICLE_2) -$ ros2 launch autoware_launch autoware.launch.xml sensor_model:= vehicle_mode:= vehicle_id:=VEHICLE_2 -``` - -##### Sample Directory Structure - -```diff -individual_params/ -└─ config/ - ├─ default/ - │ └─ / # example1 - │ ├─ imu_corrector.param.yaml - │ ├─ sensor_kit_calibration.yaml - │ └─ sensors_calibration.yaml -+ ├─ VEHICLE_1/ -+ │ └─ / # example2 -+ │ ├─ imu_corrector.param.yaml -+ │ ├─ sensor_kit_calibration.yaml -+ │ └─ sensors_calibration.yaml -+ └─ VEHICLE_2/ -+ └─ / # example3 -+ ├─ imu_corrector.param.yaml -+ ├─ sensor_kit_calibration.yaml -+ └─ sensors_calibration.yaml -``` - -## 4.YOUR_VEHICLE_launch - -`YOUR_VEHICLE_launch` is where the launch file for starting the drive system devices is stored. - -1. vehicle_interface.launch.xml (must be changed) - -### 1. vehicle_interface.launch.xml - -`vehicle_interface.launch.xml` is the launch file related to the drive system. Please modify it according to the configuration of your vehicle's drive system. - -If you are operating multiple vehicles, use the `vehicle_id` to switch to the corresponding configuration for each vehicle. - -## 5. YOUR_SENSOR_KIT_launch - -`YOUR_SENSOR_KIT_launch` is where the launch files related to sensor startup are stored. - -1. sensing.launch.xml (must be changed) -2. lidar.launch.xml (must be changed) -3. camera.launch.xml -4. imu.launch.xml (must be changed) -5. gnss.launch.xml -6. pointcloud_preprocessor.launch.py (must be changed) - -### 1. sensing.launch.xml - -`sensing.launch.xml` is the entry point that calls the launch files for all sensors. Modify it according to your sensor configuration. - -### 2. lidar.launch.xml - -`lidar.launch.xml` is the launch file related to starting the LiDAR driver. Modify it according to your LiDAR configuration. - -> In Autoware's initial configuration, it assumes converting the acquired data using `pointcloud_preprocessor.launch.py`. - -#### Example Configuration Items - -- Setting the frame_id defined in `YOUR_SENSOR_KIT_description`. -- Connection information for each device. - -### 3. camera.launch.xml - -`camera.launch.xml` is the launch file related to starting the camera driver. - -### 4. imu.launch.xml - -`imu.launch.xml` is the launch file related to starting the IMU driver. - -### 5. gnss.launch.xml - -`gnss.launch.xml` is the launch file related to starting the GNSS driver. - -### 6. pointcloud_preprocessor.launch.py - -`pointcloud_preprocessor.launch.py` is the launch file to convert the raw sensor data. For more information, please click [here](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture/sensing/data-types/point-cloud/). diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/.pages b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/.pages new file mode 100644 index 00000000000..b864eba4083 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/.pages @@ -0,0 +1,6 @@ +nav: + - index.md + - Creating sensor model: creating-sensor-model + - Creating individual params: creating-individual-params + - Creating vehicle model: creating-vehicle-model + - Calibrating sensors: calibrating-sensors diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/calibrating-sensors/.pages b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/calibrating-sensors/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/calibrating-sensors/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/calibrating-sensors/index.md similarity index 100% rename from docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md rename to docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/calibrating-sensors/index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-individual-params/.pages b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-individual-params/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-individual-params/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-individual-params/index.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-individual-params/index.md new file mode 100644 index 00000000000..7c679bddef6 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-individual-params/index.md @@ -0,0 +1,83 @@ +# Creating individual params + +## Introduction + +The [individual_params](https://github.com/autowarefoundation/autoware_individual_params) package is used +to define customized sensor calibrations for different vehicles. +It lets +you define customized sensor calibrations for different vehicles +while using the same launch files with the same sensor model. + +!!! Warning + + The "individual_params" package contains the calibration + results for your sensor kit and overrides the default calibration results found in + VEHICLE-ID_sensor_kit_description/config/ directory. + +## Placing your `individual_parameters` repository inside Autoware + +[Previously on this guide](../../creating-your-autoware-repositories/creating-autoware-repositories.md), +we forked the `autoware_individual_params` repository +to create a [tutorial_vehicle_individual_params](https://github.com/leo-drive/tutorial_vehicle_individual_params) repository +which will be used as an example for this section of the guide. +Your individual_parameters repository should be placed inside your Autoware folder following the same folder structure as the one shown below: + +??? note "sample folder structure for [`tutorial_vehicle_individual_params`](https://github.com/leo-drive/tutorial_vehicle_individual_params)" + + ```diff + / + └─ src/ + └─ param/ + └─ tutorial_vehicle_individual_params/ + └─ individual_params/ + └─ config/ + ├─ default/ + + └─ tutorial_vehicle/ + + └─ tutorial_vehicle_sensor_kit_launch/ + + ├─ imu_corrector.param.yaml + + ├─ sensor_kit_calibration.yaml + + └─ sensors_calibration.yaml + ``` + +After that, we need to build our `individual_params` package: + +```bash +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to individual_params +``` + +Now you are ready to use Autoware with a vehicle_id as an argument. +For example, if you are several, similar vehicles with different sensor calibration requirements, +your autoware_individual_params structure should look like this: + +```diff +individual_params/ +└─ config/ + ├─ default/ + │ └─ / # example1 + │ ├─ imu_corrector.param.yaml + │ ├─ sensor_kit_calibration.yaml + │ └─ sensors_calibration.yaml ++ ├─ VEHICLE_1/ ++ │ └─ / # example2 ++ │ ├─ imu_corrector.param.yaml ++ │ ├─ sensor_kit_calibration.yaml ++ │ └─ sensors_calibration.yaml ++ └─ VEHICLE_2/ ++ └─ / # example3 ++ ├─ imu_corrector.param.yaml ++ ├─ sensor_kit_calibration.yaml ++ └─ sensors_calibration.yaml +``` + +Then, you can use autoware with vehicle_id arguments like this: + +Add a `` as an argument and switch parameters using options at startup. + +```bash +# example1 (do not set vehicle_id) +$ ros2 launch autoware_launch autoware.launch.xml sensor_model:=_sensor_kit vehicle_model:=_vehicle +# example2 (set vehicle_id as VEHICLE_1) +$ ros2 launch autoware_launch autoware.launch.xml sensor_model:=_sensor_kit vehicle_model:=_vehicle vehicle_id:=VEHICLE_1 +# example3 (set vehicle_id as VEHICLE_2) +$ ros2 launch autoware_launch autoware.launch.xml sensor_model:=_sensor_kit vehicle_model:=_vehicle vehicle_id:=VEHICLE_2 +``` diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/.pages b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/images/sensing_launch_files.svg b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/images/sensing_launch_files.svg new file mode 100644 index 00000000000..6cf641896c8 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/images/sensing_launch_files.svg @@ -0,0 +1,4 @@ + + + +
sensing.launch.xml
sensing.launch.xml
camera.launch.xml
camera.launch.xml
gnss.launch.xml
gnss.launch.xml
imu.launch.xml
imu.launch.xml
lidar.launch.xml
lidar.launch.xml
vehicle_velocity_converter
.launch.xml
vehicle_velocity_converte...
lidar_model.launch.xml

(i.e., velodyne_VLP16.launch
.xml)
lidar_model.launch.xml...
nebula_node_container.py
nebula_node_container.py
common_sensor_launch
common_sen...
gnss_poser.launch.xml
gnss_poser.launch.xml
imu_corrector.launch.xml
imu_corrector.launch.xml
gyro_bias_estimator
.launch.xml
gyro_bias_estimator...
imu_corrector
imu_correc...
pointcloud_preprocessor
.launch.py
pointcloud_preprocessor...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/images/sensor_launch_design.svg b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/images/sensor_launch_design.svg new file mode 100644 index 00000000000..84c55c30b86 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/images/sensor_launch_design.svg @@ -0,0 +1,4 @@ + + + +
Sensor Launch
Sensor Lau...
Camera Driver
Camera Driver
Lidar Driver
Lidar Driver
GNSS/INS Driver
GNSS/INS Driver
IMU Driver
IMU Driver
CropBox Filter
CropBox Filter
Distortion Corrector
Distortion Corrector
Ring Outlier Filter
Ring Outlier Filter
Imu Corrector
Imu Corrector
common sensor launch
common sensor la...
Rectified Pointcloud
Rectified Pointcloud
IMU Messages
IMU Messages
Camera Sensor
Camera Sensor
Lidar Sensor
Lidar Sensor
GNSS Sensor
GNSS Sensor
IMU Sensor
IMU Sensor
image_proc
image_proc
Rectified Image
Rectified Image
GNSS/INS Messages
GNSS/INS MessagesText is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/index.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/index.md new file mode 100644 index 00000000000..0bce61def59 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-sensor-model/index.md @@ -0,0 +1,1080 @@ +# Creating a sensor model for Autoware + +## Introduction + +This page introduces the following packages for the sensor model: + +1. `common_sensor_launch` +2. `_sensor_kit_description` +3. `_sensor_kit_launch` + +Previously, +we forked our vehicle model at the [creating autoware repositories](../../creating-your-autoware-repositories/creating-autoware-repositories.md) page step. +For instance, +we created [tutorial_vehicle_launch](https://github.com/leo-drive/tutorial_vehicle_launch) +as an implementation example for the said step. +Please ensure that the \_vehicle_launch repository is included in Autoware, +following the directory structure below: + +```diff +/ + └─ src/ + └─ sensor_kit/ + └─ _sensor_kit_launch/ + ├─ common_sensor_launch/ + ├─ _sensor_kit_description/ + └─ _sensor_kit_launch/ +``` + +If your forked Autoware meta-repository doesn't include `_vehicle_launch` with the correct folder structure +as shown above, +please add your forked `_vehicle_launch` repository to the autoware.repos file +and run the vcs import src < autoware.repos command in your terminal +to import the newly included repositories at autoware.repos file. + +Now, we are ready to modify the following sensor model packages for our vehicle. +Firstly, we need to rename the description and launch packages: + +```diff +_sensor_kit_launch/ + ├─ common_sensor_launch/ +- ├─ sample_sensor_kit_description/ ++ ├─ _sensor_kit_description/ +- └─ sample_sensor_kit_launch/ ++ └─ _sensor_kit_launch/ +``` + +After that, +we will change our package names in the package.xml file and CMakeLists.txt file of the sample_sensor_kit_description and sample_sensor_kit_launch packages. +So, +open the package.xml file and CMakeLists.txt file with any text editor or IDE of your preference +and perform the following changes: + +Change the `` attribute at `package.xml` file: + +```diff + +- sample_sensor_kit_description ++ _sensor_kit_description + 0.1.0 + The sensor_kit_description package + ... + ... +``` + +Change the `project()` method at `CmakeList.txt` file. + +```diff + cmake_minimum_required(VERSION 3.5) +- project(sample_sensor_kit_description) ++ project(_sensor_kit_description) + + find_package(ament_cmake_auto REQUIRED) +... +... +``` + +Remember to apply the name changes and project method for **BOTH** +`_vehicle_description`and `_vehicle_launch` ROS 2 packages. +Once finished, we can proceed to build said packages: + +```bash +cd +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to _sensor_kit_description _sensor_kit_launch +``` + +## Sensor description + +The main purpose of this package is to describe the sensor frame IDs, +calibration parameters of all sensors, and their links with urdf files. + +The folder structure of sensor_kit_description package is: + +```diff +_sensor_kit_description/ + ├─ config/ + │ ├─ sensor_kit_calibration.yaml + │ └─ sensors_calibration.yaml + └─ urdf/ + ├─ sensor_kit.xacro + └─ sensors.xacro +``` + +Now, we will modify these files according to our sensor design. + +### sensor_kit_calibration.yaml + +This file defines the mounting positions and orientations of sensors with `sensor_kit_base_link` as the parent frame. +We can assume `sensor_kit_base_link` frame is bottom of your main Lidar sensor. +We must create this file with euler format as [x, y, z, roll, pitch, yaw]. +Also, we will set these values with "0" until the [calibration steps](../calibrating-sensors). + +We will define new frames for this file, and we will connect them `.xacro` files. +We recommend naming as if your lidar sensor frame as "velodyne_top", +you can add "\_base_link" to our calibration .yaml file. + +So, the sample file must be like: + +```yaml +sensor_kit_base_link: + velodyne_top_base_link: + x: 0.000000 + y: 0.000000 + z: 0.000000 + roll: 0.000000 + pitch: 0.000000 + yaw: 0.000000 + camera0/camera_link: + x: 0.000000 + y: 0.000000 + z: 0.000000 + roll: 0.000000 + pitch: 0.000000 + yaw: 0.000000 + ... + ... +``` + +This file for `tutorial_vehicle` was created for one camera, two lidars and one GNSS/INS sensors. + +??? note "`sensor_kit_calibration.yaml` for tutorial_vehicle_sensor_kit_description" + + ```yaml + sensor_kit_base_link: + camera0/camera_link: # Camera + x: 0.0 + y: 0.0 + z: 0.0 + roll: 0.0 + pitch: 0.0 + yaw: 0.0 + rs_helios_top_base_link: # Lidar + x: 0.0 + y: 0.0 + z: 0.0 + roll: 0.0 + pitch: 0.0 + yaw: 0.0 + rs_bpearl_front_base_link: # Lidar + x: 0.0 + y: 0.0 + z: 0.0 + roll: 0.0 + pitch: 0.0 + yaw: 0.0 + GNSS_INS/gnss_ins_link: # GNSS/INS + x: 0.0 + y: 0.0 + z: 0.0 + roll: 0.0 + pitch: 0.0 + yaw: 0.0 + ``` + +### sensors_calibration.yaml + +This file defines the mounting positions and orientations of `sensor_kit_base_link` (child frame) +with `base_link` as the parent frame. +At Autoware, `base_link` is on projection of the rear-axle center onto the ground surface. +For more information, +you can check [vehicle dimension](../../../../design/autoware-interfaces/components/vehicle-dimensions.md) page. +You can use CAD values for this, but we will fill the values with `0` for now. + +```yaml +base_link: + sensor_kit_base_link: + x: 0.000000 + y: 0.000000 + z: 0.000000 + roll: 0.000000 + pitch: 0.000000 + yaw: 0.000000 +``` + +Now, we are ready to implement .xacro files. +These files provide linking our sensor frames and adding sensor urdf files + +### sensor_kit.xacro + +We will add our sensors and remove unnecessary xacros from this file. +For example, +we want +to add our lidar sensor with `velodyne_top` frame from the sensor driver, +we will add the following xacro to our sensor_kit.xacro file. +Please add your sensors to this file and remove unnecessary sensor's xacros. + +```xml + + + + +``` + +Here is the sample xacro file for tutorial_vehicle with one camera, two lidars and one GNSS/INS sensors. + +??? note "`sensor_kit.xacro` for tutorial_vehicle_sensor_kit_description" + + ```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ``` + +### sensors.xacro + +This files links our sensor_kit main frame (`sensor_kit_base_link`) to base_link. +Also, you have sensors which will be calibrated directly to base_link, you can add it to here. + +Here is the sensors.xacro file for sample_sensor_kit_description package: +(velodyne_rear transformation is directly used with base_link) + +```xml + + + + + + + + + + + + + + + +``` + +At out tutorial vehicle, +there is no directly sensor transformation for base_link, +thus our sensors.xacro file includes only `base_link` and `sensor_kit_base_link` link. + +??? note "`sensors.xacro` for tutorial_vehicle_sensor_kit_description" + + ```xml + + + + + + + + + + + ``` + +After the completing `sensor_kit_calibration.yaml`, `sensors_calibration.yaml`, `sensor_kit.xacro` +and `sensors.xacro` file, our sensor description package is finished, +we will continue with modifying `_sensor_kit_launch` package. + +## Sensor launch + +At this package (`_sensor_kit_launch`), +we will launch our sensors and their pipelines. +So, we will also use `common_sensor_launch` package for launching the lidar sensing pipeline. +This image below demonstrates our sensor pipeline, which we will construct in this section. + +
+ ![sensor_launch_design](images/sensor_launch_design.svg){ align=center } +
+ Sample Launch workflow for sensing design. +
+
+ +The `_sensor_kit_launch` package folder structure like this: + +```diff +_sensor_kit_launch/ + ├─ config/ + ├─ data/ + └─ launch/ ++ ├─ camera.launch.xml ++ ├─ gnss.launch.xml ++ ├─ imu.launch.xml ++ ├─ lidar.launch.xml ++ ├─ pointcloud_preprocessor.launch.py ++ └─ sensing.launch.xml +``` + +So, +we will modify the launch files +which located the `launch` folder for launching and manipulating our sensors. +The main launch file is `sensing.launch.xml`. +This launch file launches other sensing launch files. +The current autoware sensing launch files design for `sensor_kit_launch` package is the diagram below. + +
+ ![sensing_launch_files_design](images/sensing_launch_files.svg){ align=center } +
+ Launch file flows over sensing.launch.xml launch file. +
+
+ +The `sensing.launch.xml` also launches `vehicle_velocity_converter` package +for converting `autoware_auto_vehicle_msgs::msg::VelocityReport` message to `geometry_msgs::msg::TwistWithCovarianceStamped` for gyro_odometer node. +So, +be sure +your vehicle_interface publishes `/vehicle/status/velocity_status` topic with `autoware_auto_vehicle_msgs::msg::VelocityReport` type, +or you must update `input_vehicle_velocity_topic` at `sensing.launch.xml`. + +```diff + ... + +- ++ + + + ... +``` + +### Lidar Launching + +Let's +start with modifying `lidar.launch.xml` file for launching our lidar sensor driver with autoware. +Please check supported lidar sensors over the nebula driver in the [GitHub repository](https://github.com/tier4/nebula). + +If you are using [Velodyne Lidar](https://velodynelidar.com/) sensor, +you can use the [sample_sensor_kit_launch template](https://github.com/autowarefoundation/sample_sensor_kit_launch/blob/main/sample_sensor_kit_launch/launch/lidar.launch.xml), +but you need to update `sensor_id`, `data_port`, `sensor_frame` and other necessary changes +(`max_range`, `scan_phase`, etc.). + +```diff + +- ++ + + +- ++ +- ++ + +- ++ /> + + + + + + + + + +``` + +Please add similar launch groups according to your sensor architecture. +For example, we use Robosense Lidars for our `tutorial_vehicle`, +so the lidar group for Robosense Lidar should be like this structure: + +!!! warning + + under construction + +If you are using a Hesai lidar (i.e. PandarQT64, +please check [nebula](https://github.com/tier4/nebula) driver page for supported sensors), +you can add the group like this structure at `lidar.launch.xml`: + +```xml + + + + + + + + + + + + + + + + + +``` + +You can create .launch.xml for common sensor launch, +please check [`hesai_PandarQT64.launch.xml`](https://github.com/leo-drive/tutorial_vehicle_sensor_kit_launch/blob/main/common_sensor_launch/launch/hesai_PandarQT64.launch.xml) as an example. + +The [nebula_node_container.py](https://github.com/autowarefoundation/sample_sensor_kit_launch/blob/main/common_sensor_launch/launch/nebula_node_container.launch.py) creates the Lidar pipeline for autoware, +the pointcloud preprocessing pipeline is constructed for each lidar please check [pointcloud_preprocessor](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/pointcloud_preprocessor) package for filters information as well. + +For example, If you want to change your `outlier_filter` method, +you can modify the pipeline components like this way: + +```diff + + nodes.append( + ComposableNode( + package="pointcloud_preprocessor", +- plugin="pointcloud_preprocessor::RingOutlierFilterComponent", +- name="ring_outlier_filter", ++ plugin="pointcloud_preprocessor::DualReturnOutlierFilterComponent", ++ name="dual_return_outlier_filter", + remappings=[ + ("input", "rectified/pointcloud_ex"), + ("output", "outlier_filtered/pointcloud"), + ], + extra_arguments=[{"use_intra_process_comms": LaunchConfiguration("use_intra_process")}], + ) + ) +``` + +We will use the default pointcloud_preprocessor pipeline for our tutorial_vehicle, +thus we will not modify [nebula_node_container.py](https://github.com/autowarefoundation/sample_sensor_kit_launch/blob/main/common_sensor_launch/launch/nebula_node_container.launch.py). + +### Camera Launching + +In this section, +we will launch our camera driver and 2D detection pipeline for Autoware for tutorial_vehicle. +The reason we do this is that there is a one computer for tutorial_vehicle. +If you are using two or more computers for Autoware, +you can launch the camera and 2D detection pipeline separately. +For example, +you can clone your camera driver +at `src/sensor_component/external` folder +(please don't forget adding this driver to `autoware.repos` file): + +```diff + + └─ src/ + └─ sensor_component/ + └─ external/ + └─ YOUR-CAMERA-DRIVER +``` + +After that, you can just add your camera driver at `camera.launch.xml`: + +```diff + ... ++ + ... +``` + +Then, you can launch tensorrt_yolo node via adding yolo.launch.xml on your design like that: +(i.e., +it is included in [tier4_perception_launch](https://github.com/autowarefoundation/autoware.universe/blob/ad69c2851b7b84e12c9f0c3b177fb6a9032bf284/launch/tier4_perception_launch/launch/object_recognition/detection/camera_lidar_fusion_based_detection.launch.xml#L49-L59) package in autwoare.universe) +`image_number` argument defines your camera number + +```xml + + + + + + + + + + + +``` + +Since we are using the same computer for 2D detection pipeline and all Autoware nodes, +we will design our camera and 2D detection pipeline +using [composable nodes and container](https://docs.ros.org/en/humble/How-To-Guides/Launching-composable-nodes.html) +structure. +So, it will decrease our network interface usage. +First of all, let's start with our camera sensor: +[Lucid Vision TRIO54S](https://thinklucid.com/product/triton-5-mp-imx490/). +We will use this sensor with [lucid_vision_driver](https://github.com/autowarefoundation/lucid_vision_driver) at the [autowarefoundation](https://github.com/autowarefoundation) organization. +We can clone this driver `src/sensor_component/external` folder as well. +After the cloning and the building camera driver, +we will create "camera_node_container.launch.py" +for launching camera and tensorrt_yolo node in same container. + +??? note "[`camera_node_container.launch.py`](https://github.com/leo-drive/tutorial_vehicle_sensor_kit_launch/blob/main/common_sensor_launch/launch/camera_node_container.launch.py) launch file for tutorial_vehicle" + + ```py + import launch + from launch.actions import DeclareLaunchArgument + from launch.actions import SetLaunchConfiguration + from launch.conditions import IfCondition + from launch.conditions import UnlessCondition + from launch.substitutions.launch_configuration import LaunchConfiguration + from launch_ros.actions import ComposableNodeContainer + from launch_ros.descriptions import ComposableNode + from launch_ros.substitutions import FindPackageShare + from launch.actions import OpaqueFunction + import yaml + + def launch_setup(context, *args, **kwargs): + + output_topic= LaunchConfiguration("output_topic").perform(context) + + image_name = LaunchConfiguration("input_image").perform(context) + camera_container_name = LaunchConfiguration("camera_container_name").perform(context) + camera_namespace = "/lucid_vision/" + image_name + + # tensorrt params + gpu_id = int(LaunchConfiguration("gpu_id").perform(context)) + mode = LaunchConfiguration("mode").perform(context) + calib_image_directory = FindPackageShare("tensorrt_yolo").perform(context) + "/calib_image/" + tensorrt_config_path = FindPackageShare('tensorrt_yolo').perform(context)+ "/config/" + LaunchConfiguration("yolo_type").perform(context) + ".param.yaml" + + with open(tensorrt_config_path, "r") as f: + tensorrt_yaml_param = yaml.safe_load(f)["/**"]["ros__parameters"] + + camera_param_path=FindPackageShare("lucid_vision_driver").perform(context)+"/param/"+image_name+".param.yaml" + with open(camera_param_path, "r") as f: + camera_yaml_param = yaml.safe_load(f)["/**"]["ros__parameters"] + + + container = ComposableNodeContainer( + name=camera_container_name, + namespace="/perception/object_detection", + package="rclcpp_components", + executable=LaunchConfiguration("container_executable"), + output="screen", + composable_node_descriptions=[ + ComposableNode( + package="lucid_vision_driver", + plugin="ArenaCameraNode", + name="arena_camera_node", + parameters=[{ + "camera_name": camera_yaml_param['camera_name'], + "frame_id": camera_yaml_param['frame_id'], + "pixel_format": camera_yaml_param['pixel_format'], + "serial_no": camera_yaml_param['serial_no'], + "camera_info_url": camera_yaml_param['camera_info_url'], + "fps": camera_yaml_param['fps'], + "horizontal_binning": camera_yaml_param['horizontal_binning'], + "vertical_binning": camera_yaml_param['vertical_binning'], + "use_default_device_settings": camera_yaml_param['use_default_device_settings'], + "exposure_auto": camera_yaml_param['exposure_auto'], + "exposure_target": camera_yaml_param['exposure_target'], + "gain_auto": camera_yaml_param['gain_auto'], + "gain_target": camera_yaml_param['gain_target'], + "gamma_target": camera_yaml_param['gamma_target'], + "enable_compressing": camera_yaml_param['enable_compressing'], + "enable_rectifying": camera_yaml_param['enable_rectifying'], + }], + remappings=[ + ], + extra_arguments=[ + {"use_intra_process_comms": LaunchConfiguration("use_intra_process")} + ], + ), + + ComposableNode( + namespace='/perception/object_recognition/detection', + package="tensorrt_yolo", + plugin="object_recognition::TensorrtYoloNodelet", + name="tensorrt_yolo", + parameters=[ + { + "mode": mode, + "gpu_id": gpu_id, + "onnx_file": FindPackageShare("tensorrt_yolo").perform(context) + "/data/" + LaunchConfiguration("yolo_type").perform(context) + ".onnx", + "label_file": FindPackageShare("tensorrt_yolo").perform(context) + "/data/" + LaunchConfiguration("label_file").perform(context), + "engine_file": FindPackageShare("tensorrt_yolo").perform(context) + "/data/"+ LaunchConfiguration("yolo_type").perform(context) + ".engine", + "calib_image_directory": calib_image_directory, + "calib_cache_file": FindPackageShare("tensorrt_yolo").perform(context) + "/data/" + LaunchConfiguration("yolo_type").perform(context) + ".cache", + "num_anchors": tensorrt_yaml_param['num_anchors'], + "anchors": tensorrt_yaml_param['anchors'], + "scale_x_y": tensorrt_yaml_param['scale_x_y'], + "score_threshold": tensorrt_yaml_param['score_threshold'], + "iou_thresh": tensorrt_yaml_param['iou_thresh'], + "detections_per_im": tensorrt_yaml_param['detections_per_im'], + "use_darknet_layer": tensorrt_yaml_param['use_darknet_layer'], + "ignore_thresh": tensorrt_yaml_param['ignore_thresh'], + } + ], + remappings=[ + ("in/image", camera_namespace + "/image_rect"), + ("out/objects", output_topic), + ("out/image", output_topic + "/debug/image"), + ], + extra_arguments=[ + {"use_intra_process_comms": LaunchConfiguration("use_intra_process")} + ], + ), + ], + + ) + return [container] + +def generate_launch_description(): +launch_arguments = [] + + def add_launch_arg(name: str, default_value=None, description=None): + # a default_value of None is equivalent to not passing that kwarg at all + launch_arguments.append( + DeclareLaunchArgument(name, default_value=default_value, description=description) + ) + add_launch_arg("mode","") + add_launch_arg("input_image","", description="input camera topic") + add_launch_arg("camera_container_name","") + add_launch_arg("yolo_type","", description="yolo model type") + add_launch_arg("label_file","" ,description="tensorrt node label file") + add_launch_arg("gpu_id","", description="gpu setting") + add_launch_arg("use_intra_process", "", "use intra process") + add_launch_arg("use_multithread", "", "use multithread") + + set_container_executable = SetLaunchConfiguration( + "container_executable", + "component_container", + condition=UnlessCondition(LaunchConfiguration("use_multithread")), + ) + + set_container_mt_executable = SetLaunchConfiguration( + "container_executable", + "component_container_mt", + condition=IfCondition(LaunchConfiguration("use_multithread")), + ) + + return launch.LaunchDescription( + launch_arguments + + [set_container_executable, set_container_mt_executable] + + [OpaqueFunction(function=launch_setup)] + ) + + ``` + +The important points for creating `camera_node_container.launch.py` +if you decided to use container for 2D detection pipeline are: + +- Please be careful with design, if you are using multiple cameras, the design must be adaptable for this +- The tensorrt_yolo node input expects rectified image as input, so if your sensor_driver doesn't support image rectification, you can use [`image_proc`](https://github.com/ros-perception/image_pipeline/tree/humble/image_proc) package. + - You can add something like this in your pipeline for getting rectifying image: + +```python + ... + ComposableNode( + namespace=camera_ns, + package='image_proc', + plugin='image_proc::RectifyNode', + name='rectify_camera_image_node', + # Remap subscribers and publishers + remappings=[ + ('image', camera_ns+"/image"), + ('camera_info', input_camera_info), + ('image_rect', 'image_rect') + ], + extra_arguments=[ + {"use_intra_process_comms": LaunchConfiguration("use_intra_process")} + ], + ), + ... +``` + +- Since [lucid_vision_driver](https://github.com/autowarefoundation/lucid_vision_driver) supports image_rectification, there is no need to add image_proc for tutorial_vehicle. +- Please be careful with namespace, + for example, we will use `/perception/object_detection` as tensorrt_yolo node namespace, + it will be explained in autoware usage section. + For more information, + please check [image_projection_based_fusion](https://github.com/autowarefoundation/autoware.universe/tree/main/perception/image_projection_based_fusion) package. + +After the preparing `camera_node_container.launch.py` to our forked `common_sensor_launch` package, +we need to build the package: + +```bash +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to common_sensor_launch +``` + +Next, we will add camera_node_container.launch.py to `camera.launch.xml`, +we must define necessary tensorrt_yolo parameters like this: + +```diff ++ ++ ++ + ... + ++ ++ ++ ++ ++ ++ ++ +``` + +Then, launch camera nodes with these arguments, +if you have two or more cameras, you can include it also like this: + +```diff ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ... ++ +``` + +Since there is one camera for tutorial_vehicle, the `camera.launch.xml` should be like this: + +??? note "[`camera.launch.xml`](https://github.com/leo-drive/tutorial_vehicle_sensor_kit_launch/blob/main/tutorial_vehicle_sensor_kit_launch/launch/camera.launch.xml) for tutorial_vehicle" + + ```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ``` + +You can check 2D detection pipeline with launching camera.launch.xml, +but we need to build the driver and tensorrt_yolo package first. +We will add our sensor driver to sensor_kit_launch's `package.xml` dependencies. + +```bash ++ +(optionally, if you will launch tensorrt_yolo at here) ++ tensorrt_yolo +``` + +Build necessary packages with: + +```bash +cd +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to common_sensor_launch _sensor_kit_launch +``` + +Then, you can test your camera pipeline: + +```bash +ros2 launch camera.launch.xml +# example for tutorial_vehicle: ros2 launch tutorial_vehicle_sensor_kit_launch camera.launch.xml +``` + +Then the rois topics will appear, +you can check debug image with rviz2 or [rqt](http://wiki.ros.org/rqt). + +### GNSS/INS Launching + +We will set up the GNSS/INS sensor launches at `gnss.launch.xml`. +The default GNSS sensor options at [`sample_sensor_kit_launch`](https://github.com/autowarefoundation/sample_sensor_kit_launch/blob/main/sample_sensor_kit_launch/launch/gnss.launch.xml) for [u-blox](https://www.u-blox.com/en/) +and [septentrio](https://www.septentrio.com/en) is included in `gnss.launch.xml`, +so If we use other sensors as GNSS/INS receiver, we need to add it here. +Moreover, [gnss_poser](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/gnss_poser) package launches here, +we will use this package for the pose source of our vehicle at localization initialization but remember, +your sensor_driver must provide [autoware gnss orientation message](https://github.com/autowarefoundation/autoware_msgs/blob/main/autoware_sensing_msgs/msg/GnssInsOrientationStamped.msg) for this node. +If you are ready with your GNSS/INS driver, +you must set `navsatfix_topic_name` and `orientation_topic_name` variables at this launch file for [gnss_poser](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/gnss_poser) arguments. +For Example, necessary modifications for should be like this: + +```diff + ... +- ++ + + + + + + + ++ + + + ... + ++ ++ ++ ++ + ... +- ++ + ... +``` + +Also, you can remove dependencies and unused sensor launch files at `gnss.launch.xml`. +For example, +we will use [Clap B7 sensor](https://en.unicorecomm.com/assets/upload/file/CLAP-B7_Product_Brief_En.pdf) as a GNSS/INS and IMU sensor, +and we will use [nrtip_client_ros](https://github.com/Robeff-Technology/ntrip_client) for RTK. +Also, we will add these packages to [autoware.repos](https://github.com/leo-drive/autoware.tutorial_vehicle/blob/main/autoware.repos) file. + +```diff ++ sensor_component/external/clap_b7_driver: ++ type: git ++ url: https://github.com/Robeff-Technology/clap_b7_driver.git ++ version: release/autoware ++ sensor_component/external/ntrip_client_ros : ++ type: git ++ url: https://github.com/Robeff-Technology/ntrip_client_ros.git ++ version: release/humble +``` + +So, +our `gnss.launch.xml` for tutorial vehicle should be like this file +(Clap B7 includes IMU also, so we will add imu_corrector at this file): + +??? note " [`gnss.launch.xml`](https://github.com/leo-drive/tutorial_vehicle_sensor_kit_launch/blob/main/tutorial_vehicle_sensor_kit_launch/launch/gnss.launch.xml) for tutorial_vehicle" + + ```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ``` + +### IMU Launching + +You can add your IMU sensor launch file at `imu.launch.xml` file. +At the [sample_sensor_kit](https://github.com/autowarefoundation/sample_sensor_kit_launch/blob/main/sample_sensor_kit_launch/launch/imu.launch.xml), +there is [Tamagawa IMU sensor](https://mems.tamagawa-seiki.com/en/) used as a IMU sensor. +You can add your IMU driver instead of the Tamagawa IMU driver. +Also, +we will launch [gyro_bias_estimator](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/imu_corrector#gyro_bias_estimator) and +[imu_corrector](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/imu_corrector#imu_corrector) at `imu.launch.xml` file. +Please refer these documentations for more information +(We added imu_corrector and gyro_bias_estimator at gnss.launch.xml at tutorial_vehicle, +so we will not create and use `imu.launch.xml` for tutorial_vehicle). +Please don't forget changing `imu_raw_name` argument for describing the raw imu topic. + +Here is a sample `imu.launch.xml` launch file for autoware: + +```diff + + + + + + +- +- +- +- +- +- +- +- + ++ ++ ++ ++ ++ ++ + +- ++ + + + + + + + + + + + + + + +``` + +Please make necessary modifications on this file according to your IMU driver. +Since there is no dedicated IMU sensor on tutorial_vehicle, +we will remove their launch in `sensing.launch.xml`. + +```diff +- +- +- +- +``` + +You can add or remove launch files in `sensing.launch.xml` according to your sensor architecture. diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/.pages b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/.pages new file mode 100644 index 00000000000..35fd5a113be --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/.pages @@ -0,0 +1,2 @@ +nav: + - index.md diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/images/mirror_dimensions.svg b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/images/mirror_dimensions.svg new file mode 100644 index 00000000000..271db0ad4a0 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/images/mirror_dimensions.svg @@ -0,0 +1,4 @@ + + + +
min_longitudinal_offset
min_longitudina...
max_longitudinal_offset
max_longitudina...
min_height_offset
min_height_offs...
max_lateral_offset
max_lateral_off...
base_link
base_link
max_height_offset
max_height_offs...
min_lateral_offset
min_lateral_off...
Top Down View of Vehicle
Top Down View of Vehicle
Right Side View of Vehicle
Right Side View of VehicleText is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/images/tutorial_vehicle.png b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/images/tutorial_vehicle.png new file mode 100644 index 00000000000..b76e8697987 Binary files /dev/null and b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/images/tutorial_vehicle.png differ diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/index.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/index.md new file mode 100644 index 00000000000..fdb61704846 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/creating-vehicle-model/index.md @@ -0,0 +1,277 @@ +# Creating a vehicle model for Autoware + +## Introduction + +This page introduces the following packages for the vehicle model: + +1. `_vehicle_description` +2. `_vehicle_launch` + +Previously, +we forked our vehicle model at the [creating autoware repositories](../../creating-your-autoware-repositories/creating-autoware-repositories.md) page step. +For instance, +we created [tutorial_vehicle_launch](https://github.com/leo-drive/tutorial_vehicle_launch) +as an implementation example for the said step. +Please ensure that the \_vehicle_launch repository is included in Autoware, +following the directory structure below: + +```diff +/ + └─ src/ + └─ vehicle/ + └─ _vehicle_launch/ + ├─ _vehicle_description/ + └─ _vehicle_launch/ +``` + +If your forked Autoware meta-repository doesn't include `_vehicle_launch` with the correct folder structure +as shown above, +please add your forked `_vehicle_launch` repository to the autoware.repos file +and run the vcs import src < autoware.repos command in your terminal +to import the newly included repositories at autoware.repos file. + +Now, we are ready to modify the following vehicle model packages for our vehicle. +Firstly, we need to rename the description and launch packages: + +```diff +_vehicle_launch/ +- ├─ sample_vehicle_description/ ++ ├─ _vehicle_description/ +- └─ sample_vehicle_launch/ ++ └─ _vehicle_launch/ +``` + +After that, +we will change our package names in the package.xml file and CMakeLists.txt file of the sample_vehicle_description and sample_vehicle_launch packages. +So, +open the package.xml file and CMakeLists.txt file with any text editor or IDE of your preference +and perform the following changes: + +Change the `` attribute at `package.xml` file: + +```diff + +- sample_vehicle_description ++ _vehicle_description + 0.1.0 + The vehicle_description package + ... + ... +``` + +Change the `project()` method at `CmakeList.txt` file. + +```diff + cmake_minimum_required(VERSION 3.5) +- project(sample_vehicle_description) ++ project(_vehicle_description) + + find_package(ament_cmake_auto REQUIRED) +... +... +``` + +Remember to apply the name changes and project method for **BOTH** +`_vehicle_description`and `_vehicle_launch` ROS 2 packages. +Once finished, we can proceed to build said packages: + +```bash +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to _vehicle_description _vehicle_launch +``` + +## Vehicle description + +The main purpose of this package is to describe the vehicle dimensions, +3D model of the vehicle, mirror_dimensions of the vehicle, +simulator model parameters and URDF of the vehicle. + +The folder structure of vehicle_description package is: + +```diff +_vehicle_description/ + ├─ config/ + │ ├─ mirror.param.yaml + │ ├─ simulator_model.param.yaml + │ └─ vehicle_info.param.yaml + ├─ mesh/ + │ ├─ .dae (or .fbx) + │ ├─ ... + └─ urdf/ + └─ vehicle.xacro +``` + +Now, we will modify these files according to our vehicle design. + +### mirror.param.yaml + +This file describes your vehicle mirror dimension for +[CropBox filter](https://autowarefoundation.github.io/autoware.universe/main/sensing/pointcloud_preprocessor/docs/crop-box-filter/) of [PointCloudPreprocessor](../../../../design/autoware-architecture/sensing/data-types/point-cloud.md). +This is important for cropping mirrors from your lidar's point cloud. + +The `mirror.param.yaml` consist of the following parameters: + +```yaml +/**: + ros__parameters: + min_longitudinal_offset: 0.0 + max_longitudinal_offset: 0.0 + min_lateral_offset: 0.0 + max_lateral_offset: 0.0 + min_height_offset: 0.0 + max_height_offset: 0.0 +``` + +The mirror param file should be filled with this dimension information, +please be careful with `min_lateral_offset`parameter, +it could be negative value like the mirror dimension figure below. + +
+ ![mirror_dimensions](images/mirror_dimensions.svg){ align=center } +
+ Dimension demonstration for mirror.param.yaml +
+
+ +!!! warning + + Since there is no mirror in `tutorial_vehicle`, all values set to 0.0. + If your vehicle does not have mirror, you can set these values 0.0 as well. + +### simulator_model.param.yaml + +This file is a configuration file for the [simulator environment](https://autowarefoundation.github.io/autoware.universe/main/simulator/simple_planning_simulator/). +Please update these parameters according to your vehicle specifications. +For detailed information about variables, +please check the [simple_planning_simulator](https://github.com/autowarefoundation/autoware.universe/tree/main/simulator/simple_planning_simulator) package. +The file consists of these parameters: + +```yaml +/**: + ros__parameters: + simulated_frame_id: "base_link" # center of the rear axle. + origin_frame_id: "map" + vehicle_model_type: "DELAY_STEER_ACC_GEARED" # options: IDEAL_STEER_VEL / IDEAL_STEER_ACC / IDEAL_STEER_ACC_GEARED / DELAY_STEER_ACC / DELAY_STEER_ACC_GEARED + initialize_source: "INITIAL_POSE_TOPIC" # options: ORIGIN / INITIAL_POSE_TOPIC + timer_sampling_time_ms: 25 + add_measurement_noise: False # the Gaussian noise is added to the simulated results + vel_lim: 50.0 # limit of velocity + vel_rate_lim: 7.0 # limit of acceleration + steer_lim: 1.0 # limit of steering angle + steer_rate_lim: 5.0 # limit of steering angle change rate + acc_time_delay: 0.1 # dead time for the acceleration input + acc_time_constant: 0.1 # time constant of the 1st-order acceleration dynamics + steer_time_delay: 0.24 # dead time for the steering input + steer_time_constant: 0.27 # time constant of the 1st-order steering dynamics + x_stddev: 0.0001 # x standard deviation for dummy covariance in map coordinate + y_stddev: 0.0001 # y standard deviation for dummy covariance in map coordinate +``` + +### vehicle_info.param.yaml + +This file stores the vehicle dimensions for Autoware modules. +Please update it with your vehicle information. +You can refer to the [vehicle dimensions](../../../../design/autoware-interfaces/components/vehicle-dimensions.md) page for detailed dimension demonstration. +Here is the `vehicle_info.param.yaml` for [sample_vehicle](https://github.com/autowarefoundation/sample_vehicle_launch/blob/main/sample_vehicle_description/config/vehicle_info.param.yaml): + +```yaml +/**: + ros__parameters: + wheel_radius: 0.383 # The radius of the wheel, primarily used for dead reckoning. + wheel_width: 0.235 # The lateral width of a wheel tire, primarily used for dead reckoning. + wheel_base: 2.79 # between front wheel center and rear wheel center + wheel_tread: 1.64 # between left wheel center and right wheel center + front_overhang: 1.0 # between front wheel center and vehicle front + rear_overhang: 1.1 # between rear wheel center and vehicle rear + left_overhang: 0.128 # between left wheel center and vehicle left + right_overhang: 0.128 # between right wheel center and vehicle right + vehicle_height: 2.5 + max_steer_angle: 0.70 # [rad] +``` + +Please update `vehicle_info.param.yaml` with your vehicle information. + +### 3D model of vehicle + +You can use .fbx or .dae format as a 3D model with autoware. +For the tutorial_vehicle, +we exported our 3D model as a .fbx file in the [tutorial_vehicle_launch](https://github.com/leo-drive/tutorial_vehicle_launch/tree/main/tutorial_vehicle_description/mesh) repository. +We will set the .fbx file path at `vehicle.xacro` file. + +### vehicle.xacro + +This .xacro file links the base_link of the vehicle to the 3D mesh. Therefore, we need to make some modifications in this file. + +```diff + + + +- ++ + + + + + + +- ++ + + + + +``` + +You can also modify roll, pitch, yaw, x, +y, z and scale values for the correct position and orientation of the vehicle. + +Please build vehicle_description package after the completion of your \_vehicle_description package. + +```bash +cd +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to _vehicle_description _vehicle_launch +``` + +### Launching vehicle interface + +If your vehicle interface is ready, +then you can add your vehicle_interface launch file in `vehicle_interface.launch.xml`. +Please check the [creating vehicle interface](../../creating-vehicle-interface-package/creating-a-vehicle-interface-for-an-ackermann-kinematic-model.md) page for more info. + +### Launch planning simulator with your own vehicle + +After completing the [sensor_model](../creating-sensor-model/index.md), +[individual_parameters](../creating-individual-params/index.md) +and vehicle model of your vehicle, +you are ready to launch the planning simulator with your own vehicle. +If you are not sure if every custom package in your Autoware project folder is built, +please build all packages: + +```bash +cd +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release +``` + +To launch the planning simulator, +source the install/setup.bash file in your Autoware project folder +and run this command in your terminal: + +```bash +ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/Files/autoware_map/sample-map-planning/ vehicle_model:= sensor_model:= vehicle_id:= +``` + +For example, if we try planning simulator with the tutorial_vehicle: + +```bash +ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/Files/autoware_map/sample-map-planning/ vehicle_model:=tutorial_vehicle sensor_model:=tutorial_vehicle_sensor_kit vehicle_id:=tutorial_vehicle +``` + +The planning simulator will open, and you can give an initial pose to your vehicle +using `2D Pose Estimate` button or by pressing the `P` key on your keyboard. +You can click everywhere for vehicle initialization. + +
+ ![tutorial_vehicle](images/tutorial_vehicle.png){ align=center } +
+ Our tutorial_vehicle on rviz with TF data +
+
diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/index.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/index.md new file mode 100644 index 00000000000..2ce6d8a3f75 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-model/index.md @@ -0,0 +1,62 @@ +# Creating vehicle and sensor models + +## Overview + +### Sensor Model + +- **Purpose:** The sensor model includes the calibration (transformation) and launch files of the + sensors used in the autonomous vehicle. + This includes various sensors like LiDARs, cameras, + radars, IMUs (Inertial Measurement Units), GPS units, etc. + +- **Importance:** Accurate sensor modeling is essential for perception tasks. + Precise calibration values help understand the environment by processing sensor data, + such as detecting objects, estimating distances, + and creating a 3D representation of the surroundings. + +- **Usage:** The sensor model is utilized in Autoware for launching sensors, + configuring their pipeline, and describing calibration values. + +- The sensor model (sensor kit) consists of the following three packages: + - `common_sensor_launch` + - `_sensor_kit_description` + - `_sensor_kit_launch` + +Please refer to the [creating sensor model](./creating-sensor-model) page +for creating your individual sensor model. + +For reference, +here is the folder structure for the [sample_sensor_kit_launch](https://github.com/autowarefoundation/sample_sensor_kit_launch) package in Autoware: + +```diff +sample_sensor_kit_launch/ +├─ common_sensor_launch/ +├─ sample_sensor_kit_description/ +└─ sample_sensor_kit_launch/ +``` + +### Vehicle Model + +- **Purpose:** The vehicle model includes individual vehicle specifications with dimensions, + a 3D model of the vehicle (in .fbx or .dae format), etc. + +- **Importance:** An accurate vehicle model is crucial for motion planning and control. + +- **Usage:** The vehicle model is employed in Autoware to provide vehicle information for Autoware, + including the 3D model of the vehicle. + +- The vehicle model comprises the following two packages: + - `_vehicle_description` + - `_vehicle_launch` + +Please consult the [creating vehicle model](./creating-vehicle-model) page +for creating your individual vehicle model. + +As a reference, +here is the folder structure for the [sample_vehicle_launch](https://github.com/autowarefoundation/sample_vehicle_launch) package in Autoware: + +```diff +sample_vehicle_launch/ +├─ sample_vehicle_description/ +└─ sample_vehicle_launch/ +``` diff --git a/docs/how-to-guides/integrating-autoware/creating-your-autoware-repositories/creating-autoware-repositories.md b/docs/how-to-guides/integrating-autoware/creating-your-autoware-repositories/creating-autoware-repositories.md index 46600edc8dd..d032d2c62cb 100644 --- a/docs/how-to-guides/integrating-autoware/creating-your-autoware-repositories/creating-autoware-repositories.md +++ b/docs/how-to-guides/integrating-autoware/creating-your-autoware-repositories/creating-autoware-repositories.md @@ -169,7 +169,10 @@ colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release Please refer to the following documentation links for instructions on how to create and customize each of your vehicle's packages: -- [creating-vehicle-and-sensor-description](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description) +- [Creating vehicle and sensor models](../creating-vehicle-and-sensor-model/index.md) + - [Creating sensor model](../creating-vehicle-and-sensor-model/creating-sensor-model/index.md) + - [Creating individual params](../creating-vehicle-and-sensor-model/creating-individual-params/index.md) + - [Creating vehicle model](../creating-vehicle-and-sensor-model/creating-vehicle-model/index.md) - [creating-vehicle-interface-package](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-a-vehicle-interface-for-an-ackermann-kinematic-model/) - [customizing-for-differential-drive-model](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model/)