# @mapbox/fid

> fid is a navigation route splicing and simulation library

Latest version **0.1.6** (published 2021-05-27) · ISC license · 0 weekly downloads

## Install

```sh
npm install @mapbox/fid
pnpm add @mapbox/fid
yarn add @mapbox/fid
bun add @mapbox/fid
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.6 |
| Published | 2021-05-27 |
| First published | 2017-11-08 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 9 |
| Unpacked size | 2.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Sam Kronick |
| Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user |

## Links

- npm: https://www.npmjs.com/package/@mapbox/fid
- Repository: https://github.com/mapbox/fid
- Homepage: https://github.com/mapbox/fid#readme
- Issues: https://github.com/mapbox/fid/issues
- npm.io page: https://npm.io/package/@mapbox/fid

## Dependencies (9)

- [clone-deep](https://npm.io/package/clone-deep.md) ^1.0.0
- [deep-equal](https://npm.io/package/deep-equal.md) ^1.0.1
- [@turf/along](https://npm.io/package/@turf/along.md) 4.7.3
- [@turf/bearing](https://npm.io/package/@turf/bearing.md) 4.7.3
- [@turf/helpers](https://npm.io/package/@turf/helpers.md) 4.7.3
- [@turf/distance](https://npm.io/package/@turf/distance.md) 4.7.3
- [@mapbox/polyline](https://npm.io/package/@mapbox/polyline.md) ^0.2.0
- [@turf/line-distance](https://npm.io/package/@turf/line-distance.md) 4.7.3
- [@turf/point-on-line](https://npm.io/package/@turf/point-on-line.md) 4.7.3

## Recent versions

- 0.1.6 (latest) — 2021-05-27
- 0.1.5 — 2020-09-10
- 0.1.4 — 2017-11-29
- 0.1.3 — 2017-11-29
- 0.1.2 — 2017-11-28
- 0.1.1 — 2017-11-28
- 0.1.0 — 2017-11-28
- 0.0.4 — 2017-11-27
- 0.0.3 — 2017-11-17
- 0.0.2 — 2017-11-17
- 0.0.1 — 2017-11-08

## README

# fid
fid is a navigation route splicing and simulation library.

![](docs/animated-rope-black-cover-3.gif)

## 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](https://github.com/mapbox/binnacle). It also can output GeoJSON for visualization purposes.

## How do I use it?

`npm install @mapbox/fid`

then

```javascript
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**. 

![](docs/data-structures.png)

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:

![](docs/splicing.png)

---
_Source: https://npm.io/package/@mapbox/fid · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._