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

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, 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).

Source Code Implementation

The core algorithm resides in build_journey_timing inside 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 (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:

# 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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}