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

Initial libosrm API docs

Browse Source
This commit is contained in:
Daniel J. Hofmann 2016-04-01 17:23:41 +02:00 committed by Patrick Niklaus
parent 9b52dd8bf7
commit c6c25e609b
13 changed files with 293 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
include/engine/api/base_parameters.hpp
View File

@ -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<util::Coordinate> coordinates;

9
include/engine/api/match_parameters.hpp
View File

@ -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()

9
include/engine/api/nearest_parameters.hpp
View File

@ -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;

19
include/engine/api/route_parameters.hpp
View File

@ -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<bool> uturns;
bool IsValid() const
{
return coordinates.size() >= 2 && BaseParameters::IsValid();
}
bool IsValid() const { return coordinates.size() >= 2 && BaseParameters::IsValid(); }
};
}
}

12
include/engine/api/table_parameters.hpp
View File

@ -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<std::size_t> sources;

15
include/engine/api/tile_parameters.hpp
View File

@ -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;

6
include/engine/api/trip_parameters.hpp
View File

@ -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

18
include/engine/engine_config.hpp
View File

@ -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;

4
include/engine/status.hpp
View File

@ -33,6 +33,10 @@ namespace osrm
namespace engine
{
/**
* Status for indicating query success or failure.
* \see OSRM
*/
enum class Status
{
Ok,

69
include/osrm/osrm.hpp
View File

@ -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 &parameters, 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 &parameters, 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 &parameters, 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 &parameters, 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 &parameters, 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 &parameters, std::string &result);
private:

14
include/storage/storage_config.hpp
View File

@ -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;

57
include/util/coordinate.hpp
View File

@ -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<double>(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<double>(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<std::int32_t>(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<std::int32_t>(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;

54
include/util/json_container.hpp
View File

@ -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<String,
Number,
mapbox::util::recursive_wrapper<Object>,
@ -85,17 +127,27 @@ using Value = mapbox::util::variant<String,
False,
Null>;
/**
* Typed Object.
*
* Unwrap the key-value pairs holding type via its values member attribute.
*/
struct Object
{
std::unordered_map<std::string, Value> values;
};
/**
* Typed Array.
*
* Unwrap the Value holding type via its values member attribute.
*/
struct Array
{
std::vector<Value> values;
};
} // namespace JSON
} // namespace json
} // namespace util
} // namespace osrm