# cartographer/sensor/imu_data.h

## Overview

`ImuData` represents a single IMU measurement containing linear acceleration and angular velocity in the sensor frame.

## Struct: `cartographer::sensor::ImuData`

```cpp
struct ImuData {
  common::Time time;
  Eigen::Vector3d linear_acceleration;   // m/s² in sensor frame
  Eigen::Vector3d angular_velocity;      // rad/s in sensor frame
};
```

### Fields

| Field | Unit | Frame | Description |
|-------|------|-------|-------------|
| `time` | UTS | — | Measurement timestamp |
| `linear_acceleration` | m/s² | Sensor | Accelerometer reading (includes gravity) |
| `angular_velocity` | rad/s | Sensor | Gyroscope reading |

### Gravity Convention

**Linear acceleration includes gravity.** When the IMU is at rest:
- `linear_acceleration ≈ (0, 0, -9.806)` m/s² (Z-up convention)
- The pose extrapolator uses this to estimate gravity direction

## Usage

```cpp
// Create IMU data
sensor::ImuData imu_data;
imu_data.time = common::FromUniversal(timestamp);
imu_data.linear_acceleration = Eigen::Vector3d(0.1, -0.2, -9.7);
imu_data.angular_velocity = Eigen::Vector3d(0.01, 0.0, 0.02);

// Wrap and send to trajectory builder
auto dispatchable = sensor::MakeDispatchable("imu", imu_data.time, imu_data);
trajectory_builder->AddSensorData("imu", std::move(dispatchable));
```

## Integration with Pose Extrapolation

IMU data feeds the `ImuBasedPoseExtrapolator` (in `internal/imu_based_pose_extrapolator.h`):

1. **Buffering** — IMU measurements queued by timestamp
2. **Integration** — Angular velocity integrated for orientation; acceleration integrated for velocity/position
3. **Gravity Alignment** — Uses acceleration magnitude/direction to estimate gravity vector
4. **Pose Prediction** — Provides pose estimates at arbitrary timestamps for scan matching

### Configuration

From `trajectory_builder_2d.lua` / `trajectory_builder_3d.lua`:

```lua
pose_extrapolator = {
  use_imu_based = true,
  imu_based = {
    pose_queue_duration = 5.,
    gravity_constant = 9.806,
    pose_translation_weight = 1.,
    pose_rotation_weight = 1.,
    imu_acceleration_weight = 1.,
    imu_rotation_weight = 1.,
    odometry_translation_weight = 1.,
    odometry_rotation_weight = 1.,
    solver_options = { ... },
  },
}
```

## Calibration

IMU data should be calibrated:
- **Bias removal** — Accelerometer/gyro biases estimated and subtracted
- **Scale factor** — Factory calibration applied
- **Alignment** — IMU frame aligned to robot base frame

Cartographer expects calibrated data; it does not perform online IMU calibration (except optional extrinsic optimization in 3D).

## Coordinate Frames

```
IMU Sensor Frame (typically):
  X: Forward
  Y: Left
  Z: Up

Robot Base Frame:
  X: Forward
  Y: Left
  Z: Up

Transform: IMU → Base (constant, from URDF/calibration)
```

## Serialization

```proto
message ImuData {
  int64 time = 1;
  Vector3d linear_acceleration = 2;
  Vector3d angular_velocity = 3;
}
```

## See Also

- [Data](data.md) — Base sensor data class
- [TrajectoryBuilder](../mapping/trajectory_builder_interface.md) — Receives IMU data