Vehicular Fusion (Odometry-IMU)

Node ID: vehicularFusion · Role: Filter · Realtime config: no

Description

Vehicle dead-reckoning filter fusing wheel odometry (CAN bus speed) with IMU. Uses bicycle or differential drive model. Outputs 2D vehicle pose with heading, velocity, and UTM coordinates.

Algorithm notes

How it works

A planar dead-reckoning filter for wheeled vehicles. Wheel speed and the gyroscope turn rate propagate position and heading; GNSS position fixes (or, alternatively, an optical tracking system) correct the accumulated drift. One fused pose is published per wheel-speed sample. Because the motion comes from the wheels and the gyro, the filter coasts cleanly through GNSS outages. While driving it also learns the gyroscope yaw bias and a wheel-speed scale factor (tire wear and pressure).

What you must configure

• IMU-to-Car Rotation and IMU Turn Rate Axis - how the IMU is mounted and which gyro axis measures the vehicle’s turn rate. If these are wrong, the heading diverges as soon as you turn.
• A valid wheel-speed input. It paces the filter: without wheel speed there is no output.

How it starts

The filter waits for an RTK Fixed GNSS position (turn on Use GNSS Without RTK Fix to accept lower quality) and a heading. The heading comes from a dual-antenna receiver (Initialize from GNSS Orientation) or, with a single antenna, from the direction of travel once you drive straight faster than Init Velocity Threshold.

Tuning

• Measurement Error - trust in GNSS position. Lower makes the output follow the fixes tightly; higher leans on wheel/gyro dead reckoning.
• Velocity Error and Angular Velocity Error - trust in the wheel-speed and turn-rate inputs.
• Smoothing hides the small step at each GNSS fix.
• In areas with weak RTK, Weight GNSS by Fix Quality admits DGPS and float fixes with a loose weight, so drift stays bounded through long RTK gaps.
• With a dual-antenna receiver, Use GNSS Yaw Measurement keeps the heading corrected even through position outages.

Troubleshooting

• No output - no wheel-speed data, or initialization never completed (fix quality too low, or the vehicle never drove straight above the initialization speed).
• Heading runs away in turns - wrong IMU Turn Rate Axis or IMU-to-Car Rotation.
• Output stops when the IMU stream drops - intended; the filter will not dead-reckon on a stale turn rate. Wheel Turn-Rate Fallback switches to the wheel-derived turn rate instead, but enable it only if that signal is trustworthy.
• Position reacts sluggishly right after a long outage - the outlier handling de-weights the first fixes; this resolves itself within a few fixes.

Inputs / Outputs

• Inputs: Gnss, Imu, VehicleSpeed, Optical
• Outputs: FusedVehiclePose, FusedVehiclePoseV2

Config aliases

OdometryImuFilter, odometryImuFilter, vehicularFusion

Required feature

vehicular_fusion

Properties

Each row shows the setting’s label in the node’s Properties panel and, in code, its key in the node’s settings object in the config file. A setting omitted from the config file uses the default shown here.

Core Tuning

Outlier Handling

Wheel Odometry & Turn Rate

Orientation & Heading

Stopped Detection

Initialization & Convergence

RTK & GNSS Quality

IMU Mounting & Frames

Optical

Example node definition

A minimal entry in config.json looks like the block below. Paste it under the sinks key, keyed by an instance name of your choice. All settings are optional: anything not listed under settings uses the default from the Properties table above. See The configuration file for how the sections and endpoint wiring work.

{
  "sinks": {
    "vehicularFusion": {
      "dataEndpoint": "inproc://vehicularFusion_data",
      "inputEndpoints": [
        "inproc://gnss_data",
        "inproc://imu_data",
        "inproc://vehicleSpeed_data",
        "inproc://optical_data"
      ],
      "inputDataFilter": [
        "Gnss",
        "Imu",
        "VehicleSpeed",
        "Optical"
      ],
      "settings": {
        "fuser": {
          "imuToCarRotation": {
            "w": 1,
            "x": 0,
            "y": 0,
            "z": 0
          },
          "imuTurnRateAxis": {
            "x": 0,
            "y": 0,
            "z": 1
          }
        }
      }
    }
  }
}