Allow returning geometry by leg

CHANGELOG.md

@@ -2,6 +2,8 @@
   - Changes from 6.0.0
     - Routing:
       - FIXED: Crash when route starts or ends at `type=manoeuvre` relation via node [#7287](https://github.com/Project-OSRM/osrm-backend/issues/7287)
+    - API:
+      - ADDED: The parameter `overview` now accepts `by_legs` to include the geometry on the `RouteLeg` instead of the `Route` object. [#7256](https://github.com/Project-OSRM/osrm-backend/pull/7256)
     - Profiles:
       - ADDED: Make `max_collapse_distance` configurable via Lua profiles to preserve short road crossings in pedestrian routing [#6171](https://github.com/Project-OSRM/osrm-backend/issues/6171)
       - ADDED: Add exception for audible fences (`barrier=fence` with `sensory=audible` or `sensory=audio`) that deter livestock but do not block vehicles [#6964](https://github.com/Project-OSRM/osrm-backend/issues/6964)

docs/http.md

@@ -211,7 +211,7 @@ In addition to the [general options](#general-options) the following options are
 |steps       |`true`, `false` (default)                    |Returned route steps for each route leg                                        |
 |annotations |`true`, `false` (default), `nodes`, `distance`, `duration`, `datasources`, `weight`, `speed`  |Returns additional metadata for each coordinate along the route geometry.      |
 |geometries  |`polyline` (default), `polyline6`, `geojson` |Returned route geometry format (influences overview and per step)              |
-|overview    |`simplified` (default), `full`, `false`      |Add overview geometry either full, simplified according to highest zoom level it could be displayed on, or not at all.|
+|overview    |`simplified` (default), `full`, `false`, `by_legs`      |Add overview geometry either full, simplified according to highest zoom level it could be displayed on, not at all, or split by leg.|
 |continue\_straight |`default` (default), `true`, `false`  |Forces the route to keep going straight at waypoints constraining uturns there even if it would be faster. Default value depends on the profile. |
 |waypoints   | `{index};{index};{index}...`                |Treats input coordinates indicated by given indices as waypoints in returned Match object. Default is to treat all input coordinates as waypoints.    |
 
@@ -432,7 +432,7 @@ In addition to the [general options](#general-options) the following options are
 |steps       |`true`, `false` (default)                       |Returned route steps for each route                                                       |
 |geometries  |`polyline` (default), `polyline6`, `geojson`    |Returned route geometry format (influences overview and per step)                         |
 |annotations |`true`, `false` (default), `nodes`, `distance`, `duration`, `datasources`, `weight`, `speed`  |Returns additional metadata for each coordinate along the route geometry.                 |
-|overview    |`simplified` (default), `full`, `false`         |Add overview geometry either full, simplified according to highest zoom level it could be displayed on, or not at all.|
+|overview    |`simplified` (default), `full`, `false`, `by_legs`         |Add overview geometry either full, simplified according to highest zoom level it could be displayed on, not at all, or split by leg.|
 |timestamps  |`{timestamp};{timestamp}[;{timestamp} ...]`     |Timestamps for the input locations in seconds since UNIX epoch. Timestamps need to be monotonically increasing. |
 |radiuses    |`{radius};{radius}[;{radius} ...]`              |Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy.|
 |gaps        |`split` (default), `ignore`                     |Allows the input track splitting based on huge timestamp gaps between points.             |
@@ -489,7 +489,7 @@ In addition to the [general options](#general-options) the following options are
 |steps       |`true`, `false` (default)                       |Returned route instructions for each trip                                  |
 |annotations |`true`, `false` (default), `nodes`, `distance`, `duration`, `datasources`, `weight`, `speed` |Returns additional metadata for each coordinate along the route geometry.  |
 |geometries  |`polyline` (default), `polyline6`, `geojson`    |Returned route geometry format (influences overview and per step)          |
-|overview    |`simplified` (default), `full`, `false`         |Add overview geometry either full, simplified according to highest zoom level it could be displayed on, or not at all.|
+|overview    |`simplified` (default), `full`, `false`, `by_legs`         |Add overview geometry either full, simplified according to highest zoom level it could be displayed on, not at all, or split by leg.|
 
 **Fixing Start and End Points**
 

docs/nodejs/api.md

@@ -63,7 +63,7 @@ Returns the fastest route between two or more coordinates while visiting the way
     *   `options.steps` **[Boolean][4]** Return route steps for each route leg. (optional, default `false`)
     *   `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`)
     *   `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`)
-    *   `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`). (optional, default `simplified`)
+    *   `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` according to highest zoom level it could be displayed on, not at all (`false`), or split by leg (`by_legs`). (optional, default `simplified`)
     *   `options.continue_straight` **[Boolean][4]?** 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.
     *   `options.approaches` **[Array][5]?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`.
         `null`/`true`/`false`
@@ -229,7 +229,7 @@ if they can not be matched successfully.
     *   `options.steps` **[Boolean][4]** Return route steps for each route. (optional, default `false`)
     *   `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`)
     *   `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`)
-    *   `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`). (optional, default `simplified`)
+    *   `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` according to highest zoom level it could be displayed on, not at all (`false`), or split by leg (`by_legs`). (optional, default `simplified`)
     *   `options.timestamps` **[Array][5]<[Number][6]>?** Timestamp of the input location (integers, UNIX-like timestamp).
     *   `options.radiuses` **[Array][5]?** Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy. Can be `null` for default value `5` meters or `double >= 0`.
     *   `options.gaps` **[String][3]** Allows the input track splitting based on huge timestamp gaps between points. Either `split` or `ignore`. (optional, default `split`)
@@ -300,7 +300,7 @@ Right now, the following combinations are possible:
     *   `options.steps` **[Boolean][4]** Return route steps for each route. (optional, default `false`)
     *   `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`)
     *   `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`)
-    *   `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` (optional, default `simplified`)
+    *   `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` according to highest zoom level it could be displayed on, not at all (`false`), or split by leg (`by_legs`). (optional, default `simplified`)
     *   `options.roundtrip` **[Boolean][4]** Return route is a roundtrip. (optional, default `true`)
     *   `options.source` **[String][3]** Return route starts at `any` or `first` coordinate. (optional, default `any`)
     *   `options.destination` **[String][3]** Return route ends at `any` or `last` coordinate. (optional, default `any`)

generated/include/engine/api/flatbuffers/route_generated.h

@@ -899,7 +899,9 @@ struct Leg FLATBUFFERS_FINAL_CLASS : private ::flatbuffers::Table {
     VT_WEIGHT = 8,
     VT_SUMMARY = 10,
     VT_ANNOTATIONS = 12,
-    VT_STEPS = 14
+    VT_STEPS = 14,
+    VT_POLYLINE = 16,
+    VT_COORDINATES = 18
   };
   double distance() const {
     return GetField<double>(VT_DISTANCE, 0.0);
@@ -919,6 +921,12 @@ struct Leg FLATBUFFERS_FINAL_CLASS : private ::flatbuffers::Table {
   const ::flatbuffers::Vector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>> *steps() const {
     return GetPointer<const ::flatbuffers::Vector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>> *>(VT_STEPS);
   }
+  const ::flatbuffers::String *polyline() const {
+    return GetPointer<const ::flatbuffers::String *>(VT_POLYLINE);
+  }
+  const ::flatbuffers::Vector<const osrm::engine::api::fbresult::Position *> *coordinates() const {
+    return GetPointer<const ::flatbuffers::Vector<const osrm::engine::api::fbresult::Position *> *>(VT_COORDINATES);
+  }
   bool Verify(::flatbuffers::Verifier &verifier) const {
     return VerifyTableStart(verifier) &&
            VerifyField<double>(verifier, VT_DISTANCE, 8) &&
@@ -931,6 +939,10 @@ struct Leg FLATBUFFERS_FINAL_CLASS : private ::flatbuffers::Table {
            VerifyOffset(verifier, VT_STEPS) &&
            verifier.VerifyVector(steps()) &&
            verifier.VerifyVectorOfTables(steps()) &&
+           VerifyOffset(verifier, VT_POLYLINE) &&
+           verifier.VerifyString(polyline()) &&
+           VerifyOffset(verifier, VT_COORDINATES) &&
+           verifier.VerifyVector(coordinates()) &&
            verifier.EndTable();
   }
 };
@@ -957,6 +969,12 @@ struct LegBuilder {
   void add_steps(::flatbuffers::Offset<::flatbuffers::Vector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>>> steps) {
     fbb_.AddOffset(Leg::VT_STEPS, steps);
   }
+  void add_polyline(::flatbuffers::Offset<::flatbuffers::String> polyline) {
+    fbb_.AddOffset(Leg::VT_POLYLINE, polyline);
+  }
+  void add_coordinates(::flatbuffers::Offset<::flatbuffers::Vector<const osrm::engine::api::fbresult::Position *>> coordinates) {
+    fbb_.AddOffset(Leg::VT_COORDINATES, coordinates);
+  }
   explicit LegBuilder(::flatbuffers::FlatBufferBuilder &_fbb)
         : fbb_(_fbb) {
     start_ = fbb_.StartTable();
@@ -975,14 +993,18 @@ inline ::flatbuffers::Offset<Leg> CreateLeg(
     double weight = 0.0,
     ::flatbuffers::Offset<::flatbuffers::String> summary = 0,
     ::flatbuffers::Offset<osrm::engine::api::fbresult::Annotation> annotations = 0,
-    ::flatbuffers::Offset<::flatbuffers::Vector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>>> steps = 0) {
+    ::flatbuffers::Offset<::flatbuffers::Vector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>>> steps = 0,
+    ::flatbuffers::Offset<::flatbuffers::String> polyline = 0,
+    ::flatbuffers::Offset<::flatbuffers::Vector<const osrm::engine::api::fbresult::Position *>> coordinates = 0) {
   LegBuilder builder_(_fbb);
   builder_.add_weight(weight);
   builder_.add_duration(duration);
   builder_.add_distance(distance);
   builder_.add_steps(steps);
   builder_.add_annotations(annotations);
   builder_.add_summary(summary);
+  builder_.add_coordinates(coordinates);
+  builder_.add_polyline(polyline);
   return builder_.Finish();
 }
 
@@ -993,17 +1015,23 @@ inline ::flatbuffers::Offset<Leg> CreateLegDirect(
     double weight = 0.0,
     const char *summary = nullptr,
     ::flatbuffers::Offset<osrm::engine::api::fbresult::Annotation> annotations = 0,
-    const std::vector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>> *steps = nullptr) {
+    const std::vector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>> *steps = nullptr,
+    const char *polyline = nullptr,
+    const std::vector<osrm::engine::api::fbresult::Position> *coordinates = nullptr) {
   auto summary__ = summary ? _fbb.CreateString(summary) : 0;
   auto steps__ = steps ? _fbb.CreateVector<::flatbuffers::Offset<osrm::engine::api::fbresult::Step>>(*steps) : 0;
+  auto polyline__ = polyline ? _fbb.CreateString(polyline) : 0;
+  auto coordinates__ = coordinates ? _fbb.CreateVectorOfStructs<osrm::engine::api::fbresult::Position>(*coordinates) : 0;
   return osrm::engine::api::fbresult::CreateLeg(
       _fbb,
       distance,
       duration,
       weight,
       summary__,
       annotations,
-      steps__);
+      steps__,
+      polyline__,
+      coordinates__);
 }
 
 struct RouteObject FLATBUFFERS_FINAL_CLASS : private ::flatbuffers::Table {

include/engine/api/flatbuffers/route.fbs

@@ -96,6 +96,8 @@ table Leg {
     summary: string;
     annotations: Annotation;
     steps: [Step];
+    polyline: string;
+    coordinates: [Position];
 }
 
 table RouteObject {

include/engine/api/json_factory.hpp

@@ -103,9 +103,8 @@ util::json::Object makeWaypoint(const util::Coordinate &location,
                                 std::string name,
                                 const Hint &hint);
 
-util::json::Object makeRouteLeg(guidance::RouteLeg leg, util::json::Array steps);
-
 util::json::Array makeRouteLegs(std::vector<guidance::RouteLeg> legs,
+                                std::vector<util::json::Value> leg_geometries,
                                 std::vector<util::json::Value> step_geometries,
                                 std::vector<util::json::Object> annotations);
 } // namespace api::json

include/engine/api/route_api.hpp

@@ -186,26 +186,33 @@ class RouteAPI : public BaseAPI
     }
 
     std::optional<util::json::Value>
-    MakeGeometry(std::optional<std::vector<Coordinate>> &&annotations) const
+    MakeGeometry(std::optional<std::vector<Coordinate>> &&geometry) const
     {
         std::optional<util::json::Value> json_geometry;
-        if (annotations)
+        if (geometry)
         {
-            auto begin = annotations->begin();
-            auto end = annotations->end();
-            if (parameters.geometries == RouteParameters::GeometriesType::Polyline)
-            {
-                json_geometry = json::makePolyline<100000>(begin, end);
-            }
-            else if (parameters.geometries == RouteParameters::GeometriesType::Polyline6)
-            {
-                json_geometry = json::makePolyline<1000000>(begin, end);
-            }
-            else
-            {
-                BOOST_ASSERT(parameters.geometries == RouteParameters::GeometriesType::GeoJSON);
-                json_geometry = json::makeGeoJSONGeometry(begin, end);
-            }
+            json_geometry = MakeGeometry(*geometry);
+        }
+        return json_geometry;
+    }
+
+    util::json::Value MakeGeometry(const std::vector<Coordinate> &geometry) const
+    {
+        util::json::Value json_geometry;
+        auto begin = geometry.begin();
+        auto end = geometry.end();
+        if (parameters.geometries == RouteParameters::GeometriesType::Polyline)
+        {
+            json_geometry = json::makePolyline<100000>(begin, end);
+        }
+        else if (parameters.geometries == RouteParameters::GeometriesType::Polyline6)
+        {
+            json_geometry = json::makePolyline<1000000>(begin, end);
+        }
+        else
+        {
+            BOOST_ASSERT(parameters.geometries == RouteParameters::GeometriesType::GeoJSON);
+            json_geometry = json::makeGeoJSONGeometry(begin, end);
         }
         return json_geometry;
     }
@@ -389,6 +396,19 @@ class RouteAPI : public BaseAPI
                 summary_string = fb_result.CreateString(leg.summary);
             }
 
+            // Fill leg geometry if overview=by_legs
+            std::variant<flatbuffers::Offset<flatbuffers::String>,
+                         flatbuffers::Offset<flatbuffers::Vector<const fbresult::Position *>>>
+                leg_geometry_variant;
+            bool has_leg_geometry = false;
+
+            if (parameters.overview == RouteParameters::OverviewType::ByLegs)
+            {
+                leg_geometry_variant = MakeGeometry(
+                    fb_result, leg_geometry.locations.begin(), leg_geometry.locations.end());
+                has_leg_geometry = true;
+            }
+
             fbresult::LegBuilder legBuilder(fb_result);
             legBuilder.add_distance(leg.distance);
             legBuilder.add_duration(leg.duration);
@@ -403,6 +423,12 @@ class RouteAPI : public BaseAPI
             {
                 legBuilder.add_annotations(annotation_buffer);
             }
+
+            if (has_leg_geometry)
+            {
+                std::visit(GeometryVisitor<fbresult::LegBuilder>(legBuilder), leg_geometry_variant);
+            }
+
             routeLegs.emplace_back(legBuilder.Finish());
         }
         auto legs_vector = fb_result.CreateVector(routeLegs);
@@ -723,6 +749,16 @@ class RouteAPI : public BaseAPI
         auto route = guidance::assembleRoute(legs);
         std::optional<util::json::Value> json_overview = MakeGeometry(MakeOverview(leg_geometries));
 
+        std::vector<util::json::Value> json_overview_by_legs;
+        if (parameters.overview == RouteParameters::OverviewType::ByLegs)
+        {
+            json_overview_by_legs.reserve(leg_geometries.size());
+            for (const auto idx : util::irange<std::size_t>(0UL, leg_geometries.size()))
+            {
+                json_overview_by_legs.emplace_back(MakeGeometry(leg_geometries[idx].locations));
+            }
+        }
+
         std::vector<util::json::Value> step_geometries;
         const auto total_step_count =
             std::accumulate(legs.begin(),
@@ -871,6 +907,7 @@ class RouteAPI : public BaseAPI
 
         auto result = json::makeRoute(route,
                                       json::makeRouteLegs(std::move(legs),
+                                                          std::move(json_overview_by_legs),
                                                           std::move(step_geometries),
                                                           std::move(annotations)),
                                       std::move(json_overview),
@@ -1004,7 +1041,8 @@ class RouteAPI : public BaseAPI
     MakeOverview(const std::vector<guidance::LegGeometry> &leg_geometries) const
     {
         std::optional<std::vector<Coordinate>> overview;
-        if (parameters.overview != RouteParameters::OverviewType::False)
+        if (parameters.overview != RouteParameters::OverviewType::False &&
+            parameters.overview != RouteParameters::OverviewType::ByLegs)
         {
             const auto use_simplification =
                 parameters.overview == RouteParameters::OverviewType::Simplified;

include/engine/api/route_parameters.hpp

@@ -61,7 +61,8 @@ struct RouteParameters : public BaseParameters
     {
         Simplified,
         Full,
-        False
+        False,
+        ByLegs
     };
     enum class AnnotationsType
     {