Overview

The Extend Kalman Filter Localizer estimates robust and less noisy robot pose and twist by integrating the 2D vehicle dynamics model with input ego-pose and ego-twist messages. The algorithm is designed especially for fast-moving robots such as autonomous driving systems.

Flowchart

The overall flowchart of the autoware_ekf_localizer is described below.

Features

This package includes the following features:

• Time delay compensation for input messages, which enables proper integration of input information with varying time delays. This is important especially for high-speed moving robots, such as autonomous driving vehicles. (see the following figure).
• Automatic estimation of yaw bias prevents modeling errors caused by sensor mounting angle errors, which can improve estimation accuracy.
• Mahalanobis distance gate enables probabilistic outlier detection to determine which inputs should be used or ignored.
• Smooth update, the Kalman Filter measurement update is typically performed when a measurement is obtained, but it can cause large changes in the estimated value, especially for low-frequency measurements. Since the algorithm can consider the measurement time, the measurement data can be divided into multiple pieces and integrated smoothly while maintaining consistency (see the following figure).
• Calculation of vertical correction amount from pitch mitigates localization instability on slopes. For example, when going uphill, it behaves as if it is buried in the ground (see the left side of the “Calculate delta from pitch” figure) because EKF only considers 3DoF(x,y,yaw). Therefore, EKF corrects the z-coordinate according to the formula (see the right side of the “Calculate delta from pitch” figure).

Node

Subscribed Topics

Published Topics

Published TF

• base_link TF from map coordinate to estimated pose.

Functions

Predict

The current robot state is predicted from previously estimated data using a given prediction model. This calculation is called at a constant interval (predict_frequency [Hz]). The prediction equation is described at the end of this page.

Measurement Update

Before the update, the Mahalanobis distance is calculated between the measured input and the predicted state, the measurement update is not performed for inputs where the Mahalanobis distance exceeds the given threshold.

The predicted state is updated with the latest measured inputs, measured_pose, and measured_twist. The updates are performed with the same frequency as prediction, usually at a high frequency, in order to enable smooth state estimation.

Parameter description

The parameters are set in launch/ekf_localizer.launch .

For Node

{{ json_to_markdown(“localization/autoware_ekf_localizer/schema/sub/node.sub_schema.json”) }}

For pose measurement

{{ json_to_markdown(“localization/autoware_ekf_localizer/schema/sub/pose_measurement.sub_schema.json”) }}

For twist measurement

{{ json_to_markdown(“localization/autoware_ekf_localizer/schema/sub/twist_measurement.sub_schema.json”) }}

For process noise

{{ json_to_markdown(“localization/autoware_ekf_localizer/schema/sub/process_noise.sub_schema.json”) }}

note: process noise for positions x & y are calculated automatically from nonlinear dynamics.

Simple 1D Filter Parameters

{{ json_to_markdown(“localization/autoware_ekf_localizer/schema/sub/simple_1d_filter_parameters.sub_schema.json”) }}

File truncated at 100 lines see the full file

Changelog for package autoware_ekf_localizer

1.1.0 (2025-05-01)

1.9.0 (2026-06-24)

• Merge remote-tracking branch 'origin/main' into tmp/bot/bump_version_base

• test(autoware_ekf_localizer): add EKFModule unit tests via non-ROS seam (#1098)

  * test(autoware_ekf_localizer): add EKFModule unit tests via non-ROS seam Add a non-ROS test seam so EKFModule can be constructed in a gtest without a live rclcpp::Node:

  - HyperParameters gains an additive default constructor and its members are made settable so a test can populate them by hand. The existing node-based constructor still initializes every field unchanged.

  - Warning gains an additive no-op constructor (null node); warn and warn_throttle become null-guarded, so behavior is byte-identical when a real node is present. Add test/test_ekf_module.cpp covering the previously-untested core algorithm branches: find_closest_delay_time_index (begin/end bounds, target-beyond-last, closest-of-two), accumulate_delay_time shift and accumulation, Simple1DFilter init and update, compensate_rph_with_delay zero vs non-zero angular-velocity branches, and the safety-critical rejection paths of measurement_update_pose/twist (delay gate, NaN/Inf ignore, Mahalanobis gate), asserting both the boolean return and the EKFDiagnosticInfo flags. Also drop the unused full-covariance copy in predict_with_delay and declare x_curr as Vector6d to avoid a dynamic-to-fixed Eigen copy.

  * fix(autoware_ekf_localizer): guard empty delay-time table in find_closest_delay_time_index (#65) Reject the extend_state_step==0 degenerate by returning a safe index from the empty accumulated_delay_times_ table instead of dereferencing .back() (UB). Add a RED test for the empty-table case and pin the accept-path update postconditions via the pose/twist getters. Refs: autowarefoundation/autoware_core#1096

  * refactor(autoware_ekf_localizer): split parameter parsing from HyperParameters data (#87) Revert the unit-test-only default-value seam on HyperParameters. The struct is now plain data with no rclcpp dependency and no production-looking default member values that could silently diverge from the YAML source of truth. All declare_parameter calls are mechanically moved into a free function load_hyper_parameters(rclcpp::Node * node) that returns a fully-populated instance. Production keeps a single construction path (params_(load_hyper_parameters(this))) and params_ stays const HyperParameters, so the production instance remains immutable. The EKFModule unit test builds the struct directly by hand-setting fields, with no special default constructor. Behavior is identical: same parameter names and defaults as the YAML. Refs: autowarefoundation/autoware_core#1096

  * test(autoware_ekf_localizer): cover Warning nullptr no-op construction Add a direct Warning{nullptr} test asserting warn() and warn_throttle() are no-ops when constructed without a node, covering the warning.hpp partial branch flagged by Codecov, per review. Refs: autowarefoundation/autoware_core#1096 ---------

• Contributors: Yutaka Kondo, github-actions

1.8.0 (2026-05-01)

• Merge remote-tracking branch 'origin/main' into tmp/bot/bump_version_base

• fix(ekf_localizer): initialize diagnostics information before publishing them (#680)

  * fix: initialize diagnostics information before publishing them

  • chore: add comments and remove unnecessary code
  • test: reset measurement diag fields on timer early return
  • style(pre-commit): autofix

  * test(ekf_localizer): stabilize diagnostics period gtest timing ---------Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Junya Sasaki <<j2sasaki1990@gmail.com>>

• fix(ekf_localizer): ekf localizer diagnostics name (#1028)

  • test: add diagnostics topic test and log message names
  • fix: diagnostic task names and timer-driven publish
  • feat: mirror diagnostics on diagnostics_manual alongside updater
  • refactor: drop diagnostic_updater; publish /diagnostics manually

File truncated at 100 lines see the full file