From c6c25e609ba50a30d73453c98155c52b8803aa45 Mon Sep 17 00:00:00 2001 From: "Daniel J. Hofmann" Date: Fri, 1 Apr 2016 17:23:41 +0200 Subject: [PATCH] Initial libosrm API docs --- include/engine/api/base_parameters.hpp | 16 ++++++ include/engine/api/match_parameters.hpp | 9 +++ include/engine/api/nearest_parameters.hpp | 9 +++ include/engine/api/route_parameters.hpp | 19 +++++-- include/engine/api/table_parameters.hpp | 12 ++++ include/engine/api/tile_parameters.hpp | 15 +++++ include/engine/api/trip_parameters.hpp | 6 ++ include/engine/engine_config.hpp | 18 +++++- include/engine/status.hpp | 4 ++ include/osrm/osrm.hpp | 69 +++++++++++++++++++++++ include/storage/storage_config.hpp | 14 ++++- include/util/coordinate.hpp | 57 ++++++++++++++++++- include/util/json_container.hpp | 54 +++++++++++++++++- 13 files changed, 293 insertions(+), 9 deletions(-) diff --git a/include/engine/api/base_parameters.hpp b/include/engine/api/base_parameters.hpp index b0144630e..63239b716 100644 --- a/include/engine/api/base_parameters.hpp +++ b/include/engine/api/base_parameters.hpp @@ -43,6 +43,22 @@ namespace engine { namespace api { + +/** + * General parameters for OSRM service queries. + * + * Holds member attributes: + * - coordinates: for specifying location(s) to services + * - hints: hint for the service to derive the position(s) in the road network more efficiently, + * optional per coordinate + * - radiuses: limits the search for segments in the road network to given radius(es) in meter, + * optional per coordinate + * - bearings: limits the search for segments in the road network to given bearing(s) in degree + * towards true north in clockwise direction, optional per coordinate + * + * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters, + * NearestParameters, TripParameters, MatchParameters and TileParameters + */ struct BaseParameters { std::vector coordinates; diff --git a/include/engine/api/match_parameters.hpp b/include/engine/api/match_parameters.hpp index d33d24d3e..0cb4741ea 100644 --- a/include/engine/api/match_parameters.hpp +++ b/include/engine/api/match_parameters.hpp @@ -39,6 +39,15 @@ namespace engine namespace api { +/** + * Parameters specific to the OSRM Match service. + * + * Holds member attributes: + * - timestamps: timestamp(s) for the corresponding input coordinate(s) + * + * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters, + * NearestParameters, TripParameters, MatchParameters and TileParameters + */ struct MatchParameters : public RouteParameters { MatchParameters() diff --git a/include/engine/api/nearest_parameters.hpp b/include/engine/api/nearest_parameters.hpp index c516ee20e..6a6dad7f1 100644 --- a/include/engine/api/nearest_parameters.hpp +++ b/include/engine/api/nearest_parameters.hpp @@ -37,6 +37,15 @@ namespace engine namespace api { +/** + * Parameters specific to the OSRM Nearest service. + * + * Holds member attributes: + * - number of results: number of nearest segments that should be returned + * + * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters, + * NearestParameters, TripParameters, MatchParameters and TileParameters + */ struct NearestParameters : public BaseParameters { unsigned number_of_results = 1; diff --git a/include/engine/api/route_parameters.hpp b/include/engine/api/route_parameters.hpp index 6db16a723..b8704fca5 100644 --- a/include/engine/api/route_parameters.hpp +++ b/include/engine/api/route_parameters.hpp @@ -39,6 +39,20 @@ namespace engine namespace api { +/** + * Parameters specific to the OSRM Route service. + * + * Holds member attributes: + * - steps: return route step for each route leg + * - alternatives: tries to find alternative routes + * - geometries: route geometry encoded in Polyline or GeoJSON + * - overview: adds overview geometry either Full, Simplified (according to highest zoom level) or + * False (not at all) + * - uturns: enable or disable uturns (disabled by default) + * + * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters, + * NearestParameters, TripParameters, MatchParameters and TileParameters + */ struct RouteParameters : public BaseParameters { enum class GeometriesType @@ -73,10 +87,7 @@ struct RouteParameters : public BaseParameters OverviewType overview = OverviewType::Simplified; boost::optional uturns; - bool IsValid() const - { - return coordinates.size() >= 2 && BaseParameters::IsValid(); - } + bool IsValid() const { return coordinates.size() >= 2 && BaseParameters::IsValid(); } }; } } diff --git a/include/engine/api/table_parameters.hpp b/include/engine/api/table_parameters.hpp index 0a31829ad..d4d3fd356 100644 --- a/include/engine/api/table_parameters.hpp +++ b/include/engine/api/table_parameters.hpp @@ -43,6 +43,18 @@ namespace engine namespace api { +/** + * Parameters specific to the OSRM Table service. + * + * Holds member attributes: + * - sources: indices into coordinates indicating sources for the Table service, no sources means + * use all coordinates as sources + * - destinations: indices into coordinates indicating destinations for the Table service, no + * destinations means use all coordinates as destinations + * + * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters, + * NearestParameters, TripParameters, MatchParameters and TileParameters + */ struct TableParameters : public BaseParameters { std::vector sources; diff --git a/include/engine/api/tile_parameters.hpp b/include/engine/api/tile_parameters.hpp index 261264c03..34c949a89 100644 --- a/include/engine/api/tile_parameters.hpp +++ b/include/engine/api/tile_parameters.hpp @@ -37,6 +37,21 @@ namespace engine namespace api { +/** + * Parameters specific to the OSRM Tile service. + * + * Holds member attributes: + * - x: the x location for the tile + * - y: the y location for the tile + * - z: the zoom level for the tile + * + * The parameters x,y and z have to conform to the Slippy Map Tilenames specification: + * - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Zoom_levels + * - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#X_and_Y + * + * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters, + * NearestParameters, TripParameters, MatchParameters and TileParameters + */ struct TileParameters final { unsigned x; diff --git a/include/engine/api/trip_parameters.hpp b/include/engine/api/trip_parameters.hpp index 063f71d7d..53c9f4274 100644 --- a/include/engine/api/trip_parameters.hpp +++ b/include/engine/api/trip_parameters.hpp @@ -39,6 +39,12 @@ namespace engine namespace api { +/** + * Parameters specific to the OSRM Trip service. + * + * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters, + * NearestParameters, TripParameters, MatchParameters and TileParameters + */ struct TripParameters : public RouteParameters { // bool IsValid() const; Falls back to base class diff --git a/include/engine/engine_config.hpp b/include/engine/engine_config.hpp index e17d2ef3e..eb627198c 100644 --- a/include/engine/engine_config.hpp +++ b/include/engine/engine_config.hpp @@ -40,7 +40,23 @@ namespace osrm namespace engine { -struct EngineConfig +/** + * Configures an OSRM instance. + * + * You can customize the storage OSRM uses for auxiliary files specifying a storage config. + * + * You can further set service constraints. + * These are the maximum number of allowed locations (-1 for unlimited) for the services: + * - Trip + * - Route + * - Table + * - Match + * + * In addition, shared memory can be used for datasets loaded with osrm-datastore. + * + * \see OSRM, StorageConfig + */ +struct EngineConfig final { bool IsValid() const; diff --git a/include/engine/status.hpp b/include/engine/status.hpp index 2f3c3bafe..4a0fc9a54 100644 --- a/include/engine/status.hpp +++ b/include/engine/status.hpp @@ -33,6 +33,10 @@ namespace osrm namespace engine { +/** + * Status for indicating query success or failure. + * \see OSRM + */ enum class Status { Ok, diff --git a/include/osrm/osrm.hpp b/include/osrm/osrm.hpp index 0e9e6db4c..1de8610a3 100644 --- a/include/osrm/osrm.hpp +++ b/include/osrm/osrm.hpp @@ -45,20 +45,89 @@ using engine::api::TripParameters; using engine::api::MatchParameters; using engine::api::TileParameters; +/** + * Represents a Open Source Routing Machine with access to its services. + * + * This represents an Open Source Routing Machine (OSRM) instance, with the services: + * + * - Route: shortest path queries for coordinates + * - Table: distance tables for coordinates + * - Nearest: nearest street segment for coordinate + * - Trip: shortest round trip between coordinates + * - Match: snaps noisy coordinate traces to the road network + * - Tile: vector tiles with internal graph representation + * + * All services take service-specific parameters, fill a JSON object, and return a status code. + */ class OSRM final { public: + /** + * Constructs an OSRM instance with user-configurable settings. + * + * \param config The user-provided OSRM configuration. + * \see EngineConfig + */ explicit OSRM(EngineConfig &config); + ~OSRM(); + // Moveable but not copyable OSRM(OSRM &&) noexcept; OSRM &operator=(OSRM &&) noexcept; + /** + * Shortest path queries for coordinates. + * + * \param parameters route query specific parameters + * \return Status indicating success for the query or failure + * \see Status, RouteParameters and json::Object + */ Status Route(const RouteParameters ¶meters, json::Object &result); + + /** + * Distance tables for coordinates. + * + * \param parameters table query specific parameters + * \return Status indicating success for the query or failure + * \see Status, TableParameters and json::Object + */ Status Table(const TableParameters ¶meters, json::Object &result); + + /** + * Nearest street segment for coordinate. + * + * \param parameters nearest query specific parameters + * \return Status indicating success for the query or failure + * \see Status, NearestParameters and json::Object + */ Status Nearest(const NearestParameters ¶meters, json::Object &result); + + /** + * Trip: shortest round trip between coordinates. + * + * \param parameters trip query specific parameters + * \return Status indicating success for the query or failure + * \see Status, TripParameters and json::Object + */ Status Trip(const TripParameters ¶meters, json::Object &result); + + /** + * Match: snaps noisy coordinate traces to the road network + * + * \param parameters match query specific parameters + * \return Status indicating success for the query or failure + * \see Status, MatchParameters and json::Object + */ Status Match(const MatchParameters ¶meters, json::Object &result); + + /** + * Tile: vector tiles with internal graph representation + * + * \param parameters tile query specific parameters + * \return Status indicating success for the query or failure + * \see Status, TileParameters and json::Object + */ Status Tile(const TileParameters ¶meters, std::string &result); private: diff --git a/include/storage/storage_config.hpp b/include/storage/storage_config.hpp index b5d016408..e5e0e8879 100644 --- a/include/storage/storage_config.hpp +++ b/include/storage/storage_config.hpp @@ -7,9 +7,21 @@ namespace osrm { namespace storage { -struct StorageConfig + +/** + * Configures OSRM's file storage paths. + * + * \see OSRM, EngineConfig + */ +struct StorageConfig final { StorageConfig() = default; + + /** + * Constructs a storage configuration setting paths based on a base path. + * + * \param base The base path (e.g. france.pbf.osrm) to derive auxiliary file suffixes from. + */ StorageConfig(const boost::filesystem::path &base); bool IsValid() const; diff --git a/include/util/coordinate.hpp b/include/util/coordinate.hpp index d8e41a52e..e249bb227 100644 --- a/include/util/coordinate.hpp +++ b/include/util/coordinate.hpp @@ -50,6 +50,13 @@ OSRM_STRONG_TYPEDEF(int32_t, FixedLongitude) OSRM_STRONG_TYPEDEF(double, FloatLatitude) OSRM_STRONG_TYPEDEF(double, FloatLongitude) +/** + * Converts a typed latitude from floating to fixed representation. + * + * \param floating typed latitude in floating representation. + * \return typed latitude in fixed representation + * \see Coordinate, toFloating + */ inline FixedLatitude toFixed(const FloatLatitude floating) { const auto latitude = static_cast(floating); @@ -57,6 +64,13 @@ inline FixedLatitude toFixed(const FloatLatitude floating) return FixedLatitude(fixed); } +/** + * Converts a typed longitude from floating to fixed representation. + * + * \param floating typed longitude in floating representation. + * \return typed latitude in fixed representation + * \see Coordinate, toFloating + */ inline FixedLongitude toFixed(const FloatLongitude floating) { const auto longitude = static_cast(floating); @@ -64,6 +78,13 @@ inline FixedLongitude toFixed(const FloatLongitude floating) return FixedLongitude(fixed); } +/** + * Converts a typed latitude from fixed to floating representation. + * + * \param fixed typed latitude in fixed representation. + * \return typed latitude in floating representation + * \see Coordinate, toFixed + */ inline FloatLatitude toFloating(const FixedLatitude fixed) { const auto latitude = static_cast(fixed); @@ -71,6 +92,13 @@ inline FloatLatitude toFloating(const FixedLatitude fixed) return FloatLatitude(floating); } +/** + * Converts a typed longitude from fixed to floating representation. + * + * \param fixed typed longitude in fixed representation. + * \return typed longitude in floating representation + * \see Coordinate, toFixed + */ inline FloatLongitude toFloating(const FixedLongitude fixed) { const auto longitude = static_cast(fixed); @@ -78,9 +106,22 @@ inline FloatLongitude toFloating(const FixedLongitude fixed) return FloatLongitude(floating); } +// fwd. decl. struct FloatCoordinate; -// Coordinate encoded as longitude, latitude +/** + * Represents a coordinate based on longitude and latitude in fixed representation. + * + * To prevent accidental longitude and latitude flips, we provide typed longitude and latitude + * wrappers. You can cast these wrappers back to their underlying representation or convert them + * from one representation to the other. + * + * The two representation we provide are: + * - Fixed point + * - Floating point + * + * \see FloatCoordinate, toFixed, toFloating + */ struct Coordinate { FixedLongitude lon; @@ -107,7 +148,19 @@ struct Coordinate friend std::ostream &operator<<(std::ostream &out, const Coordinate coordinate); }; -// Coordinate encoded as longitude, latitude +/** + * Represents a coordinate based on longitude and latitude in floating representation. + * + * To prevent accidental longitude and latitude flips, we provide typed longitude and latitude + * wrappers. You can cast these wrappers back to their underlying representation or convert them + * from one representation to the other. + * + * The two representation we provide are: + * - Fixed point + * - Floating point + * + * \see Coordinate, toFixed, toFloating + */ struct FloatCoordinate { FloatLongitude lon; diff --git a/include/util/json_container.hpp b/include/util/json_container.hpp index b5b14a143..9a383bb86 100644 --- a/include/util/json_container.hpp +++ b/include/util/json_container.hpp @@ -44,12 +44,35 @@ namespace osrm namespace util { +/** + * JSON types representing OSRM responses. + * + * The json::Value type represents the basic sum-type, implemented as a variant. + * + * There are two ways for destructuring such types: + * - Either provide a visitor and use the apply_visitor function or + * - use the get function and explicitely specify the type + * + * See the following documentations on variants: + * - https://github.com/mapbox/variant + * - http://www.boost.org/doc/libs/1_55_0/doc/html/variant.html + * + * And take a look at the example we provide. + * + * \see OSRM + */ namespace json { +// fwd. decls. struct Object; struct Array; +/** + * Typed string wrapper. + * + * Unwrap the type via its value member attribute. + */ struct String { String() = default; @@ -58,6 +81,11 @@ struct String std::string value; }; +/** + * Typed floating point number. + * + * Unwrap the type via its value member attribute. + */ struct Number { Number() = default; @@ -65,18 +93,32 @@ struct Number double value; }; +/** + * Typed True. + */ struct True { }; +/** + * Typed False. + */ struct False { }; +/** + * Typed Null. + */ struct Null { }; +/** + * Typed Value sum-type implemented as a variant able to represent tree-like JSON structures. + * + * Dispatch on its type by either by using apply_visitor or its get function. + */ using Value = mapbox::util::variant, @@ -85,17 +127,27 @@ using Value = mapbox::util::variant; +/** + * Typed Object. + * + * Unwrap the key-value pairs holding type via its values member attribute. + */ struct Object { std::unordered_map values; }; +/** + * Typed Array. + * + * Unwrap the Value holding type via its values member attribute. + */ struct Array { std::vector values; }; -} // namespace JSON +} // namespace json } // namespace util } // namespace osrm