IMU sensor#

The IMUSensor (Inertial Measurement Unit) provides accelerometer, gyroscope, and magnetometer readings for robot state estimation.

Overview#

An IMU sensor measures:

  • Linear acceleration: 3D acceleration including gravity

  • Angular velocity: 3D rotational velocity

  • Magnetic field: 3D magnetic field vector

Usage#

import genesis as gs

gs.init()
scene = gs.Scene()
robot = scene.add_entity(gs.morphs.URDF(file="quadruped.urdf"))
base = robot.get_link("base_link")

# Add IMU to robot base
imu = scene.add_sensor(
    gs.sensors.IMU(
        entity_idx=robot.idx,
        link_idx_local=base.idx_local,
        pos_offset=(0.0, 0.0, 0.15),
    )
)

scene.build()

# Simulation loop
for i in range(1000):
    scene.step()

    # Get IMU readings (IMUReturnType NamedTuple)
    data = imu.read()
    accel = data.lin_acc  # ([n_envs,] 3) acceleration in m/s^2
    gyro = data.ang_vel   # ([n_envs,] 3) angular velocity in rad/s
    mag = data.mag        # ([n_envs,] 3) magnetic field in Tesla

The options passed to gs.sensors.IMU (attachment offsets and the accelerometer, gyroscope, and magnetometer noise models) are documented in the reference below.

Output format#

read() and read_ground_truth() both return an IMUReturnType NamedTuple:

Field

Type

Shape

Description

lin_acc

torch.Tensor (float32)

([n_envs,] 3)

Linear acceleration in local sensor frame (m/s^2)

ang_vel

torch.Tensor (float32)

([n_envs,] 3)

Angular velocity in local sensor frame (rad/s)

mag

torch.Tensor (float32)

([n_envs,] 3)

Magnetic field vector in local sensor frame (Tesla)

read() applies noise, bias, random walk, and cross-axis coupling if configured. read_ground_truth() returns noiseless values.

Noise modeling#

The IMU supports realistic noise modeling based on Allan variance parameters:

Accelerometer noise#

Parameter

Description

Typical Value

acc_noise

White noise std

0.001-0.01 m/s^2

acc_random_walk

Bias drift std

0.0001-0.001 m/s^3

Gyroscope noise#

Parameter

Description

Typical Value

gyro_noise

White noise std

0.0001-0.001 rad/s

gyro_random_walk

Bias drift std

0.00001-0.0001 rad/s^2

Example: quadruped state estimation#

import genesis as gs
import numpy as np

gs.init()
scene = gs.Scene()
quadruped = scene.add_entity(gs.morphs.URDF(file="go2.urdf"))
base = quadruped.get_link("base")

# Add IMU with realistic noise
imu = scene.add_sensor(
    gs.sensors.IMU(
        entity_idx=quadruped.idx,
        link_idx_local=base.idx_local,
    )
)

scene.build()

# State estimation loop
import torch
velocity_estimate = torch.zeros(3, device=gs.device)
dt = scene.dt

for i in range(1000):
    scene.step()

    data = imu.read()

    # Simple integration (real systems use Kalman filtering)
    velocity_estimate += data.lin_acc * dt

API reference#

gs.sensors.IMU#

class genesis.options.sensors.options.IMU(*, history_length: int = 0, delay: float = 0.0, jitter: float = 0.0, draw_debug: bool = False, entity_idx: int = -1, resolution: tuple[float, ...] | float = 0.0, bias: tuple[float, ...] | float = 0.0, noise: tuple[float, ...] | float = 0.0, random_walk: tuple[float, ...] | float = 0.0, link_idx_local: int = 0, pos_offset: tuple[float, float, float] = (0.0, 0.0, 0.0), euler_offset: tuple[float, float, float] = (0.0, 0.0, 0.0), acc_resolution: tuple[float, float, float] = 0.0, acc_cross_axis_coupling: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | tuple[float, float, float] | float = 0.0, acc_noise: tuple[float, float, float] = 0.0, acc_bias: tuple[float, float, float] = 0.0, acc_random_walk: tuple[float, float, float] = 0.0, gyro_resolution: tuple[float, float, float] = 0.0, gyro_cross_axis_coupling: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | tuple[float, float, float] | float = 0.0, gyro_noise: tuple[float, float, float] = 0.0, gyro_bias: tuple[float, float, float] = 0.0, gyro_random_walk: tuple[float, float, float] = 0.0, mag_resolution: tuple[float, float, float] = 0.0, mag_cross_axis_coupling: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | tuple[float, float, float] | float = 0.0, mag_noise: tuple[float, float, float] = 0.0, mag_bias: tuple[float, float, float] = 0.0, mag_random_walk: tuple[float, float, float] = 0.0, magnetic_field: tuple[float, float, float] = (0.0, 0.0, 0.5), debug_acc_color: tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.6), debug_acc_scale: float = 0.01, debug_gyro_color: tuple[float, float, float, float] = (0.0, 1.0, 0.0, 0.6), debug_gyro_scale: float = 0.01, debug_mag_color: tuple[float, float, float, float] = (0.0, 0.0, 1.0, 0.6), debug_mag_scale: float = 0.5) → None[source]#

