@mapbox/fid

fid

fid is a navigation route splicing and simulation library.

What's it do?

fid transforms navigation data into simulated navigation routes. It works with two kinds of raw data: raw Mapbox Directions API reponses and special bundles of directions responses combined with Mapbox Navigation SDK telemetry events called replay files. In both cases, it can output a second-by-second simulation of where we think a user would or did drive given the data provided.

The timestamped output can be used for generating animated playback of a navigation session, such as in Binnacle. It also can output GeoJSON for visualization purposes.

How do I use it?

npm install @mapbox/fid

then

import { simulateRoute, simulateReplay, makeGeoJSON } from '@mapbox/fid'

// Pull a replay file from S3 or some other location
S3.GetObject(..., (replayData) => {
  // Create an simulation object containing an array of timestamped `locations`, timestamped `events`, and original `route` objects
  const simulated = simulateReplay(replayData); 

  // Turn the simulation object into GeoJSON for further visualization
  const geojson = makeGeoJSON(simulated);  
});

// Get a route from the Mapbox Directions API
mapboxClient.getDirections(.. (err, response) => {
  // Create an simulation object containing an array of timestamped `locations` and timestamped `events`
  const simulated = simulateRoute(response.routes[0]);

  // Turn the simulation object into GeoJSON for further visualization
  const geojson = makeGeoJSON(simulated);
});

The resulting GeoJSON contains several LineStrings each tagged with a source property. The source is one of:

• gps - These lines are generated by copying GPS location updates directly from a replay file.
• simulation - These lines are synthetic location updates, generated by taking a simulated drive across route segments before, after, and between any GPS location data.
• combined - This line is our best guess of where the user actually drove, a combination of gps and simulation sources in one continuous line.
• route - These lines contain all suggest routes (including re-routes) that the user may have seen but may or may not have followed.

How's it work?

fid works with two main data structures internally: timestamped location updates and speed-annotated geometry.

To splice together the various geometries in a replay file, it splits the input into shorter segments, runs a driving simulator on the necessary sub-segments, and then merges the result back together with any original GPS traces. For replay files with multiple events, it runs this process iteratively, merging each new event with the output from the previous step.

Here's a diagram of the rough idea: