# How Different Long-Trip Compression Presets Control Animation Speed in Google Timeline Visualizer

> Discover how long trip compression presets in google-timeline-visualizer control animation speed by adjusting time across trip segments. Optimize your visualizations now.

- Repository: [mahlernim/google-timeline-visualizer](https://github.com/mahlernim/google-timeline-visualizer)
- Tags: internals
- Published: 2026-08-22

---

**The `--long-trip-compression` option in google-timeline-visualizer applies mathematical exponents (`1.00`, `0.92`, `0.85`, or `0.75`) to redistribute animation time across trip segments, reducing the visual dominance of long legs while preserving total duration.**

The **google-timeline-visualizer** repository enables fine-grained control over timeline animations through configurable **long-trip compression presets**. When visualizing extensive travel logs where short city segments coexist with lengthy highway stretches, these presets prevent brief legs from becoming imperceptibly short while maintaining geographic accuracy.

## How Long-Trip Compression Presets Modify Distance Weighting

Each preset determines an exponent value that skews the mapping from animation progress (0.0 to 1.0) to the raw cumulative distance of the trip.

In [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py), the `COMPRESSION_EXPONENTS` dictionary associates preset names with specific power values. When `build_journey_timing()` processes your route, it raises each segment distance to the selected exponent using the operation `segment ** exponent`. Because fractional exponents (values < 1.0) compress larger numbers more aggressively than smaller ones, longer segments contribute proportionally less to the effective total distance.

The implementation then scales these weighted values back to the true total kilometers, ensuring that `total_km * progress` remains mathematically accurate. This preserves the overall animation duration while altering the velocity profile across individual waypoints.

## Available Long-Trip Compression Presets

The tool provides four distinct options defined in `COMPRESSION_EXPONENTS`:

- **`off`** (`1.00`): Disables compression entirely. Progress maps linearly to distance, causing the animation speed to follow raw segment lengths without modification.
- **`gentle`** (`0.92`): Applies slight compression to reduce the visual weight of long segments, creating a subtly more even travel appearance.
- **`balanced`** (`0.85`): The default preset. Provides moderate compression that noticeably reduces the dominance of long segments while maintaining sufficient speed variation.
- **`strong`** (`0.75`): Aggressively compresses long segments to flatten dramatic speed spikes, ideal for journeys with extreme length disparities.

### Fallback Behavior for Edge Cases

The source code guards against degenerate configurations. If you specify `compression == 'off'` or provide fewer than two waypoints, `build_journey_timing` falls back to a simple linear mapper, bypassing the exponential calculation entirely (lines 18-21 in [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py)).

## Source Code Implementation

The core algorithm resides in **`build_journey_timing`** inside [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) (lines 15-34). This function constructs a cumulative distance array from your waypoints, applies the selected exponent to transform the timing curve, and returns an interpolation function.

The procedure follows three steps:

1. **Distance Calculation**: Computes raw cumulative distances from input coordinates.
2. **Exponent Application**: Raises each segment length to the power of the selected preset value.
3. **Normalization**: Scales compressed values to create timing keyframes that preserve the true total distance.

According to the test `test_balanced_compression_reduces_long_segments_share_without_changing_duration` in [`tests/test_camera.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/tests/test_camera.py) (lines 27-34), this implementation correctly reduces the proportional share of long segments without altering the overall animation length.

## Practical Usage Examples

Specify **long-trip compression presets** via command-line arguments or direct Python API calls.

**Command-Line Interface:**

```bash

# Use the default balanced compression

python visualizer.py --long-trip-compression balanced my_takeout.json

# Apply gentle smoothing for moderately long trips

python visualizer.py --long-trip-compression gentle my_takeout.json

# Disable compression for accurate speed representation

python visualizer.py --long-trip-compression off my_takeout.json

# Use strong compression for extremely long journeys

python visualizer.py --long-trip-compression strong my_takeout.json

```

**Python API:**

```python
from visualizer import build_journey_timing

# Cumulative distances in kilometers at each waypoint

cumulative_distances = [0, 10, 30, 90]

# Create a mapper with strong compression

mapper = build_journey_timing(
    cumulative_distances, 
    compression='strong'
)

# Get the distance at 50% animation progress

distance_at_midpoint = mapper(0.5)
print(f"Distance at 50% animation: {distance_at_midpoint} km")

```

## Summary

- **Long-trip compression presets** control animation velocity by applying exponents (`0.75` to `1.00`) to segment distances in [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py).
- The **`balanced`** preset (`0.85`) serves as the default, offering moderate compression for typical visualization workflows.
- **`build_journey_timing`** implements the core logic, raising segments to the selected exponent while preserving total trip duration through normalization.
- Tests in [`tests/test_camera.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/tests/test_camera.py) validate that compression alters segment weighting without affecting overall animation length.
- Choose **`off`** for linear speed accuracy, **`gentle`** for subtle smoothing, or **`strong`** to suppress extreme speed variations in very long trips.

## Frequently Asked Questions

### What happens when I set long-trip compression to "off"?

Setting the preset to `off` applies an exponent of `1.00`, which disables all compression algorithms. The animation progress maps linearly to cumulative distance, meaning the camera spends time proportional to each segment's actual length. Short segments may appear too brief to observe, while long legs dominate the timeline.

### Does compression change the total duration of the animation?

No. The `build_journey_timing` function scales the compressed distance values back to the true total distance, ensuring that 100% animation progress always corresponds to the full trip length. The redistribution only affects how quickly the animation moves through specific segments, not the overall playback time.

### Which preset should I use for a road trip with varying leg lengths?

For trips containing both short city segments and long highway stretches, the **`balanced`** preset (`0.85`) provides optimal viewing. This default setting noticeably reduces the visual dominance of long highway legs while maintaining enough speed variation to distinguish between different types of travel. If long segments still overwhelm short ones, switch to **`strong`** (`0.75`).

### Where in the codebase are the compression exponents defined?

The exponents reside in the `COMPRESSION_EXPONENTS` dictionary at the top of [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py). The `build_journey_timing` function references this mapping to convert string preset names into mathematical exponents, applying them via the operation `segment ** exponent` during timing calculations.