IMU sensor returns the linear acceleration (accelerometer) and angular velocity (gyroscope) of the associated entity link.

Parameters:

  • acc_resolution (float, optional) – The measurement resolution of the accelerometer (smallest increment of change in the sensor reading). Default is 0.0, which means no quantization is applied.

  • acc_cross_axis_coupling (float | array-like[float, float, float] | array-like with shape (3,3)) – Accelerometer axes alignment as a 3x3 rotation matrix, where diagonal elements represent alignment (0.0 to 1.0) for each axis, and off-diagonal elements account for cross-axis misalignment effects. - If a scalar is provided (float), all off-diagonal elements are set to the scalar value. - If a 3-element vector is provided (array-like[float, float, float]), off-diagonal elements are set. - If a full 3x3 matrix is provided, it is used directly.

  • acc_bias (array-like[float, float, float]) – The constant additive bias for each axis of the accelerometer.

  • acc_noise (array-like[float, float, float]) – The standard deviation of the white noise for each axis of the accelerometer.

  • acc_random_walk (array-like[float, float, float]) – The standard deviation of the random walk, which acts as accumulated bias drift.

  • gyro_resolution (float, optional) – The measurement resolution of the gyroscope (smallest increment of change in the sensor reading). Default is 0.0, which means no quantization is applied.

  • gyro_cross_axis_coupling (float | array-like[float, float, float] | array-like with shape (3,3)) – Gyroscope axes alignment as a 3x3 rotation matrix, similar to acc_cross_axis_coupling.

  • gyro_bias (array-like[float, float, float]) – The constant additive bias for each axis of the gyroscope.

  • gyro_noise (array-like[float, float, float]) – The standard deviation of the white noise for each axis of the gyroscope.

  • gyro_random_walk (array-like[float, float, float]) – The standard deviation of the bias drift for each axis of the gyroscope.

  • mag_resolution (float, optional) – The measurement resolution of the magnetometer (smallest increment of change in the sensor reading). Default is 0.0, which means no quantization is applied.

  • mag_cross_axis_coupling (float | array-like[float, float, float] | array-like with shape (3,3)) – Magnetometer axes alignment as a 3x3 rotation matrix, similar to acc_cross_axis_coupling.

  • mag_bias (array-like[float, float, float]) – The constant additive bias for each axis of the magnetometer.

  • mag_noise (array-like[float, float, float]) – The standard deviation of the white noise for each axis of the gyroscope.

  • mag_random_walk (array-like[float, float, float]) – The standard deviation of the bias drift for each axis of the magnetometer.

  • debug_acc_color (array-like[float, float, float, float], optional) – The rgba color of the debug acceleration arrow. Defaults to (1.0, 0.0, 0.0, 0.6).

  • debug_acc_scale (float, optional) – The scale factor for the debug acceleration arrow. Defaults to 0.01.

  • debug_gyro_color (array-like[float, float, float, float], optional) – The rgba color of the debug gyroscope arrow. Defaults to (0.0, 1.0, 0.0, 0.6).

  • debug_gyro_scale (float, optional) – The scale factor for the debug gyroscope arrow. Defaults to 0.01.

  • debug_mag_color (array-like[float, float, float, float], optional) – The rgba color of the debug magnetometer arrow. Defaults to (0.0, 0.0, 1.0, 0.6).

  • debug_mag_scale (float, optional) – The scale factor for the debug magnetometer arrow. Defaults to 0.01.

class genesis.engine.sensors.imu.IMUSensor(options: IMU, idx: int, shared_context, shared_metadata: IMUSharedMetadata, manager: SensorManager)[source]#

Bases: RigidSensorMixin[IMUSharedMetadata], SimpleSensor[IMU, None, IMUSharedMetadata, IMUReturnType]

set_acc_cross_axis_coupling(cross_axis_coupling: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | tuple[float, float, float] | float, envs_idx=None)[source]#
set_gyro_cross_axis_coupling(cross_axis_coupling: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | tuple[float, float, float] | float, envs_idx=None)[source]#
set_mag_cross_axis_coupling(cross_axis_coupling: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] | tuple[float, float, float] | float, envs_idx=None)[source]#
build()[source]#

Initialize all shared metadata needed to update all IMU sensors.

See also#