From f041f910e75774e5c02dde90f5661ee2da325067 Mon Sep 17 00:00:00 2001 From: mvglasow Date: Thu, 8 May 2025 23:16:37 +0300 Subject: [PATCH] [openlr] Documentation Signed-off-by: mvglasow --- openlr/graph.hpp | 22 +++-- openlr/helpers.hpp | 22 +++-- openlr/openlr_decoder.hpp | 9 +- openlr/openlr_model.hpp | 104 ++++++++++++++++------- openlr/router.hpp | 72 +++++++++++----- openlr/score_candidate_paths_getter.hpp | 15 ++-- openlr/score_candidate_points_getter.hpp | 4 +- openlr/score_paths_connector.hpp | 9 +- openlr/stats.hpp | 4 +- 9 files changed, 181 insertions(+), 80 deletions(-) diff --git a/openlr/graph.hpp b/openlr/graph.hpp index 4caa9f1fa..0b5476056 100644 --- a/openlr/graph.hpp +++ b/openlr/graph.hpp @@ -30,16 +30,26 @@ public: Graph(DataSource & dataSource, std::shared_ptr 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, diff --git a/openlr/helpers.hpp b/openlr/helpers.hpp index 11d78aea6..b9e7105af 100644 --- a/openlr/helpers.hpp +++ b/openlr/helpers.hpp @@ -47,14 +47,18 @@ std::common_type_t 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); diff --git a/openlr/openlr_decoder.hpp b/openlr/openlr_decoder.hpp index 67a190220..9e612a29d 100644 --- a/openlr/openlr_decoder.hpp +++ b/openlr/openlr_decoder.hpp @@ -43,10 +43,17 @@ public: OpenLRDecoder(std::vector & 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 const & segments, uint32_t const numThreads, std::vector & paths); + /** + * Maps partner segments to mwm paths. + */ void DecodeV3(std::vector const & segments, uint32_t numThreads, std::vector & paths); diff --git a/openlr/openlr_model.hpp b/openlr/openlr_model.hpp index a33a6ce97..eb0d0cc4a 100644 --- a/openlr/openlr_model.hpp +++ b/openlr/openlr_model.hpp @@ -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; }; diff --git a/openlr/router.hpp b/openlr/router.hpp index 118443402..c93207e48 100644 --- a/openlr/router.hpp +++ b/openlr/router.hpp @@ -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 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 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 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 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 void ForStagePrefix(It b, It e, size_t stage, Fn && fn); diff --git a/openlr/score_candidate_paths_getter.hpp b/openlr/score_candidate_paths_getter.hpp index c8fc14335..99203948d 100644 --- a/openlr/score_candidate_paths_getter.hpp +++ b/openlr/score_candidate_paths_getter.hpp @@ -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, diff --git a/openlr/score_candidate_points_getter.hpp b/openlr/score_candidate_points_getter.hpp index 3c8c964ec..660ca470c 100644 --- a/openlr/score_candidate_points_getter.hpp +++ b/openlr/score_candidate_points_getter.hpp @@ -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); diff --git a/openlr/score_paths_connector.hpp b/openlr/score_paths_connector.hpp index 5561ceab9..1945e345b 100644 --- a/openlr/score_paths_connector.hpp +++ b/openlr/score_paths_connector.hpp @@ -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 const & points, std::vector> const & lineCandidates, LinearSegmentSource source, diff --git a/openlr/stats.hpp b/openlr/stats.hpp index 4f42a1116..01da5fb76 100644 --- a/openlr/stats.hpp +++ b/openlr/stats.hpp @@ -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