Project-OSRM · gardster · Aug 29, 2019 · Jul 31, 2019 · Jul 31, 2019 · Aug 2, 2019
diff --git a/.eslintignore b/.eslintignore
@@ -0,0 +1,2 @@
+features/support/flatbuffers.js
+features/support/fbresult_generated.js
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@
       - ADDED: data timestamp information in the response (saved in new file `.osrm.timestamp`). [#5115](https://github.com/Project-OSRM/osrm-backend/issues/5115)
       - ADDED: new API parameter - `snapping=any|default` to allow snapping to previously unsnappable edges [#5361](https://github.com/Project-OSRM/osrm-backend/pull/5361)
       - ADDED: keepalive support to the osrm-routed HTTP server [#5518](https://github.com/Project-OSRM/osrm-backend/pull/5518)
+      - ADDED: flatbuffers output format support [#5513](https://github.com/Project-OSRM/osrm-backend/pull/5513)
     - Routing:
       - CHANGED: allow routing past `barrier=arch` [#5352](https://github.com/Project-OSRM/osrm-backend/pull/5352)
       - CHANGED: default car weight was reduced to 2000 kg. [#5371](https://github.com/Project-OSRM/osrm-backend/pull/5371)

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -439,6 +439,12 @@ include_directories(SYSTEM ${PROTOZERO_INCLUDE_DIR})
 set(VTZERO_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/third_party/vtzero/include")
 include_directories(SYSTEM ${VTZERO_INCLUDE_DIR})
 
+set(FLATBUFFERS_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/third_party/flatbuffers")
+set(FLATBUFFERS_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/third_party/flatbuffers/include")
+include_directories(${FLATBUFFERS_INCLUDE_DIR})
+add_subdirectory(${FLATBUFFERS_SRC_DIR}
+        ${CMAKE_CURRENT_BINARY_DIR}/flatbuffers-build
+        EXCLUDE_FROM_ALL)
 
 # if mason is enabled no find_package calls are made
 # to ensure that we are only compiling and linking against
@@ -738,8 +744,10 @@ set_property(TARGET osrm-datastore PROPERTY INSTALL_RPATH_USE_LINK_PATH TRUE)
 set_property(TARGET osrm-routed PROPERTY INSTALL_RPATH_USE_LINK_PATH TRUE)
 
 file(GLOB VariantGlob third_party/variant/include/mapbox/*.hpp)
+file(GLOB FlatbuffersGlob third_party/flatbuffers/include/flatbuffers/*.h)
 file(GLOB LibraryGlob include/osrm/*.hpp)
 file(GLOB ParametersGlob include/engine/api/*_parameters.hpp)
+set(ApiHeader include/engine/api/base_result.hpp)
 set(EngineHeader include/engine/status.hpp include/engine/engine_config.hpp include/engine/hint.hpp include/engine/bearing.hpp include/engine/approach.hpp include/engine/phantom_node.hpp)
 set(UtilHeader include/util/coordinate.hpp include/util/json_container.hpp include/util/typedefs.hpp include/util/alias.hpp include/util/exception.hpp include/util/bearing.hpp)
 set(ExtractorHeader include/extractor/extractor.hpp include/storage/io_config.hpp include/extractor/extractor_config.hpp include/extractor/travel_mode.hpp)
@@ -754,7 +762,9 @@ install(FILES ${PartitionerHeader} DESTINATION include/osrm/partitioner)
 install(FILES ${ContractorHeader} DESTINATION include/osrm/contractor)
 install(FILES ${LibraryGlob} DESTINATION include/osrm)
 install(FILES ${ParametersGlob} DESTINATION include/osrm/engine/api)
+install(FILES ${ApiHeader} DESTINATION include/osrm/engine/api)
 install(FILES ${VariantGlob} DESTINATION include/mapbox)
+install(FILES ${FlatbuffersGlob} DESTINATION include/flatbuffers)
 install(TARGETS osrm-extract DESTINATION bin)
 install(TARGETS osrm-partition DESTINATION bin)
 install(TARGETS osrm-customize DESTINATION bin)

diff --git a/docs/http.md b/docs/http.md
@@ -21,7 +21,7 @@ GET /{service}/{version}/{profile}/{coordinates}[.{format}]?option=value&option=
 | `version` | Version of the protocol implemented by the service. `v1` for all OSRM 5.x installations |
 | `profile` | Mode of transportation, is determined statically by the Lua profile that is used to prepare the data using `osrm-extract`. Typically `car`, `bike` or `foot` if using one of the supplied profiles. |
 | `coordinates`| String of format `{longitude},{latitude};{longitude},{latitude}[;{longitude},{latitude} ...]` or `polyline({polyline}) or polyline6({polyline6})`. |
-| `format`| Only `json` is supported at the moment. This parameter is optional and defaults to `json`. |
+| `format`| `json` or `flatbuffers`. This parameter is optional and defaults to `json`. |
 
 Passing any `option=value` is optional. `polyline` follows Google's polyline format with precision 5 by default and can be generated using [this package](https://www.npmjs.com/package/polyline).
 
@@ -944,3 +944,174 @@ Object used to describe waypoint on a route.
    ]
 }
 ```
+
+## Flatbuffers format
+
+Default response format is `json`, but OSRM supports binary [`flatbuffers`](https://google.github.io/flatbuffers/) format, which 
+is much faster in serialization/deserialization, comparing to `json`.
+
+The format itself is described in message descriptors, located at `include/engine/api/flatbuffers directory`. Those descriptors could
+be compiled to provide protocol parsers in Go/Javascript/Typescript/Java/Dart/C#/Python/Lobster/Lua/Rust/PHP/Kotlin. Precompiled 
+protocol parser for C++ is supplied with OSRM.
+
+`Flatbuffers` format provides exactly same data, as `json` format with a slightly different layout, which was optimized to minimize
+in-transfer size.
+
+### Root object
+
+Root object is the only object, available from a 'raw' `flatbuffers` buffer. It can be constructed with a following call:
+
+         auto osrm = osrm::engine::api::fbresult::GetFBResult(some_input_buffer);
+
+**Properties**
+
+- `error`: `bool` Marks response as erroneous. Erroneus response should include `code` field set, all the other field may not present. 
+- `code`: `Error` Error description object, only present, when `error` is `true`
+- `waypoints`: `[Waypoint]` Array of `Waypoint` objects. Should present for every service call. Table service will put `sources` array here.
+- `routes`: `[RouteObject]` Array of `RouteObject` objects. May be empty or absent. Should present for Route/Trip/Match services call.
+- `table`: `Table` Table object, may absent. Should be present in case of Table service call.
+
+### Error object
+
+Contains error information.
+
+**Properties**
+
+- `code`: `string` Error code 
+- `message`: `string` Detailed error message
+
+### Waypoint object
+
+Almost same as `json` Waypoint object. The following properties differ:
+
+- `location`: `Position` Same as `json` location field, but different format. 
+- `nodes`: `Uint64Pair` Same as `json` nodes field, but different format.
+
+### RouteObject object
+
+Almost same as `json` Route object. The following properties differ:
+
+- `polyline`: `string` Same as `json` geometry.polyline or geometry.polyline6 fields. One field for both formats. 
+- `coordinates`: `[Position]` Same as `json` geometry.coordinates field, but different format.
+- `legs`: `[Leg]` Array of `Leg` objects.
+
+### Leg object
+
+Almost same as `json` Leg object. The following properties differ:
+
+- `annotations`: `Annotation` Same as `json` annotation field, but different format.
+- `steps`: `[Step]` Same as `step` annotation field, but different format.
+
+### Step object
+
+Almost same as `json` Step object. The following properties differ:
+
+- `polyline`: `string` Same as `json` geometry.polyline or geometry.polyline6 fields. One field for both formats. 
+- `coordinates`: `[Position]` Same as `json` geometry.coordinates field, but different format.
+- `maneuver`: `StepManeuver` Same as `json` maneuver field, but different format.
+
+| `type`           | Description                                                                                                                                                                                                                                                                                                                  |
+|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Turn`           | a basic turn into direction of the `modifier`                                                                                                                                                                                                                                                                                |
+| `NewName`        | no turn is taken/possible, but the road name changes. The road can take a turn itself, following `modifier`.                                                                                                                                                                                                                 |
+| `Depart`         | indicates the departure of the leg                                                                                                                                                                                                                                                                                           |
+| `Arrive`         | indicates the destination of the leg                                                                                                                                                                                                                                                                                         |
+| `Merge`          | merge onto a street (e.g. getting on the highway from a ramp, the `modifier specifies the direction of the merge`)                                                                                                                                                                                                           |
+| `OnRamp`         | take a ramp to enter a highway (direction given my `modifier`)                                                                                                                                                                                                                                                               |
+| `OffRamp`        | take a ramp to exit a highway (direction given my `modifier`)                                                                                                                                                                                                                                                                |
+| `Fork`           | take the left/right side at a fork depending on `modifier`                                                                                                                                                                                                                                                                   |
+| `EndOfRoad`      | road ends in a T intersection turn in direction of `modifier`                                                                                                                                                                                                                                                                |
+| `Continue`       | Turn in direction of `modifier` to stay on the same road                                                                                                                                                                                                                                                                     |
+| `Roundabout`     | traverse roundabout, if the route leaves the roundabout there will be an additional property `exit` for exit counting. The modifier specifies the direction of entering the roundabout.                                                                                                                                      |
+| `Rotary`         | a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer `rotary_name` and/or `rotary_pronunciation` parameters (located in the RouteStep object) in addition to the `exit` parameter (located on the StepManeuver object).  |
+| `RoundaboutTurn` | Describes a turn at a small roundabout that should be treated as normal turn. The `modifier` indicates the turn direciton. Example instruction: `At the roundabout turn left`.                                                                                                                                               |
+| `Notification`   | not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the `modifier` describes the direction                                                                                                                                                   |
+| `ExitRoundabout` | Describes a maneuver exiting a roundabout (usually preceeded by a `roundabout` instruction)                                                                                                                                                                                                                                  |
+| `ExitRotary`     | Describes the maneuver exiting a rotary (large named roundabout)                                                                                                                                                                                                                                                             |
+
+- `driving_side`: `bool` Ttrue stands for the left side driving. 
+- `intersections`: `[Intersection]` Same as `json` intersections field, but different format.
+
+### Intersection object
+
+Almost same as `json` Intersection object. The following properties differ:
+
+- `location`: `Position` Same as `json` location property, but in different format.
+- `lanes`: `[Lane]` Array of `Lane` objects.
+
+### Lane object
+
+Almost same as `json` Lane object. The following properties differ:
+
+- `indications`: `Turn` Array of `Turn` enum values. 
+
+| `value`                | Description                                                                                                               |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------|
+| `None`                 | No dedicated indication is shown.                                                                                         |
+| `UTurn`                | An indication signaling the possibility to reverse (i.e. fully bend arrow).                                               |
+| `SharpRight`           | An indication indicating a sharp right turn (i.e. strongly bend arrow).                                                   |
+| `Right`                | An indication indicating a right turn (i.e. bend arrow).                                                                  |
+| `SlightRight`          | An indication indicating a slight right turn (i.e. slightly bend arrow).                                                  |
+| `Straight`             | No dedicated indication is shown (i.e. straight arrow).                                                                   |
+| `SlightLeft`           | An indication indicating a slight left turn (i.e. slightly bend arrow).                                                   |
+| `Left`                 | An indication indicating a left turn (i.e. bend arrow).                                                                   |
+| `SharpLeft`            | An indication indicating a sharp left turn (i.e. strongly bend arrow).                                                    |
+
+### StepManeuver object
+
+Almost same as `json` StepManeuver object. The following properties differ:
+
+- `location`: `Position` Same as `json` location property, but in different format.
+- `type`: `ManeuverType` Type of a maneuver (enum)
+
+| `type`           | Description                                                  |
+|------------------|--------------------------------------------------------------|
+| `Turn`           | a basic turn into direction of the `modifier`                |
+| `NewName`        | no turn is taken/possible, but the road name changes. The road can take a turn itself, following `modifier`.                  |
+| `Depart`         | indicates the departure of the leg                           |
+| `Arrive`         | indicates the destination of the leg                         |
+| `Merge`          | merge onto a street (e.g. getting on the highway from a ramp, the `modifier specifies the direction of the merge`) |
+| `OnRamp`         | take a ramp to enter a highway (direction given my `modifier`) |
+| `OffRamp`        | take a ramp to exit a highway (direction given my `modifier`)  |
+| `Fork`           | take the left/right side at a fork depending on `modifier`   |
+| `EndOfRoad`      | road ends in a T intersection turn in direction of `modifier`|
+| `Continue`       | Turn in direction of `modifier` to stay on the same road     |
+| `Roundabout`     | traverse roundabout, if the route leaves the roundabout there will be an additional property `exit` for exit counting. The modifier specifies the direction of entering the roundabout. |
+| `Rotary`         | a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer `rotary_name` and/or `rotary_pronunciation` parameters (located in the RouteStep object) in addition to the `exit` parameter (located on the StepManeuver object).  |
+| `RoundaboutTurn` | Describes a turn at a small roundabout that should be treated as normal turn. The `modifier` indicates the turn direciton. Example instruction: `At the roundabout turn left`. |
+| `Notification`   | not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the `modifier` describes the direction |
+| `ExitRoundabout` | Describes a maneuver exiting a roundabout (usually preceeded by a `roundabout` instruction) |
+| `ExitRotary`    | Describes the maneuver exiting a rotary (large named roundabout) |
+
+- `modifier`: `Turn` Maneuver turn (enum) 
+
+### Annotation object
+
+Exactly same as `json` annotation object. 
+
+
+### Position object
+
+A point on Earth. 
+
+***Properties***
+- `longitute`: `float` Point's longitude
+- `latitude`: `float` Point's latitude
+
+### Uint64Pair
+
+A pair of long long integers. Used only by `Waypoint` object.
+
+***Properties***
+- `first`: `uint64` First pair value.
+- `second`: `uint64` Second pair value.
+
+### Table object
+
+Almost same as `json` Table object. The main difference is that 'sources' field is absent and root's object 'waypoints' field is
+used instead. All the other differences follow:
+
+- `durations`: `[float]` Flat representation of a durations matrix. Element at row;col can be adressed as [row * cols + col]
+- `destinations`: `[float]` Flat representation of a destinations matrix. Element at row;col can be adressed as [row * cols + col]
+- `rows`: `ushort` Number of rows in durations/destinations matrices.
+- `cols`: `ushort` Number of cols in durations/destinations matrices.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		features/support/flatbuffers.js
		features/support/fbresult_generated.js