# cartographer/common/time.h

## Overview

`common::Time` provides a high-resolution timestamp type based on Universal Time Scale (UTS) — 100-nanosecond ticks since January 1, 1 AD (Gregorian). This is the same epoch as Windows FILETIME.

## Types

### `Duration`

```cpp
using Duration = std::chrono::duration<int64, std::ratio<1, 10000000>>;
```

100-nanosecond resolution duration (signed 64-bit).

### `Time`

```cpp
using Time = std::chrono::time_point<UniversalTimeScaleClock>;
```

Time point with UTS epoch.

### Constants

```cpp
constexpr int64 kUtsEpochOffsetFromUnixEpochInSeconds = 719162ll * 24 * 60 * 60;
// = 62,135,596,800 seconds between 1 AD and 1970-01-01
```

## Functions

### Creation

```cpp
// From seconds (double)
Duration FromSeconds(double seconds);

// From milliseconds
Duration FromMilliseconds(int64 milliseconds);

// From UTS ticks (100ns since 1 AD)
Time FromUniversal(int64 ticks);
```

### Conversion

```cpp
// To seconds (double)
double ToSeconds(Duration duration);
double ToSeconds(std::chrono::steady_clock::duration duration);

// To UTS ticks
int64 ToUniversal(Time time);
```

### Output

```cpp
std::ostream& operator<<(std::ostream& os, Time time);
// Outputs UTS tick integer
```

### Thread CPU Time

```cpp
double GetThreadCpuTimeSeconds();
// Returns CPU time consumed by current thread
```

## Usage

```cpp
// Current time (typically from sensor driver)
auto now = common::FromUniversal(ros_time_to_uts(ros::Time::now()));

// Create duration
auto timeout = common::FromSeconds(5.0);
auto period = common::FromMilliseconds(100);

// Arithmetic
auto later = now + timeout;
auto dt = later - now;
double dt_sec = common::ToSeconds(dt);

// Compare
if (time_a < time_b) { ... }

// Convert to/from ROS time
ros::Time ros_time = uts_to_ros_time(common::ToUniversal(cartographer_time));
```

## UTS Epoch Details

| Epoch | Date | Offset from Unix |
|-------|------|------------------|
| UTS | 0001-01-01 00:00:00 UTC | +62,135,596,800 seconds |
| Unix | 1970-01-01 00:00:00 UTC | 0 |

**Why UTS?**
- Integer representation (no floating-point drift)
- 100ns resolution (sufficient for all robotics sensors)
- Compatible with Windows FILETIME
- No leap second ambiguity (unlike UTC)

## Time Synchronization

Cartographer assumes all sensors provide timestamps in a **common time base**. Typical approaches:

1. **Hardware sync** — All sensors timestamped by same clock (e.g., PTP, GPS)
2. **Software sync** — Host timestamps on receipt (adds latency/jitter)
3. **ROS time** — `ros::Time::now()` at receipt, converted to UTS

```cpp
// ROS to UTS conversion
int64 RosTimeToUniversal(const ros::Time& ros_time) {
  return (ros_time.sec + kUtsEpochOffsetFromUnixEpochInSeconds) * 10000000
         + ros_time.nsec / 100;
}
```

## See Also

- [LuaParameterDictionary](lua_parameter_dictionary.md) — Configuration uses Time for durations
- [TrajectoryBuilder](../mapping/trajectory_builder_interface.md) — Uses Time for sensor data
- [PoseExtrapolator](../sensor/imu_data.md) — Uses Time for pose queries
- [TimeConversion (cartographer_ros)](../../cartographer_ros/cartographer_ros/include/cartographer_ros/time_conversion.h.md) — ROS time to UTS conversion