From 7f2a2a6fc1662cda0a32a9192a9ac1dbacaac7e9 Mon Sep 17 00:00:00 2001 From: kminoda Date: Wed, 12 Jul 2023 21:07:11 +0900 Subject: [PATCH 1/5] feat: change localization methods section Signed-off-by: kminoda --- .../launch-autoware/.pages | 2 +- .../.pages | 0 .../eagleye-guide.md | 0 .../eagleye_pose_twist.drawio.svg | 0 .../eagleye_twist.drawio.svg | 0 .../localization-methods/index.md | 63 +++++++++ .../localization-mode/index.md | 129 ------------------ 7 files changed, 64 insertions(+), 130 deletions(-) rename docs/how-to-guides/integrating-autoware/launch-autoware/{localization-mode => localization-methods}/.pages (100%) rename docs/how-to-guides/integrating-autoware/launch-autoware/{localization-mode => localization-methods}/eagleye-guide.md (100%) rename docs/how-to-guides/integrating-autoware/launch-autoware/{localization-mode => localization-methods}/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg (100%) rename docs/how-to-guides/integrating-autoware/launch-autoware/{localization-mode => localization-methods}/images/eagleye-integration-guide/eagleye_twist.drawio.svg (100%) create mode 100644 docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md delete mode 100644 docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/index.md diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/.pages b/docs/how-to-guides/integrating-autoware/launch-autoware/.pages index 25f992ebd0d..f3708e7a449 100644 --- a/docs/how-to-guides/integrating-autoware/launch-autoware/.pages +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/.pages @@ -1,4 +1,4 @@ nav: - index.md - - Localization mode: localization-mode + - Localization methods: localization-methods - Perception mode: perception.md diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/.pages b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/.pages similarity index 100% rename from docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/.pages rename to docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/.pages diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/eagleye-guide.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/eagleye-guide.md similarity index 100% rename from docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/eagleye-guide.md rename to docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/eagleye-guide.md diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg similarity index 100% rename from docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg rename to docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/images/eagleye-integration-guide/eagleye_twist.drawio.svg b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_twist.drawio.svg similarity index 100% rename from docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/images/eagleye-integration-guide/eagleye_twist.drawio.svg rename to docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/images/eagleye-integration-guide/eagleye_twist.drawio.svg diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md new file mode 100644 index 00000000000..a7522912c68 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md @@ -0,0 +1,63 @@ +# Localization methods + +Current localization launcher implemented by TIER IV supports multiple localization methods, both pose estimators and twist estimators. +`tier4_localization_component.launch.xml` has two arguments to select which estimators to launch: + +- `pose_source` : an argument to select pose_estimator, currently supporting `ndt` (default), `yabloc`, and `eagleye` +- `twist_source` : an argument to select twist_estimator, currently supporting `gyro_odom` (default), and `eagleye` + +## NDT scan matcher: a LiDAR and pointcloud map based pose estimator (default) + +By default, Autoware launches [ndt_scan_matcher](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/ndt_scan_matcher) for pose estimator. +In order to launch this explicitely, you need to specify as follows: +```bash +$ ros2 launch autoware_launch autoware.launch.xml ... pose_source:=ndt ... +``` +Note that currently `pose_source` is set to NDT as default, so you can skip this argument. + + +## Gyro Odometer: an IMU & wheel odometry based twist estimator (default) +By default, Autoware launches [gyro_odometer](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/gyro_odometer) for twist estimator. +In order to launch this explicitely, you need to specify as follows: + +```bash +ros2 launch autoware_launch autoware.launch.xml ... twist_source:=gyro_odom ... +``` +Note that currently `twist_source` is set to Gyro Odometer as default, so you can skip this argument. + + +## YabLoc: a camera and vector map based pose estimator + +You can use YabLoc as a camera-based localization method. +For more details on YabLoc, please refer to the [README of YabLoc](https://github.com/autowarefoundation/autoware.universe/blob/main/localization/yabloc/README.md) in autoware.universe. + +To use YabLoc as a pose_estimator, add `localization_mode:=camera` when launching Autoware. +By default, the `localization_mode` is set to `lidar`. +By specifying this command-line argument, YabLoc nodes will be automatically launched while the NDT nodes will not be started. + +Here is an example of a launch command: + +```bash +ros2 launch autoware_launch autoware.launch.xml ... pose_source:=yabloc ... +``` + +## Eagleye: a GNSS & IMU & wheel odometry based pose and twist estimator + +You can use Eagleye as a GNSS & IMU & wheel odometry-based localization method. For more details on Eagleye, please refer to the [Eagleye](eagleye-guide.md). + +Eagleye has a function for position estimation and twist estimation, namely `pose_estimator` and `twist_estimator`, respectively. +When running Eagleye in twist_estimator mode with other pose_estimator such as ndt_scan_matcher, Eagleye is still helpful since it can improve scan matching by providing accurate twists using GNSS doppler. + +You can use Eagleye by specifying the `pose_source` and `twist_source` accordingly through command-line arguments. + +**Example of using Eagleye as the pose twist estimator:** + +```bash +ros2 launch autoware_launch autoware.launch.xml ... pose_source:=eagleye twist_source:=eagleye ... +``` + +**Example of using Eagleye as the twist estimator:** + +```bash +ros2 launch autoware_launch autoware.launch.xml ... twist_source:=eagleye ... +``` diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/index.md deleted file mode 100644 index 4846b766ffe..00000000000 --- a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-mode/index.md +++ /dev/null @@ -1,129 +0,0 @@ -# Localization mode - -The Autoware provides multiple localization methods that work with multiple different sensor configurations. -The table below shows the supported sensor configurations and their corresponding algorithms. - -| localization mode | algorithm | map type | -| ----------------- | --------- | --------------- | -| LiDAR-based | NDT | point cloud map | -| Camera-based | YabLoc | vector map | -| GNSS/IMU-based | Eagleye | - | - -## LiDAR-based localizer (default) - -By default, Autoware launches [ndt_scan_matcher](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/ndt_scan_matcher) for localization. - -## Camera-based localizer - -You can use YabLoc as a camera-based localization method. -For more details on YabLoc, please refer to the [README of YabLoc](https://github.com/autowarefoundation/autoware.universe/blob/main/localization/yabloc/README.md) in autoware.universe. - -To use YabLoc as a pose_estimator, add `localization_mode:=camera` when launching Autoware. -By default, the `localization_mode` is set to `lidar`. -By specifying this command-line argument, YabLoc nodes will be automatically launched while the NDT nodes will not be started. - -Here is an example of a launch command: - -```bash -ros2 launch autoware_launch autoware.launch.xml \ - vehicle_model:=YOUR_VEHICLE \ - sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ - localization_mode:=camera # Add this argument -``` - -## GNSS/IMU-based localizer - -You can use Eagleye as a GNSS/IMU-based localization method. For more details on Eagleye, please refer to the [Eagleye](eagleye-guide.md). - -Eagleye has a function for position estimation and twist estimation, namely `pose_estimator` and `twist_estimator`, respectively. -When running Eagleye in twist_estimator mode, ndt_scan_matcher is used as the pose_estimator. -Eagleye will improve scan matching by providing accurate twists using GNSS doppler. - -To use Eagleye, it requires both specifying the command-line arguments and modifying the launch file. - -Firstly, please modify the commented-out line and change it to launch `map4_localization_component.launch.xml` instead of `tier4_localization_component.launch.xml` in [`autoware.launch.xml`](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/launch/autoware.launch.xml). -Please refer to the following snippet for the modification details: - -```xml - - - - - -``` - -NOTE: Please refer to [`map4_localization_launch`](https://github.com/autowarefoundation/autoware.universe/tree/main/launch/map4_localization_launch) in the `autoware.universe` package and [`map4_localization_component.launch.xml`](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/launch/components/map4_localization_component.launch.xml) in `autoware_launch` package for information on how to modify the localization launch. - -Once you have modified the launch file, you can use Eagleye by specifying the `pose_estimator_mode` through command-line arguments. - -**Example of using Eagleye as the pose twist estimator:** - -```bash -ros2 launch autoware_launch autoware.launch.xml \ - vehicle_model:=YOUR_VEHICLE \ - sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ - pose_estimator_mode:=gnss # Add this argument -``` - -**Example of using Eagleye as the twist estimator:** - -```bash -ros2 launch autoware_launch autoware.launch.xml \ - vehicle_model:=YOUR_VEHICLE \ - sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP \ - pose_estimator_mode:=lidar # Not mandatory, as it is the default. -``` - -## Comprehensive Options Table - -The table below indicates which pose_estimator and twist_estimator are called based on the invoked launch file and provided arguments. - - - - - - - - - - - - - - - - - - - - - - - - -
tier4_localization_component.launch.xml
localization_modepose_estimatortwist_estimator
lidar (default)ndt_scan_matchergyro_odometer
camerayablocgyro_odometer
- - - - - - - - - - - - - - - - - - - - - - - - -
map4_localization_component.launch.xml
pose_estimator_modepose_estimatortwist_estimator
lidar (default)ndt_scan_matchereagleye
gnsseagleyeeagleye
From b36e64bc4a8a19b8ad531e9fb9cf7d4ccfc03ed2 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 12 Jul 2023 12:08:39 +0000 Subject: [PATCH 2/5] style(pre-commit): autofix --- .../launch-autoware/localization-methods/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md index a7522912c68..8ef15ba36dd 100644 --- a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md @@ -3,28 +3,30 @@ Current localization launcher implemented by TIER IV supports multiple localization methods, both pose estimators and twist estimators. `tier4_localization_component.launch.xml` has two arguments to select which estimators to launch: -- `pose_source` : an argument to select pose_estimator, currently supporting `ndt` (default), `yabloc`, and `eagleye` -- `twist_source` : an argument to select twist_estimator, currently supporting `gyro_odom` (default), and `eagleye` +- `pose_source` : an argument to select pose_estimator, currently supporting `ndt` (default), `yabloc`, and `eagleye` +- `twist_source` : an argument to select twist_estimator, currently supporting `gyro_odom` (default), and `eagleye` ## NDT scan matcher: a LiDAR and pointcloud map based pose estimator (default) By default, Autoware launches [ndt_scan_matcher](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/ndt_scan_matcher) for pose estimator. In order to launch this explicitely, you need to specify as follows: + ```bash -$ ros2 launch autoware_launch autoware.launch.xml ... pose_source:=ndt ... +ros2 launch autoware_launch autoware.launch.xml ... pose_source:=ndt ... ``` -Note that currently `pose_source` is set to NDT as default, so you can skip this argument. +Note that currently `pose_source` is set to NDT as default, so you can skip this argument. ## Gyro Odometer: an IMU & wheel odometry based twist estimator (default) + By default, Autoware launches [gyro_odometer](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/gyro_odometer) for twist estimator. In order to launch this explicitely, you need to specify as follows: ```bash ros2 launch autoware_launch autoware.launch.xml ... twist_source:=gyro_odom ... ``` -Note that currently `twist_source` is set to Gyro Odometer as default, so you can skip this argument. +Note that currently `twist_source` is set to Gyro Odometer as default, so you can skip this argument. ## YabLoc: a camera and vector map based pose estimator From d3b44ef0a83db18e76dcc071920bb6d19fb23d7a Mon Sep 17 00:00:00 2001 From: kminoda Date: Wed, 12 Jul 2023 21:10:36 +0900 Subject: [PATCH 3/5] fix typo Signed-off-by: kminoda --- .../launch-autoware/localization-methods/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md index 8ef15ba36dd..0682c38a65d 100644 --- a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md @@ -9,7 +9,7 @@ Current localization launcher implemented by TIER IV supports multiple localizat ## NDT scan matcher: a LiDAR and pointcloud map based pose estimator (default) By default, Autoware launches [ndt_scan_matcher](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/ndt_scan_matcher) for pose estimator. -In order to launch this explicitely, you need to specify as follows: +In order to launch this explicitly, you need to specify as follows: ```bash ros2 launch autoware_launch autoware.launch.xml ... pose_source:=ndt ... @@ -20,7 +20,7 @@ Note that currently `pose_source` is set to NDT as default, so you can skip this ## Gyro Odometer: an IMU & wheel odometry based twist estimator (default) By default, Autoware launches [gyro_odometer](https://github.com/autowarefoundation/autoware.universe/tree/main/localization/gyro_odometer) for twist estimator. -In order to launch this explicitely, you need to specify as follows: +In order to launch this explicitly, you need to specify as follows: ```bash ros2 launch autoware_launch autoware.launch.xml ... twist_source:=gyro_odom ... From 2eade2d0cc5aed5d036a6adf17aed3891836b515 Mon Sep 17 00:00:00 2001 From: kminoda Date: Thu, 13 Jul 2023 13:43:29 +0900 Subject: [PATCH 4/5] minor fix Signed-off-by: kminoda --- .../integrating-autoware/launch-autoware/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/index.md index 3195fb2bc3d..1877a2cc39f 100644 --- a/docs/how-to-guides/integrating-autoware/launch-autoware/index.md +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/index.md @@ -31,12 +31,12 @@ ros2 launch autoware_launch autoware.launch.xml vehicle_model:=YOUR_VEHICLE sens The basic command-line options are documented in [autoware.launch.xml](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/launch/autoware.launch.xml). There are options available to switch between different methods for some component. -For example, by specifying `localization_mode` or `perception_mode`, you can switch localization and perception methods, respectively. +For example, by specifying `pose_source`/`twist_source` or `perception_mode`, you can switch localization and perception methods, respectively. These options allow you to choose the desired algorithms or sensor configurations for the respective functionalities. For options on eagleye component, please refer to the sub-pages. -- [localization-mode](localization-mode/index.md) +- [localization-mode](localization-methods/index.md) - [perception-mode](perception.md) ## Set initial pose From cece86e6103816a63297d65d8845055a98526a08 Mon Sep 17 00:00:00 2001 From: kminoda <44218668+kminoda@users.noreply.github.com> Date: Thu, 13 Jul 2023 16:31:22 +0900 Subject: [PATCH 5/5] Update docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md Co-authored-by: Kento Yabuuchi --- .../launch-autoware/localization-methods/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md index 0682c38a65d..c508d7cb589 100644 --- a/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md +++ b/docs/how-to-guides/integrating-autoware/launch-autoware/localization-methods/index.md @@ -33,8 +33,8 @@ Note that currently `twist_source` is set to Gyro Odometer as default, so you ca You can use YabLoc as a camera-based localization method. For more details on YabLoc, please refer to the [README of YabLoc](https://github.com/autowarefoundation/autoware.universe/blob/main/localization/yabloc/README.md) in autoware.universe. -To use YabLoc as a pose_estimator, add `localization_mode:=camera` when launching Autoware. -By default, the `localization_mode` is set to `lidar`. +To use YabLoc as a pose_estimator, add `pose_source:=yabloc` when launching Autoware. +By default, the `pose_source` is set to `ndt`. By specifying this command-line argument, YabLoc nodes will be automatically launched while the NDT nodes will not be started. Here is an example of a launch command: