Skip to content

Localization launch files#

Overview#

The Autoware localization stack starts with autoware.launch.xml, as the Launch Autoware page explains. If launch_localization is true, autoware.launch.xml includes component_localization.launch.xml of the autoware_launch package. This file includes the launch files of the autoware_localization_launch package in the /localization namespace. The following diagram shows the localization launch flow in the autoware_launch repository.

autoware.launch.xml includes component_localization.launch.xml. In the localization namespace, it includes the pose and twist estimators that pose_source and twist_source select, the pose estimator arbiter when several pose sources run, and always the util, pose_twist_fusion_filter, and localization_error_monitor launch files of autoware_localization_launch.autoware.launch.xmlautoware_launchcomponent_localization.launch.xmlautoware_launchpose_source: ndt (default), yabloc, eagleye, artag, lidar-marker,or several of them joined by _ (for example ndt_yabloc)twist_source: gyro_odom (default) or eagleyeParameter files: autoware_localization_configNamespace /localizationThe launch files in both groups are in autoware_localization_launch. Gray boxes are off by default.Pose and twist estimatorsndt_scan_matcher.launch.xmlIf pose_source has ndt (the default)yabloc.launch.xmlIf pose_source has yablocar_tag_based_localizer.launch.xmlIf pose_source has artaglidar_marker_localizer.launch.xmlIf pose_source has lidar-markereagleye/eagleye_rt.launch.xmlIf eagleye is a pose source or the twist sourcegyro_odometer.launch.xmlIf twist_source is gyro_odom (the default)pose_estimator_arbiter.launch.xmlautoware_pose_estimator_arbiterIf pose_source has two or more sourcesThe ndt branch can add pose_covariance_modifier.launch.xml.Always launchedutil.launch.xmlNamespace utilautoware_pose_initializerpose_initializer.launch.xmlautoware_pose_initialization_requesterif gnss_enabled is trueautoware_pointcloud_preprocessorNDT input filters, if ndt is usedpose_twist_fusion_filter.launch.xmlNamespace pose_twist_fusion_filterautoware_ekf_localizerekf_localizer.launch.xmlautoware_stop_filterstop_filter.launch.xmlautoware_twist2acceltwist2accel.launch.xmlautoware_pose_instability_detectorpose_instability_detector.launch.xmllocalization_error_monitor.launch.xmlNamespace localizationautoware_localization_error_monitorlocalization_error_monitor.launch.xmllaunch_localization:=true
component_localization.launch.xml includes the estimators that pose_source and twist_source select, and always the util, fusion filter, and error monitor launch files.

Note

The Autoware project is a large project. Therefore, as we manage the Autoware project, we utilize specific arguments in the launch files. ROS 2 offers an argument-overriding feature for these launch files. Please refer to the official ROS 2 launch documentation for further information. For instance, if we define an argument at the top-level launch, it will override the value on lower-level launches.

component_localization.launch.xml#

The component_localization.launch.xml launch file is the main localization launch file of the autoware_launch package. It selects the localization units, and it includes one launch file for each unit from the autoware_localization_launch package. There is no single localization.launch.xml file any more. The parameter files are in the autoware_localization_config package. You can change the localization launch arguments in component_localization.launch.xml.

The localization launch files support several pose estimators and twist estimators. component_localization.launch.xml has two arguments that select the estimators:

  • pose_source: This argument selects the pose estimator. The options are ndt (the default), yabloc, eagleye, artag, and lidar-marker. By default, Autoware launches ndt_scan_matcher as the pose estimator. You can use YabLoc as a camera-based localization method. For more information about YabLoc, see the YabLoc documentation. You can also use Eagleye as a localization method that uses GNSS, IMU, and wheel odometry. For more information, see the Eagleye page.

    To run several pose estimators, join their names with underscores, for example ndt_yabloc. Then Autoware also launches the pose_estimator_arbiter, which selects the active pose estimator.

    You can set the pose_source argument in component_localization.launch.xml. For example, to use Eagleye as the pose source, update component_localization.launch.xml like this:

    - <arg name="pose_source" default="ndt" description="A string consisting of ndt, yabloc, eagleye, artag and lidar-marker joined by underscores no matter the order. e.g. ndt_yabloc"/>
