mapbox / guidance-sim

Creates Mapbox Directions API guidance simulations using Mapbox GL JS

guidance-sim

A project to simulate guidance routes using Mapbox GL JS from Mapbox Directions API responses.

Simulating a Mapbox Directions Guidance Route

var simulate = require('guidance-sim').simulate;
var configuration = require('./configuration.json');

var map = new mapboxgl.Map({
    // desired map options
});
map.on('style.load', function () {
    simulate(map, configuration);
});

Parameters

• map Object Mapbox GL map object
• config Object Configuration parameters, which include the following:

parameter	required	type	default value	notes
style	Yes	String	mapbox://styles/mapbox/streets-v8	Style ID provided by Mapbox Studio
route	Yes	Object	---	Mapbox Directions v4 or v5 API response
spacing	No	String	constant	constant assumes a constant speed throughout playback acceldecel assumes an average speed per route step
zoom	Yes	Number	17	If spacing:constant - zoom when not maneuvering If spacing:acceldecel - zoom at 30mph
pitch	Yes	Number	45	Pitch when not maneuvering
timestamp	Yes	String	00h00m00s	Route simulation playback start time
speed	Yes	String	1x	Route simulation playback speed
maneuvers	Yes	Object	---	Specifies desired buffer (miles), zoom, and pitch for each maneuver

The maneuvers configuration parameter provides the simulator alternative map parameters when approaching and exiting a maneuver. The following configuration will ease sinusoidally from a pitch of 40° to 35° and zoom of 17 to 17.5 beginning 0.10 miles away from any turns, and ease back to the default values over 0.10 miles afterwards:

{
    'zoom': 17,
    'pitch': 40,
    'maneuvers': [
        {
          "type": [
            "turn right",
            "turn left"
          ],
          "buffer": 0.10,
          "zoom": 17.5,
          "pitch": 35
        }
    ]
}

Example

npm start
# --> http://localhost:9966/

Creating a Configuration File

npm run configure

This script generates a starter configuration file for running a simulation. You will be prompted to provide inputs for parameters. Default parameters, presented in magenta text, will be automatically configured if you press `[ENTER]`` without specifying a value.

If there are errors, the script will print the first error it encountered. If there are no errors, a configuration file should be created at the specified filepath (i.e., first input provided).

Additional Notes

A maneuver array will be automatically added to your configuration file. Please see the explanation above for maneuver object specifications.

For Directions v5 API responses, maneuvers have an additional modifiers field. If a maneuver type is specified but no modifiers, it is assumed that the rule should be applied to all modifier values. The exception to this is if a modifier is specified for the same type in another maneuver object. In this scenario, the more specific configuration takes precendence.

Validating a Configuration File

npm run validate

This script validates the configuration file. You will be prompted to provide the filepath of the file you'd like to validate. The default directory is the main directory.

If there are errors, the script will print the first error it encounters. If there are no errors, the script will print the JSON-formatted configuration file contents back into the terminal.

Seeking to a Different Point in the Simulation

This function runs the Emitter.stepsTaken function from guidance-replay using the start time determined by the user in the configuration file.

var Emitter = require('guidance-replay').Emitter;
var route = require('guidance-replay').route;
var stepsTaken = require('guidance-sim').stepsTaken;

var configuration = require('./configuration.json');
var emitter = new Emitter(route(configuration.route), 1000);
var seek = 10000 // desired seek time in milliseconds

stepsTaken(emitter, seek);

Parameters

• emitter Object An event emitter object coming off the Emitter function in guidance-replay
• scrub Number Desired start time in milliseconds.

Adjusting Simulation Speed

This function clears the current interval and reinitializes a new interval using a new speed value.

var setSpeed = require('guidance-sim').setSpeed;

var map = new mapboxgl.Map({
    // desired map options
});
map.on('style.load', function () {
    var response = simulate(map, configuration);
    response.on('update', function(data) {
      var newSpeed = 500;
      response.interval = setSpeed(response, response.interval, newSpeed, data.options.frequency);
    })
});

Parameters

• response Object An EventEmitter object
• interval Number An interval ID
• speed Number The duration in milliseconds over which to ease the map to the new location
• options Object Map options from initialization; see simulate.js L62:71 for more information

Test

npm test

guidance-sim's Issues

how can get simulation finish event?

Is there any good way to reset map to before simulation?

Thanks.

Update configuration file validator

Update the configuration file generator to reflect the following changes:

• v4 Directions API routes can now jibe with "spacing": "acceldecel" mode

Deploying to Heroku and other platforms

Hi, I had two questions regarding this repo. I am trying to deploy the code to Heroku and other deployment platforms and I keep getting this error below:

LiveReload running on 35729
info Server running at http://172.19.106.102:9966/ (connect)
4617ms 3.3MB (browserify)
Error R10 (Boot timeout) -> Web process failed to bind to $PORT within 60 seconds of launch
Stopping process with SIGKILL
Process exited with status 137
State changed from starting to crashed

The port error is happening on each platform. Browserfy seems to have an issue when deploying to a server. It works perfectly locally but would like to see how I can have it running in a development server like heroku.

The other question I had was around starting and stopping the simulator after it started and then restart based on a click function.

Is it possible to change destination after the application is started?

Regular website hosting

Sorry, this might be a dummy question. but is there somehow a way to host it and be able to call by <script ... src="./guidance-sim.js"> ?

Back/Forward functionality

How difficult is it to add a back/forward functionality? Either by distance or to a certain point

Add maneuver object set-up to `configure.sh`

Update configure.sh to set-up the maneuver object according to the configuration route, instead of inserting a dummy object as it currently does.

Add docs files for `util.js` and `setTime.js`

Add a separate file that documents the functions available in:

• setTime.js
• util.js

Update configuration file generator

Update the configuration file generator to reflect the following changes:

• v4 Directions API routes can now jibe with "spacing": "acceldecel" mode

I may also want to eventually make the saved route response optional and add an option to provide an origin and destination through URL params.