How the Google Timeline Visualizer Handles International Flights with Great-Circle Interpolation

The visualizer renders international flights by projecting coordinates to Web-Mercator space, detecting polar corridors above 70° latitude, and applying spherical linear interpolation (slerp) to 3D vectors to calculate true great-circle arcs that prevent antimeridian wrap-around artifacts.

The mahlernim/google-timeline-visualizer repository transforms raw Google Timeline JSON into rendered travel routes on a Mercator-projected canvas. While short domestic trips render correctly with simple linear interpolation, international flights—particularly those crossing the antimeridian or traversing polar regions—require sophisticated great-circle interpolation to display geographically accurate paths without visual distortions.

Projecting Coordinates to Normalized World Space

The pipeline begins in web/src/geo.ts with the project() function (see lines 3-9). This utility clamps latitude values to Web-Mercator limits and maps longitude/latitude pairs to normalized [0, 1] × [0, 1] world coordinates. By establishing this baseline projection, the system ensures all subsequent geometric calculations operate within a consistent, bounded coordinate space.

Unwrapping World Points to Eliminate Antimeridian Jumps

Next, the unwrapWorldPoints() function (see geo.ts lines 12-22) processes the sequence of projected points. It adjusts consecutive x values so that no single step exceeds ½ world-width, effectively selecting the correct map copy when a path crosses the antimeridian at ±180°. This prevents the "wrap-around" artifact where a flight from Los Angeles to Tokyo would incorrectly streak backwards across the entire map width instead of crossing the Pacific.

Detecting Polar Flight Corridors

For long-haul routes passing near the poles, the unwrapJourneyPoints() function scans for point clusters exceeding 70° latitude (POLAR_CORE_LATITUDE). In these polar corridors, longitude changes rapidly, and naive unwrapping would fabricate extra full-world turns. The algorithm identifies these high-latitude segments to trigger specialized great-circle calculations rather than Mercator linear interpolation, ensuring the path follows the true shortest route over the Earth’s curvature.

Computing Great-Circle References via Spherical Interpolation

When processing polar or trans-oceanic corridors, the visualizer invokes greatCircleReferenceX() (see geo.ts lines 32-58). This function performs the following steps:

1. Vector Conversion: Converts start and end geographic coordinates to 3D unit vectors using the toVector helper.
2. Angular Distance Calculation: Determines the central angle between the two vectors.
3. Spherical Linear Interpolation (slerp): Interpolates along the great-circle path using the angular distance ratio.
4. Coordinate Projection: Converts the interpolated 3D vector back to a normalized x coordinate in world space.

This process replaces the corridor’s linear x values with mathematically accurate great-circle longitudes, ensuring the flight path reflects the true shortest path over the Earth's surface rather than a straight line in Mercator projection.

Applying Branch Correction for Continuous Paths

After computing great-circle references, the algorithm validates continuity. If the computed end x differs from the projected end coordinate by more than 0.5 world-width, the system applies branch correction—shifting all subsequent points in the journey to maintain the flight on the same logical map copy. This step ensures that flights crossing the antimeridian render as single continuous lines rather than broken segments.

Generating Render-Ready Route Segments

Finally, overviewRouteSegments() (see geo.ts lines 10-44) consumes the unwrapped point sequence to detect actual world-copy crossings. It splits the route into discrete segments wherever the path legitimately wraps around the globe, producing separate line segments that the canvas renderer can draw without artificial interpolation across map boundaries. This guarantees the final visualization displays a smooth, accurate great-circle arc regardless of the flight’s origin, destination, or polar traversal.

Practical Implementation Example

The following TypeScript demonstrates how a two-point international flight is transformed into renderable segments:

import { unwrapJourneyPoints, overviewRouteSegments } from "./geo";
import type { GeoPoint } from "./types";

/* Example: a flight from Los Angeles (LAX) to Tokyo (NRT) */
const flight: GeoPoint[] = [
  { latitude: 33.9416, longitude: -118.4085, instant: new Date("2023-03-10T10:00:00Z") },
  { latitude: 35.6895, longitude: 139.6917, instant: new Date("2023-03-10T22:00:00Z") },
];

/* 1️⃣ Project and unwrap the journey (great-circle is applied automatically) */
const worldPoints = unwrapJourneyPoints(flight);

/* 2️⃣ Split into renderable segments (handles antimeridian crossing) */
const segments = overviewRouteSegments(worldPoints);

/* `segments` can now be fed to the canvas renderer */
console.log(segments);

This snippet leverages the geometry utilities in web/src/geo.ts to automatically handle the great-circle calculation and antimeridian splitting for the transpacific route.

Summary

• Mercator Projection: The project() function normalizes all coordinates to [0, 1] × [0, 1] world space to establish a consistent rendering baseline.
• Antimeridian Handling: unwrapWorldPoints() prevents wrap-around artifacts by ensuring longitude jumps never exceed ½ world-width.
• Polar Detection: Flights exceeding 70° latitude trigger specialized processing via unwrapJourneyPoints() to handle rapid longitude changes.
• Great-Circle Math: greatCircleReferenceX() uses 3D vector slerp to calculate true shortest-path arcs rather than straight-line Mercator interpolations.
• Segmentation: overviewRouteSegments() produces canvas-ready line segments that respect world-copy boundaries for artifact-free rendering.

Frequently Asked Questions

What is great-circle interpolation and why does it matter for flight visualization?

Great-circle interpolation calculates the shortest path between two points on a sphere’s surface. For international flights, this matters because a straight line on a Mercator map does not represent the true shortest route—flights from North America to Asia actually arc over Alaska or the Arctic. Without great-circle calculations, visualizers display inefficient, misleading routes that cross excessive longitude lines.

How does the visualizer detect when a flight crosses the antimeridian?

The system uses unwrapWorldPoints() to monitor the delta between consecutive longitude values in normalized world coordinates. When a coordinate jump exceeds 0.5 world-width, the algorithm adjusts the sequence by adding or subtracting full world-width units to keep the path continuous on the same map copy. This logic runs automatically for all journey sequences before rendering.

Why are polar flights handled differently from standard international routes?

Polar flights encounter mathematical singularities where longitude lines converge. Above 70° latitude (POLAR_CORE_LATITUDE), small movements create large longitude changes that standard unwrapping misinterprets as antimeridian crossings. The visualizer detects these clusters and applies 3D vector spherical interpolation (slerp) via greatCircleReferenceX() to calculate accurate positions without Mercator distortion.

Which source files contain the core flight path calculations?

According to the mahlernim/google-timeline-visualizer source code, the primary geometric logic resides in web/src/geo.ts, which exports unwrapJourneyPoints(), greatCircleReferenceX(), and overviewRouteSegments(). The web/src/timeline.ts file parses raw Timeline JSON into GeoPoint arrays, while web/src/renderer.ts consumes the processed segments to draw the final canvas output.

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