Differential IMU

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

Description

Computes differential orientation between two IMU sensors (e.g. reference body and headset). Outputs transformed IMU data with the relative orientation removed.

Algorithm notes

How it works

This node subtracts a moving platform’s rotation from a headset’s rotation, so the output looks like the headset is being worn in a stationary room. It takes two IMU streams: one from the headset (the primary) and one mounted rigidly on the vehicle, boat or motion platform (the reference). The reference IMU’s turn rate is rotated into the headset’s own frame using the current fused orientation, then subtracted from the headset’s turn rate. Everything else in the stream - acceleration, timing, and any orientation the source already carried - passes through untouched. The result is an IMU stream you can feed into a fusion node the same way you would feed a plain sensor.

What you must configure

Wire the two IMU sources to the correct input handles. The handles are separate on purpose: the node decides which stream is which purely from the wiring, not from the sensor names. Swapping them silently inverts the correction, so check this first.

Then set Reference Orientation to describe how the reference IMU sits relative to the vehicle. If both IMUs are mounted the same way up and facing the same direction, the default is usually a good starting point. If the reference unit is rotated - upside down, sideways, or turned 90 degrees - this value has to reflect that, or the subtraction removes rotation about the wrong axes.

Finally, connect a fused pose source. The node needs to know where the headset is currently pointing in order to place the reference rotation into the headset’s frame.

How it starts

Output is produced on every primary IMU sample, immediately. There is no warm-up period. Until the first reference IMU sample and the first fused pose arrive, the node assumes the reference is not rotating and the headset is level, so the first few samples pass through essentially uncorrected. This settles as soon as both other inputs are flowing.

Tuning

There is nothing to tune numerically. Reference Orientation is a mounting description, not a gain - find the correct value once and leave it. Set Output Sender ID to something recognizable if several IMU streams reach the same downstream node and you need to tell them apart.

Troubleshooting

No output at all - the primary IMU input is not wired, or is wired to the reference handle. Only primary samples trigger output.
The view drifts the wrong way, roughly twice as fast as the vehicle turns - the two IMU inputs are swapped.
Turning the vehicle removes the wrong axis, for example a turn shows up as tilt - Reference Orientation does not match how the reference IMU is mounted.
Correction works when facing forward but fails when you look sideways - the fused pose input is missing or stale.
Small residual drift while the vehicle turns steadily - normal sensor bias in either unit; correct it upstream, not here.

Inputs / Outputs

Inputs: PrimaryImu (Imu) - Primary IMU, ReferenceImu (Imu) - Reference IMU, FusedPose
Outputs: Imu

Config aliases

DifferentialImuFilter, differentialImuFilter, differentialImu

Required feature

differential_imu_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.

Property	Type	Default	Description
Reference Orientation `referenceOrientationQuat`	quaternion	`{"w":1,"x":-1,"y":1,"z":1}`	Quaternion (w,x,y,z) rotating the reference IMU’s frame into the global frame. The reference IMU’s angular velocity is rotated by this, transformed into the headset frame, and subtracted from the headset IMU’s gyroscope so the output gyro is relative to the moving reference (e.g. a vehicle). Edit when the reference IMU is mounted at a different orientation.
Output Sender ID `outputSenderId`	string	`differentialImu`	Sender identifier stamped on the output IMU stream, used downstream to distinguish this differential IMU from other IMU sources.

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": {
    "differentialImu": {
      "dataEndpoint": "inproc://differentialImu_data",
      "inputEndpoints": [
        "inproc://primaryImu_data",
        "inproc://referenceImu_data",
        "inproc://fusedPose_data"
      ],
      "inputDataFilter": [
        "Imu",
        "Imu",
        "FusedPose"
      ],
      "settings": {}
    }
  }
}

Loading documentation…