drifty/comaps
1
0
Fork 0
mirror of https://codeberg.org/comaps/comaps synced 2026-01-10 14:24:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

[openlr] Documentation

Browse Source 
Signed-off-by: mvglasow <michael -at- vonglasow.com>
This commit is contained in:
mvglasow
2025-05-08 23:16:37 +03:00
parent dbf253c9d1
commit f041f910e7
9 changed files with 181 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
openlr/graph.hpp
View File

@@ -30,16 +30,26 @@ public:
Graph(DataSource & dataSource, std::shared_ptr<routing::CarModelFactory> carModelFactory);
// Appends edges such as that edge.GetStartJunction() == junction to the |edges|.
/**
* Appends edges to `edges` such as that `edge.GetStartJunction() == junction`.
*/
void GetOutgoingEdges(geometry::PointWithAltitude const & junction, EdgeListT & edges);
// Appends edges such as that edge.GetEndJunction() == junction to the |edges|.
/**
* Appends edges to `edges` such as that `edge.GetEndJunction() == junction`.
*/
void GetIngoingEdges(geometry::PointWithAltitude const & junction, EdgeListT & edges);
// Appends edges such as that edge.GetStartJunction() == junction and edge.IsFake() == false
// to the |edges|.
/**
* Appends edges to `edges` such as that `edge.GetStartJunction() == junction` and
* `edge.IsFake() == false`.
*/
void GetRegularOutgoingEdges(Junction const & junction, EdgeListT & edges);
// Appends edges such as that edge.GetEndJunction() == junction and edge.IsFale() == false
// to the |edges|.
/**
* Appends edges to `edges` such as that `edge.GetEndJunction() == junction` and
* `edge.IsFake() == false`.
*/
void GetRegularIngoingEdges(Junction const & junction, EdgeListT & edges);
void FindClosestEdges(m2::PointD const & point, uint32_t const count,

22
openlr/helpers.hpp
View File

@@ -47,14 +47,18 @@ std::common_type_t<T, U> AbsDifference(T const a, U const b)
bool PassesRestriction(Graph::Edge const & e, FunctionalRoadClass restriction, FormOfWay formOfWay,
int frcThreshold, RoadInfoGetter & infoGetter);
/// \returns true if |e| conforms |functionalRoadClass| and |formOfWay| and false otherwise.
/// \note If the method returns true |score| should be considered next.
/**
* @return true if `e` conforms `functionalRoadClass` and `formOfWay` and false otherwise.
* @note If the method returns true `score` should be considered next.
*/
bool PassesRestrictionV3(Graph::Edge const & e, FunctionalRoadClass functionalRoadClass,
FormOfWay formOfWay, RoadInfoGetter & infoGetter, Score & score);
/// \returns true if edge |e| conforms Lowest Functional Road Class to Next Point.
/// \note frc means Functional Road Class. Please see openlr documentation for details:
/// http://www.openlr.org/data/docs/whitepaper/1_0/OpenLR-Whitepaper_v1.0.pdf
/**
* @return true if edge `e` conforms Lowest Functional Road Class to Next Point.
* @note frc means Functional Road Class. Please see openlr documentation for details:
* http://www.openlr.org/data/docs/whitepaper/1_0/OpenLR-Whitepaper_v1.0.pdf
*/
bool ConformLfrcnp(Graph::Edge const & e, FunctionalRoadClass lowestFrcToNextPoint,
int frcThreshold, RoadInfoGetter & infoGetter);
bool ConformLfrcnpV3(Graph::Edge const & e, FunctionalRoadClass lowestFrcToNextPoint,
@@ -64,9 +68,11 @@ size_t IntersectionLen(Graph::EdgeVector a, Graph::EdgeVector b);
bool SuffixEqualsPrefix(Graph::EdgeVector const & a, Graph::EdgeVector const & b, size_t len);
// Returns a length of the longest suffix of |a| that matches any prefix of |b|.
// Neither |a| nor |b| can contain several repetitions of any edge.
// Returns -1 if |a| intersection |b| is not equal to some suffix of |a| and some prefix of |b|.
/**
* Returns a length of the longest suffix of `a` that matches any prefix of `b`.
* Neither `a` nor `b` can contain several repetitions of any edge.
* Returns -1 if `a` intersection `b` is not equal to some suffix of `a` and some prefix of `b`.
*/
int32_t PathOverlappingLen(Graph::EdgeVector const & a, Graph::EdgeVector const & b);
m2::PointD PointAtSegmentM(m2::PointD const & p1, m2::PointD const & p2, double const distanceM);

9
openlr/openlr_decoder.hpp
View File

@@ -43,10 +43,17 @@ public:
OpenLRDecoder(std::vector<FrozenDataSource> & dataSources,
CountryParentNameGetter const & countryParentNameGetter);
// Maps partner segments to mwm paths. |segments| should be sorted by partner id.
/**
* Maps partner segments to mwm paths.
*
* `segments` should be sorted by partner id.
*/
void DecodeV2(std::vector<LinearSegment> const & segments, uint32_t const numThreads,
std::vector<DecodedPath> & paths);
/**
* Maps partner segments to mwm paths.
*/
void DecodeV3(std::vector<LinearSegment> const & segments, uint32_t numThreads,
std::vector<DecodedPath> & paths);

104
openlr/openlr_model.hpp
View File

@@ -10,42 +10,70 @@
namespace openlr
{
// The form of way (FOW) describes the physical road type of a line.
/**
* The form of way (FOW) describes the physical road type of a line.
*/
enum class FormOfWay
{
// The physical road type is unknown.
/**
* The physical road type is unknown.
*/
Undefined,
// A road permitted for motorized vehicles only in combination with a prescribed minimum speed.
// It has two or more physically separated carriageways and no single level-crossings.
/**
* A road permitted for motorized vehicles only in combination with a prescribed minimum speed.
* It has two or more physically separated carriageways and no single level-crossings.
*/
Motorway,
// A road with physically separated carriageways regardless of the number of lanes.
// If a road is also a motorway, it should be coded as such and not as a multiple carriageway.
/**
* A road with physically separated carriageways regardless of the number of lanes.
* If a road is also a motorway, it should be coded as such and not as a multiple carriageway.
*/
MultipleCarriageway,
// All roads without separate carriageways are considered as roads with a single carriageway.
/**
* All roads without separate carriageways are considered as roads with a single carriageway.
*/
SingleCarriageway,
// A road which forms a ring on which traffic traveling in only one direction is allowed.
/**
* A road which forms a ring on which traffic traveling in only one direction is allowed.
*/
Roundabout,
// An open area (partly) enclosed by roads which is used for non-traffic purposes
// and which is not a Roundabout.
/**
* An open area (partly) enclosed by roads which is used for non-traffic purposes
* and which is not a Roundabout.
*/
Trafficsquare,
// A road especially designed to enter or leave a line.
/**
* A road especially designed to enter or leave a line.
*/
Sliproad,
// The physical road type is known, but does not fit into one of the other categories.
/**
* The physical road type is known, but does not fit into one of the other categories.
*/
Other,
// A path only allowed for bikes.
/**
* A path only allowed for bikes.
*/
BikePath,
// A path only allowed for pedestrians.
/**
* A path only allowed for pedestrians.
*/
Footpath,
NotAValue
};
// The functional road class (FRC) of a line is a road classification based on the importance
// of the road represented by the line.
/**
* The functional road class (FRC) of a line is a road classification based on the importance
* of the road represented by the line.
*/
enum class FunctionalRoadClass
{
// Main road, highest importance.
/**
* Main road, highest importance.
*/
FRC0,
// First class road.
/**
* First class road.
*/
FRC1,
// Other road classes.
@@ -70,27 +98,37 @@ enum class LinearSegmentSource
struct LocationReferencePoint
{
// Coordinates of the point of interest.
/**
* Coordinates of the point of interest.
*/
ms::LatLon m_latLon = ms::LatLon::Zero();
// The bearing (BEAR) describes the angle between the true North and a line which is defined
// by the coordinate of the LocationReferencePoint and a coordinate which is BEARDIST along
// the line defined by the LocationReference-point attributes.
// For more information see OpenLR-Whitepaper `Bearing' section.
/**
* The bearing (BEAR) describes the angle between the true North and a line which is defined
* by the coordinate of the LocationReferencePoint and a coordinate which is BEARDIST along
* the line defined by the LocationReference-point attributes.
* For more information see OpenLR-Whitepaper ‘Bearing’ section.
*/
uint8_t m_bearing = 0;
FunctionalRoadClass m_functionalRoadClass = FunctionalRoadClass::NotAValue;
FormOfWay m_formOfWay = FormOfWay::NotAValue;
// The distance to next point field describes the distance to the next LocationReferencePoint
// in the topological connection of the LocationReferencePoints. The distance is measured in meters
// and is calculated along the location reference path between two subsequent LR-points.
// The last LRP has the distance value 0.
// Should not be used in the last point of a segment.
/**
* The distance to next point field describes the distance to the next LocationReferencePoint
* in the topological connection of the LocationReferencePoints. The distance is measured in meters
* and is calculated along the location reference path between two subsequent LR-points.
* The last LRP has the distance value 0.
* Should not be used in the last point of a segment.
*/
uint32_t m_distanceToNextPoint = 0;
// The lowest FunctionalRoadClass to the next point (LFRCNP) is the lowest FunctionalRoadClass
// value which appears in the location reference path between two consecutive LR-points.
// This information could be used to limit the number of road classes which need to be
// scanned during the decoding.
// Should not be used in the last point of a segment.
/**
* The lowest FunctionalRoadClass to the next point (LFRCNP) is the lowest FunctionalRoadClass
* value which appears in the location reference path between two consecutive LR-points.
* This information could be used to limit the number of road classes which need to be
* scanned during the decoding.
* Should not be used in the last point of a segment.
*/
FunctionalRoadClass m_lfrcnp = FunctionalRoadClass::NotAValue;
bool m_againstDrivingDirection = false;
};

72
openlr/router.hpp
View File

@@ -34,20 +34,30 @@ private:
class Score final
{
public:
// A weight for total length of true fake edges.
/**
* A weight for total length of true fake edges.
*/
static const int kTrueFakeCoeff = 10;
// A weight for total length of fake edges that are parts of some
// real edges.
/**
* A weight for total length of fake edges that are parts of some
* real edges.
*/
static constexpr double kFakeCoeff = 0.001;
// A weight for passing too far from pivot points.
/**
* A weight for passing too far from pivot points.
*/
static const int kIntermediateErrorCoeff = 3;
// A weight for excess of distance limit.
/**
* A weight for excess of distance limit.
*/
static const int kDistanceErrorCoeff = 3;
// A weight for deviation from bearing.
/**
* A weight for deviation from bearing.
*/
static const int kBearingErrorCoeff = 5;
void AddDistance(double p) { m_distance += p; }
@@ -66,7 +76,9 @@ private:
bool operator!=(Score const & rhs) const { return !(*this == rhs); }
private:
// Reduced length of path in meters.
/**
* Reduced length of path in meters.
*/
double m_distance = 0.0;
double m_penalty = 0.0;
@@ -143,21 +155,31 @@ private:
bool Init(std::vector<WayPoint> const & points, double positiveOffsetM, double negativeOffsetM);
bool FindPath(Path & path);
// Returns true if the bearing should be checked for |u|, if the
// real passed distance from the source vertex is |distanceM|.
/**
* Returns true if the bearing should be checked for `u`, if the
* real passed distance from the source vertex is `distanceM`.
*/
bool NeedToCheckBearing(Vertex const & u, double distanceM) const;
double GetPotential(Vertex const & u) const;
// Returns true if |u| is located near portal to the next stage.
// |pi| is the potential of |u|.
/**
* Returns true if `u` is located near portal to the next stage.
*
* @param pi potential of `u`.
*/
bool NearNextStage(Vertex const & u, double pi) const;
// Returns true if it's possible to move to the next stage from |u|.
// |pi| is the potential of |u|.
/**
* Returns true if it's possible to move to the next stage from `u`.
*
* @param pi potential of `u`.
*/
bool MayMoveToNextStage(Vertex const & u, double pi) const;
// Returns true if |u| is a final vertex and the router may stop now.
/**
* Returns true if `u` is a final vertex and the router may stop now.
*/
bool IsFinalVertex(Vertex const & u) const { return u.m_stage == m_pivots.size(); }
double GetWeight(routing::Edge const & e) const
@@ -194,20 +216,26 @@ private:
template <typename It>
size_t FindPrefixLengthToConsume(It b, It const e, double lengthM);
// Finds all edges that are on (u, v) and have the same direction as
// (u, v). Then, computes the fraction of the union of these edges
// to the total length of (u, v).
/**
* Finds all edges that are on (u, v) and have the same direction as
* (u, v). Then, computes the fraction of the union of these edges
* to the total length of (u, v).
*/
template <typename It>
double GetCoverage(m2::PointD const & u, m2::PointD const & v, It b, It e);
// Finds the longest prefix of [b, e) that covers edge (u, v).
// Returns the fraction of the coverage to the length of the (u, v).
/**
* Finds the longest prefix of [b, e) that covers edge (u, v).
* Returns the fraction of the coverage to the length of the (u, v).
*/
template <typename It>
double GetMatchingScore(m2::PointD const & u, m2::PointD const & v, It b, It e);
// Finds the longest prefix of fake edges of [b, e) that have the
// same stage as |stage|. If the prefix exists, passes its bounding
// iterator to |fn|.
/**
* Finds the longest prefix of fake edges of [b, e) that have the
* same stage as `stage`. If the prefix exists, passes its bounding
* iterator to `fn`.
*/
template <typename It, typename Fn>
void ForStagePrefix(It b, It e, size_t stage, Fn && fn);

15
openlr/score_candidate_paths_getter.hpp
View File

@@ -55,8 +55,10 @@ private:
Graph::Edge const m_edge;
double const m_distanceM;
Score const m_pointScore;
// Minimum score of segments of the path going along |m_parent| based on functional road class
// and form of way.
/**
* Minimum score of segments of the path going along `m_parent` based on functional road class
* and form of way.
*/
Score const m_minRoadScore;
};
@@ -94,9 +96,12 @@ private:
// distance-to-next point is taken from point 3. You can learn more in
// TomTom OpenLR spec.
/// \brief Fills |allPaths| with paths near start or finish point starting from |startLines|.
/// To extract a path from |allPaths| a item from |allPaths| should be taken,
/// then should be taken the member |m_parent| of the item and so on till the beginning.
/**
* @brief Fills `allPaths` with paths near start or finish point starting from `startLines`.
*
* To extract a path from `allPaths` a item from `allPaths` should be taken,
* then should be taken the member `m_parent` of the item and so on till the beginning.
*/
void GetAllSuitablePaths(ScoreEdgeVec const & startLines, LinearSegmentSource source,
bool isLastPoint, double bearDistM,
FunctionalRoadClass functionalRoadClass, FormOfWay formOfWay,

4
openlr/score_candidate_points_getter.hpp
View File

@@ -37,7 +37,9 @@ private:
ScoreEdgeVec & edgeCandidates);
void EnrichWithProjectionPoints(m2::PointD const & p, ScoreEdgeVec & edgeCandidates);
/// \returns true if |p| is a junction and false otherwise.
/**
* @return true if `p` is a junction and false otherwise.
*/
bool IsJunction(m2::PointD const & p);
Score GetScoreByDistance(m2::PointD const & point, m2::PointD const & candidate);

9
openlr/score_paths_connector.hpp
View File

@@ -17,9 +17,12 @@ class ScorePathsConnector
public:
ScorePathsConnector(Graph & graph, RoadInfoGetter & infoGetter, v2::Stats & stat);
/// \brief Connects |lineCandidates| and fills |resultPath| with the path with maximum score
/// if there's a good enough.
/// \returns true if the best path is found and false otherwise.
/**
* @brief Connects `lineCandidates` and fills `resultPath` with the path with maximum score
* if there's a good enough one.
*
* @return true if the best path is found and false otherwise.
*/
bool FindBestPath(std::vector<LocationReferencePoint> const & points,
std::vector<std::vector<ScorePath>> const & lineCandidates,
LinearSegmentSource source,

4
openlr/stats.hpp
View File

@@ -41,7 +41,9 @@ struct alignas(kCacheLineSize) Stats
uint32_t m_noShortestPathFound = 0;
uint32_t m_notEnoughScore = 0;
uint32_t m_wrongOffsets = 0;
// Number of zeroed distance-to-next point values in the input.
/**
* Number of zeroed distance-to-next point values in the input.
*/
uint32_t m_zeroDistToNextPointCount = 0;
};
} // namespace V2