Drake
road_geometry.h
Go to the documentation of this file.
1 #pragma once
2 
3 #include <string>
4 #include <vector>
5 
9 
10 namespace drake {
11 namespace maliput {
12 namespace api {
13 
14 class BranchPoint;
15 class Junction;
16 
17 
18 /// Persistent identifier for a RoadGeometry element.
20 
21 
22 /// Abstract API for the geometry of a road network, including both
23 /// the network topology and the geometry of its embedding in 3-space.
24 // TODO(maddog@tri.global) This entire API should be templated on a
25 // scalar type T like everything else in drake.
26 class RoadGeometry {
27  public:
29 
30  virtual ~RoadGeometry() = default;
31 
32  /// Returns the persistent identifier.
33  ///
34  // TODO(maddog@tri.global) Tie id into a tiling mechanism?
35  const RoadGeometryId id() const { return do_id(); }
36 
37  // TODO(maddog@tri.global) Proper iterators over junctions and branch-points?
38 
39  /// Returns the number of Junctions in the RoadGeometry.
40  ///
41  /// Return value is non-negative.
42  int num_junctions() const { return do_num_junctions(); }
43 
44  /// Returns the Junction indexed by @p index.
45  ///
46  /// @pre @p index must be >= 0 and < num_junctions().
47  const Junction* junction(int index) const { return do_junction(index); }
48 
49  /// Returns the number of BranchPoints in the RoadGeometry.
50  ///
51  /// Return value is non-negative.
52  int num_branch_points() const { return do_num_branch_points(); }
53 
54  /// Returns the BranchPoint indexed by @p index.
55  ///
56  /// @pre @p index must be >= 0 and < num_branch_points().
57  const BranchPoint* branch_point(int index) const {
58  return do_branch_point(index);
59  }
60 
61  /// Determines the RoadPosition corresponding to GeoPosition @p geo_position.
62  ///
63  /// If @p hint is non-null, its value is used to help determine the result.
64  ///
65  /// The return value is the RoadPosition of the point in the RoadGeometry's
66  /// manifold which is, in the world frame, closest to @p geo_position. If
67  /// @p nearest_position is non-null, then it will be populated with the
68  /// GeoPosition of that nearest point. If @p distance is non-null, then it
69  /// will be populated with the Cartesian distance from @p geo_position to
70  /// that nearest point.
71  ///
72  /// This method guarantees that its result satisfies the condition that
73  /// `result.lane->ToGeoPosition(result.pos)` is within `linear_tolerance()`
74  /// of `*nearest_position`.
75  ///
76  /// The map from RoadGeometry to the world frame is not onto (as a bounded
77  /// RoadGeometry cannot completely cover the unbounded Cartesian universe).
78  /// If @p geo_position does represent a point contained within the volume
79  /// of the RoadGeometry, then result @p distance is guaranteed to be less
80  /// than or equal to `linear_tolerance()`.
81  ///
82  /// The map from RoadGeometry to world frame is not necessarily one-to-one.
83  /// Different `(s,r,h)` coordinates from different Lanes, potentially from
84  /// different Segments, may map to the same `(x,y,z)` world frame location.
85  ///
86  /// If @p geo_position is contained within the volumes of multiple Segments,
87  /// then ToRoadPosition() will choose a Segment which yields the minimum
88  /// height `h` value in the result. If the chosen Segment has multiple
89  /// Lanes, then ToRoadPosition() will choose a Lane which contains
90  /// @p geo_position within its `lane_bounds()` if possible, and if that is
91  /// still ambiguous, it will further select a Lane which minimizes the
92  /// absolute value of the lateral `r` coordinate in the result.
93  // TODO(maddog@tri.global) Establish what effect `hint` has on the outcome.
94  // Two notions:
95  // 1) the hint helps to bootstrap a search;
96  // 2) the hint helps to choose between multiple
97  // equally valid solutions.
98  // The general idea: if one knows the RoadPosition
99  // of an entity some small dT in the past, then one
100  // might expect an updated RoadPosition which is
101  // nearby (e.g., on the same Lane).
103  const RoadPosition* hint,
104  GeoPosition* nearest_position,
105  double* distance) const {
106  return DoToRoadPosition(geo_position, hint, nearest_position, distance);
107  }
108 
109  /// Returns the tolerance guaranteed for linear measurements (positions).
110  double linear_tolerance() const {
111  return do_linear_tolerance();
112  }
113 
114  /// Returns the tolerance guaranteed for angular measurements (orientations).
115  double angular_tolerance() const {
116  return do_angular_tolerance();
117  }
118 
119  /// Verifies certain invariants guaranteed by the API.
120  ///
121  /// Returns a vector of strings describing violations of invariants.
122  /// Return value with size() == 0 indicates success.
123  std::vector<std::string> CheckInvariants() const;
124 
125  protected:
126  RoadGeometry() = default;
127 
128  private:
129  /// @name NVI implementations of the public methods.
130  /// These must satisfy the constraints/invariants of the
131  /// corresponding public methods.
132  ///@{
133  virtual const RoadGeometryId do_id() const = 0;
134 
135  virtual int do_num_junctions() const = 0;
136 
137  virtual const Junction* do_junction(int index) const = 0;
138 
139  virtual int do_num_branch_points() const = 0;
140 
141  virtual const BranchPoint* do_branch_point(int index) const = 0;
142 
143  virtual RoadPosition DoToRoadPosition(const GeoPosition& geo_pos,
144  const RoadPosition* hint,
145  GeoPosition* nearest_position,
146  double* distance) const = 0;
147 
148  virtual double do_linear_tolerance() const = 0;
149 
150  virtual double do_angular_tolerance() const = 0;
151  ///@}
152 };
153 
154 
155 } // namespace api
156 } // namespace maliput
157 } // namespace drake
A BranchPoint is a node in the network of a RoadGeometry at which Lanes connect to one another...
Definition: branch_point.h:67
Definition: automotive_demo.cc:88
std::vector< std::string > CheckInvariants() const
Verifies certain invariants guaranteed by the API.
Definition: road_geometry.cc:118
Abstract API for the geometry of a road network, including both the network topology and the geometry...
Definition: road_geometry.h:26
const RoadGeometryId id() const
Returns the persistent identifier.
Definition: road_geometry.h:35
RoadPosition ToRoadPosition(const GeoPosition &geo_position, const RoadPosition *hint, GeoPosition *nearest_position, double *distance) const
Determines the RoadPosition corresponding to GeoPosition geo_position.
Definition: road_geometry.h:102
double linear_tolerance() const
Returns the tolerance guaranteed for linear measurements (positions).
Definition: road_geometry.h:110
TypeSpecificIdentifier<T> represents an identifier specifically identifying an entity of type T...
Definition: type_specific_identifier.h:38
int num_junctions() const
Returns the number of Junctions in the RoadGeometry.
Definition: road_geometry.h:42
GeoPositionT< double > GeoPosition
Definition: lane_data.h:178
double angular_tolerance() const
Returns the tolerance guaranteed for angular measurements (orientations).
Definition: road_geometry.h:115
const BranchPoint * branch_point(int index) const
Returns the BranchPoint indexed by index.
Definition: road_geometry.h:57
TypeSpecificIdentifier< class RoadGeometry > RoadGeometryId
Persistent identifier for a RoadGeometry element.
Definition: road_geometry.h:19
int num_branch_points() const
Returns the number of BranchPoints in the RoadGeometry.
Definition: road_geometry.h:52
A Junction is a closed set of Segments which have physically coplanar road surfaces, in the sense that RoadPositions with the same h value (height above surface) in the domains of two Segments map to the same GeoPosition.
Definition: junction.h:27
#define DRAKE_NO_COPY_NO_MOVE_NO_ASSIGN(Classname)
DRAKE_NO_COPY_NO_MOVE_NO_ASSIGN deletes the special member functions for copy-construction, copy-assignment, move-construction, and move-assignment.
Definition: drake_copyable.h:33
A position in the road network, consisting of a pointer to a specific Lane and a Lane-frame position ...
Definition: lane_data.h:282
Provides careful macros to selectively enable or disable the special member functions for copy-constr...
const Junction * junction(int index) const
Returns the Junction indexed by index.
Definition: road_geometry.h:47