Open-Harbor/osrm-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Update nodejs docs to document the constructor better

Browse Source
This commit is contained in:
Patrick Niklaus 2017-04-28 13:44:44 +00:00 committed by Patrick Niklaus
parent 1aea10010b
commit f531a956f5
1 changed files with 73 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
src/nodejs/node_osrm.cpp
View File

@ -50,42 +50,38 @@ NAN_MODULE_INIT(Engine::Init)
// clang-format off // clang-format off
/** /**
*
* The `OSRM` method is the main constructor for creating an OSRM instance. * The `OSRM` method is the main constructor for creating an OSRM instance.
* An OSRM instance requires a `.osrm` dataset, which is prepared by the OSRM toolchain. * An OSRM instance requires a `.osrm` dataset, which is prepared by the OSRM toolchain.
* The documentation on `osrm-extract` and `osrm-contract` for more information. * You can create such a `.osrm` file by running the OSRM binaries we ship in `node_modules/osrm/lib/binding/` and default
* Once you have a complete `network.osrm` file, you can calculate routes in javascript with this library using the methods below. * profiles (e.g. for setting speeds and determining road types to route on) in `node_modules/osrm/profiles/`:
* To create an OSRM instance with your network you need to construct an instance like this: *
* node_modules/osrm/lib/binding/osrm-extract data.osm.pbf -p node_modules/osrm/profiles/car.lua
* node_modules/osrm/lib/binding/osrm-contract data.osrm
*
* Consult the [osrm-backend](https://github.com/Project-OSRM/osrm-backend) documentation for further details.
*
* Once you have a complete `network.osrm` file, you can calculate routes in javascript with this object.
* *
* ```javascript * ```javascript
* var osrm = new OSRM('network.osrm'); * var osrm = new OSRM('network.osrm');
* ``` * ```
* *
* #### Methods * @param {Object} [options={shared_memory: true}] Options for creating an OSRM object.
* * @param {String} [options.algorithm] The algorithm to use for routing. Can be 'CH', 'CoreCH' or 'MLD'. Default is 'CH'.
* | Service | Description | * Make sure you prepared the dataset with the correct toolchain.
* |-----------------------------|-----------------------------------------------------------| * @param {Boolean} [options.shared_memory] Connects to the persistent shared memory datastore.
* | [`osrm.route`](#route) | shortest path between given coordinates | * This requires you to run `osrm-datastore` prior to creating an `OSRM` object.
* | [`osrm.nearest`](#nearest) | returns the nearest street segment for a given coordinate | * @param {String} [options.path] The path to the `.osrm` files. This is mutually exclusive with setting {options.shared_memory} to true.
* | [`osrm.table`](#table) | computes distance tables for given coordinates |
* | [`osrm.match`](#match) | matches given coordinates to the road network |
* | [`osrm.trip`](#trip) | computes the shortest trip between given coordinates |
* | [`osrm.tile`](#tile) | Return vector tiles containing debugging info |
*
* #### General Options
*
* Each OSRM method (except for `OSRM.tile()`) has set of general options as well as unique options,
* outlined below.
*
* | Option | Values | Description | Format |
* | ----------- | -----------------| ------------ | -------|
* | coordinates | `array` of `coordinate` elements: `[{coordinate}, ...]` | The coordinates this request will use. | `array` with `[{lon},{lat}]` values, in decimal degrees |
* | bearings | `array` of `bearing` elements: `[{bearing}, ...]` | Limits the search to segments with given bearing in degrees towards true north in clockwise direction. | `null` or `array` with `[{value},{range}]` `integer 0 .. 360,integer 0 .. 180` |
* | radiuses | `array` of `radius` elements: `[{radius}, ...]` | Limits the search to given radius in meters. | `null` or `double >= 0` or `unlimited` (default) |
* | hints | `array` of `hint` elements: `[{hint}, ...]` | Hint to derive position in street network. | Base64 `string` |
* *
* @class OSRM * @class OSRM
* *
*/
/**
* Constructs an `OSRM` object directly from a path.
*
* @param {string} [path] The path to the `.osrm` files.
*
* @class OSRM
* *
*/ */
// clang-format on // clang-format on
@ -192,11 +188,16 @@ inline void async(const Nan::FunctionCallbackInfo<v8::Value> &info,
* @name route * @name route
* @memberof OSRM * @memberof OSRM
* @param {Object} options Object literal containing parameters for the route query. * @param {Object} options Object literal containing parameters for the route query.
* @param {Array} [options.coordinates] The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees.
* @param {Array} [options.bearings] Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
* Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* @param {Array} [options.radiuses] Limits the coordinate snapping to streets in the given radius in meters. Can be `null` or `double >= 0` or `unlimited` (default).
* @param {Array} [options.hints] Hints for the coordinate snapping. Array of base64 encoded strings.
* @param {Boolean} [options.alternatives=false] Search for alternative routes and return as well. * @param {Boolean} [options.alternatives=false] Search for alternative routes and return as well.
* *Please note that even if an alternative route is requested, a result cannot be guaranteed.* * *Please note that even if an alternative route is requested, a result cannot be guaranteed.*
* @param {Boolean} [options.steps=false] Return route steps for each route leg. * @param {Boolean} [options.steps=false] Return route steps for each route leg.
* @param {Boolean} or {Array} [options.annotations=false] Return annotations for each route leg. * @param {Boolean} [options.annotations=false] Return annotations for each route leg.
* Can be `false`, `true` or an array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed`. * @param {Array} [options.annotations] An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed`.
* @param {String} [options.geometries=polyline] Returned route geometry format (influences overview and per step). Can also be `geojson`. * @param {String} [options.geometries=polyline] Returned route geometry format (influences overview and per step). Can also be `geojson`.
* @param {String} [options.overview=simplified] Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`). * @param {String} [options.overview=simplified] Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`).
* @param {Boolean} [options.continue_straight] Forces the route to keep going straight at waypoints and don't do a uturn even if it would be faster. Default value depends on the profile. * @param {Boolean} [options.continue_straight] Forces the route to keep going straight at waypoints and don't do a uturn even if it would be faster. Default value depends on the profile.
@ -228,6 +229,11 @@ NAN_METHOD(Engine::route) //
* @name nearest * @name nearest
* @memberof OSRM * @memberof OSRM
* @param {Object} options - Object literal containing parameters for the nearest query. * @param {Object} options - Object literal containing parameters for the nearest query.
* @param {Array} [options.coordinates] The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees.
* @param {Array} [options.bearings] Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
* Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* @param {Array} [options.radiuses] Limits the coordinate snapping to streets in the given radius in meters. Can be `null` or `double >= 0` or `unlimited` (default).
* @param {Array} [options.hints] Hints for the coordinate snapping. Array of base64 encoded strings.
* @param {Number} [options.number=1] Number of nearest segments that should be returned. * @param {Number} [options.number=1] Number of nearest segments that should be returned.
* Must be an integer greater than or equal to `1`. * Must be an integer greater than or equal to `1`.
* @param {Function} callback * @param {Function} callback
@ -261,6 +267,11 @@ NAN_METHOD(Engine::nearest) //
* @name table * @name table
* @memberof OSRM * @memberof OSRM
* @param {Object} options - Object literal containing parameters for the table query. * @param {Object} options - Object literal containing parameters for the table query.
* @param {Array} [options.coordinates] The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees.
* @param {Array} [options.bearings] Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
* Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* @param {Array} [options.radiuses] Limits the coordinate snapping to streets in the given radius in meters. Can be `null` or `double >= 0` or `unlimited` (default).
* @param {Array} [options.hints] Hints for the coordinate snapping. Array of base64 encoded strings.
* @param {Array} [options.sources] An array of `index` elements (`0 <= integer < #coordinates`) to * @param {Array} [options.sources] An array of `index` elements (`0 <= integer < #coordinates`) to
* use * use
* location with given index as source. Default is to use all. * location with given index as source. Default is to use all.
@ -337,9 +348,14 @@ NAN_METHOD(Engine::tile)
* @name match * @name match
* @memberof OSRM * @memberof OSRM
* @param {Object} options - Object literal containing parameters for the match query. * @param {Object} options - Object literal containing parameters for the match query.
* @param {Array} [options.coordinates] The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees.
* @param {Array} [options.bearings] Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
* Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* @param {Array} [options.radiuses] Limits the coordinate snapping to streets in the given radius in meters. Can be `null` or `double >= 0` or `unlimited` (default).
* @param {Array} [options.hints] Hints for the coordinate snapping. Array of base64 encoded strings.
* @param {Boolean} [options.steps=false] Return route steps for each route. * @param {Boolean} [options.steps=false] Return route steps for each route.
* @param {Boolean} or {Array} [options.annotations=false] Return annotations for each route leg. * @param {Boolean} [options.annotations=false] Return annotations for each route leg.
* Can be `false`, `true` or an array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed`. * @param {Array} [options.annotations] An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed`.
* @param {String} [options.geometries=polyline] Returned route geometry format (influences overview and per step). Can also be `geojson`. * @param {String} [options.geometries=polyline] Returned route geometry format (influences overview and per step). Can also be `geojson`.
* @param {String} [options.overview=simplified] Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`). * @param {String} [options.overview=simplified] Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`).
* @param {Array<Number>} [options.timestamps] Timestamp of the input location (integers, UNIX-like timestamp). * @param {Array<Number>} [options.timestamps] Timestamp of the input location (integers, UNIX-like timestamp).
@ -380,14 +396,33 @@ NAN_METHOD(Engine::match) //
* (farthest-insertion algorithm) for 10 or * more waypoints and uses brute force for less than 10 * (farthest-insertion algorithm) for 10 or * more waypoints and uses brute force for less than 10
* waypoints. The returned path does not have to be the shortest path, * as TSP is NP-hard it is * waypoints. The returned path does not have to be the shortest path, * as TSP is NP-hard it is
* only an approximation. * only an approximation.
*
* Note that all input coordinates have to be connected for the trip service to work. * Note that all input coordinates have to be connected for the trip service to work.
* Currently, not all combinations of `roundtrip`, `source` and `destination` are supported.
* Right now, the following combinations are possible:
*
* | roundtrip | source | destination | supported |
* | :-- | :-- | :-- | :-- |
* | true | first | last | **yes** |
* | true | first | any | **yes** |
* | true | any | last | **yes** |
* | true | any | any | **yes** |
* | false | first | last | **yes** |
* | false | first | any | no |
* | false | any | last | no |
* | false | any | any | no |
* *
* @name trip * @name trip
* @memberof OSRM * @memberof OSRM
* @param {Object} options - Object literal containing parameters for the trip query. * @param {Object} options - Object literal containing parameters for the trip query.
* @param {Array} [options.coordinates] The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees.
* @param {Array} [options.bearings] Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
* Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* @param {Array} [options.radiuses] Limits the coordinate snapping to streets in the given radius in meters. Can be `null` or `double >= 0` or `unlimited` (default).
* @param {Array} [options.hints] Hints for the coordinate snapping. Array of base64 encoded strings.
* @param {Boolean} [options.steps=false] Return route steps for each route. * @param {Boolean} [options.steps=false] Return route steps for each route.
* @param {Boolean} or {Array} [options.annotations=false] Return annotations for each route leg. Can be `false`, * @param {Boolean} [options.annotations=false] Return annotations for each route leg.
* `true` or an array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed`. * @param {Array} [options.annotations] An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed`.
* @param {String} [options.geometries=polyline] Returned route geometry format (influences overview and per step). Can also be `geojson`. * @param {String} [options.geometries=polyline] Returned route geometry format (influences overview and per step). Can also be `geojson`.
* @param {String} [options.overview=simplified] Add overview geometry either `full`, `simplified` * @param {String} [options.overview=simplified] Add overview geometry either `full`, `simplified`
* @param {Function} callback * @param {Function} callback
@ -398,8 +433,8 @@ NAN_METHOD(Engine::match) //
* @returns {Object} containing `waypoints` and `trips`. * @returns {Object} containing `waypoints` and `trips`.
* **`waypoints`**: an array of [`Waypoint`](#waypoint) objects representing all waypoints in input order. * **`waypoints`**: an array of [`Waypoint`](#waypoint) objects representing all waypoints in input order.
* Each Waypoint object has the following additional properties, * Each Waypoint object has the following additional properties,
* 1) `trips_index`: index to trips of the sub-trip the point was matched to, * 1) `trips_index`: index to trips of the sub-trip the point was matched to, and
* and 2) `waypoint_index`: index of the point in the trip. * 2) `waypoint_index`: index of the point in the trip.
* **`trips`**: an array of [`Route`](#route) objects that assemble the trace. * **`trips`**: an array of [`Route`](#route) objects that assemble the trace.
* *
* @example * @example
@ -408,7 +443,10 @@ NAN_METHOD(Engine::match) //
* coordinates: [ * coordinates: [
* [13.36761474609375, 52.51663871100423], * [13.36761474609375, 52.51663871100423],
* [13.374481201171875, 52.506191342034576] * [13.374481201171875, 52.506191342034576]
* ] * ],
* source: "first",
* destination: "last",
* roundtrip: false
* } * }
* osrm.trip(options, function(err, response) { * osrm.trip(options, function(err, response) {
* if (err) throw err; * if (err) throw err;