+ <arg name="pose_source" default="eagleye" description="A string consisting of ndt, yabloc, eagleye, artag and lidar-marker joined by underscores no matter the order. e.g. ndt_yabloc"/>

    You can also override the launch argument on the command line:

    ros2 launch autoware_launch autoware.launch.xml ... pose_source:=eagleye

  • twist_source: This argument selects the twist estimator. The options are gyro_odom (the default) and eagleye. By default, Autoware launches gyro_odometer as the twist estimator. You can also use Eagleye as the twist source. For more information, see the Eagleye page. To change the twist source to Eagleye, update component_localization.launch.xml like this:

    - <arg name="twist_source" default="gyro_odom" description="select twist_estimator. gyro_odom, eagleye"/>
+ <arg name="twist_source" default="eagleye" description="select twist_estimator. gyro_odom, eagleye"/>

    Or you can override the launch argument on the command line:

    ros2 launch autoware_launch autoware.launch.xml ... twist_source:=eagleye

  • input_pointcloud: This argument sets the input point cloud of the localization point cloud pipeline in the util launch file. If NDT is a pose source, this pipeline downsamples the point cloud for NDT. The default value is /sensing/lidar/concatenated/pointcloud, which is the output of the point cloud preprocessing pipeline of sensing. You can change this value to the topic of one LiDAR. In sample_sensor_kit_launch, each LiDAR publishes its preprocessed point cloud on /sensing/lidar/<name>/pointcloud_before_sync. For example:

    - <arg name="input_pointcloud" default="/sensing/lidar/concatenated/pointcloud" description="The topic will be used in the localization util module"/>
+ <arg name="input_pointcloud" default="/sensing/lidar/top/pointcloud_before_sync" description="The topic will be used in the localization util module"/>
  • gnss_enabled: If this argument is true (the default), the pose initializer uses the GNSS pose for the initial position estimation.

The unit launch files of autoware_localization_launch give some topics as fixed values. A launch argument does not change these topics. For example, pose_twist_estimator/gyro_odometer.launch.xml sets the input twist topic of the gyro odometer:

<arg name="input_vehicle_twist_with_covariance_topic" value="/sensing/vehicle_velocity_converter/twist_with_covariance"/>

To change this topic, change the value in your fork of autoware_launch.

Note: The vehicle velocity converter package provides the input topic of the gyro odometer. The sensor kit launches this package. For more information, see the vehicle velocity converter package.

Note when using non NDT pose estimator#

Note

NDT is the pose estimator that most users use. So the default diagnostic graph monitors the diagnostics of NDT. If you use a pose estimator other than NDT, the diagnostics of NDT do not arrive, and their state becomes stale. The diagnostic graph treats a stale state as an error. Then the localization state is an error, and Autoware cannot change to the autonomous mode.

To work around this, change the diagnostic graph. The diagnostic graph aggregator reads the graph file that the diagnostic_graph_aggregator_graph_path argument of autoware.launch.xml sets. Its default value is autoware-main.yaml, which includes localization.yaml. In localization.yaml, the /autoware/localization/scan_matching_status unit reads the scan_matching_status diagnostics of ndt_scan_matcher:

- path: /autoware/localization/scan_matching_status
  type: diag
  node: ndt_scan_matcher
  name: scan_matching_status

To prevent the error when NDT does not run, copy all files of the config/system/diagnostics directory to a new directory. autoware-main.yaml includes the other files from its own directory ($(dirname)), so keep them together. In your copy of localization.yaml, remove the link to /autoware/localization/scan_matching_status from the /autoware/localization unit. Then set diagnostic_graph_aggregator_graph_path to your copy of autoware-main.yaml. For more information about the graph files, see the diagnostic_graph_aggregator documentation.