Drake
right_of_way_rule.h
Go to the documentation of this file.
1 #pragma once
2 
3 #include <unordered_map>
4 #include <utility>
5 #include <vector>
6 
11 
12 namespace drake {
13 namespace maliput {
14 namespace api {
15 namespace rules {
16 
17 
18 /// Rule describing right-of-way, a.k.a. priority.
19 ///
20 /// Right-of-way rules cover things like stop signs, yield signs, and
21 /// traffic lights: in other words, control over how competing traffic
22 /// flows take turns traversing regions of the road network.
23 ///
24 /// Each rule instance comprises:
25 /// * a zone (a LaneSRoute) which specifies a contiguous longitudinal
26 /// lane-wise section of the road network to which the rule instance
27 /// applies;
28 /// * a ZoneType describing whether or not stopping within the zone is
29 /// allowed;
30 /// * a catalog of one or more States, each of which indicate the possible
31 /// right-of-way semantics for a vehicle traversing the zone.
32 ///
33 /// The `zone` is directed; the rule applies to vehicles traveling forward
34 /// through the `zone`.
35 ///
36 /// A rule instance with a single State is considered "static", and has fixed
37 /// semantics. A rule instance with multiple States is considered "dynamic"
38 /// and determination of the active rule State at any given time is delegated
39 /// to a RightOfWayStateProvider agent, linked by the rule's Id.
40 class RightOfWayRule final {
41  public:
43 
44  /// Unique identifier for a RightOfWayRule.
46 
47  /// Description of stopping properties of the zone.
48  enum class ZoneType {
49  kStopExcluded, ///< Vehicles should not stop within the zone; vehicles
50  /// should avoid entering the zone if traffic conditions
51  /// may cause them to stop within the zone. Vehicles
52  /// already in the zone when a kStop state occurs should
53  /// exit the zone.
54  kStopAllowed ///< Vehicles are allowed to stop within the zone.
55  };
56 
57  /// Semantic state of a RightOfWayRule.
58  ///
59  /// A State describes the semantic state of a RightOfWayRule,
60  /// basically "Go", "Stop", or "Stop, Then Go". A RightOfWayRule
61  /// may have multiple possible States, in which case its States must
62  /// have Id's which are unique within the context of that
63  /// RightOfWayRule.
64  ///
65  /// A State also describes the yield logic of a RightOfWayRule, via
66  /// a list of Id's of other RightOfWayRules (and thus the zones
67  /// which they control) which have priority over this rule. An
68  /// empty list means that a rule in this State has priority over all
69  /// other rules. Vehicles with lower priority (i.e., traveling on
70  /// lower-priority paths) must yield to vehicles with higher priority.
71  class State final {
72  public:
74 
75  /// Unique identifier for a State
77 
78  /// List of RightOfWayRule::Id's of rules/zones with priority.
79  using YieldGroup = std::vector<RightOfWayRule::Id>;
80 
81  /// Basic semantic type of a rule state.
82  enum class Type {
83  kGo = 0, ///< Vehicle has right-of-way and may proceed if
84  /// safe to do so.
85  kStop, ///< Vehicle does not have right-of-way and must
86  /// stop.
87  kStopThenGo ///< Vehicle must come to complete stop before
88  /// entering controlled zone, but may then
89  /// proceed if safe;
90  };
91 
92  /// Constructs a State instance.
93  ///
94  /// @param id the unique Id
95  /// @param type the semantic Type
96  /// @param yield_to the other paths/rules which must be yielded to
97  State(Id id, Type type, const YieldGroup& yield_to)
98  : id_(id), type_(type), yield_to_(yield_to) {}
99 
100  /// Returns the Id.
101  const Id& id() const { return id_; }
102 
103  /// Returns the Type.
104  Type type() const { return type_; }
105 
106  /// Returns the YieldGroup.
107  const YieldGroup& yield_to() const { return yield_to_; }
108 
109  private:
110  Id id_;
111  Type type_{};
112  YieldGroup yield_to_;
113  };
114 
115  /// Constructs a RightOfWayRule.
116  ///
117  /// @param id the unique ID of this rule (in the RoadRulebook)
118  /// @param controlled_zone LaneSRoute to which this rule applies
119  /// @param type the static semantics of this rule
120  ///
121  /// Throws a std::exception if `states` is empty or if `states` contains
122  /// duplicate State::Id's.
123  RightOfWayRule(const Id& id,
124  const LaneSRoute& zone,
126  const std::vector<State>& states)
127  : id_(id), zone_(zone), zone_type_(zone_type) {
128  DRAKE_THROW_UNLESS(states.size() >= 1);
129  for (const State& state : states) {
130  // Construct index of states by ID, ensuring uniqueness of ID's.
131  auto result = states_.emplace(state.id(), state);
132  DRAKE_THROW_UNLESS(result.second);
133  }
134  }
135 
136  /// Returns the rule's identifier.
137  const Id& id() const { return id_; }
138 
139  /// Returns the zone controlled by the rule.
140  const LaneSRoute& zone() const { return zone_; }
141 
142  /// Returns the zone's type.
143  ZoneType zone_type() const { return zone_type_; }
144 
145  /// Returns the catalog of possible States.
146  const std::unordered_map<State::Id, State>& states() const { return states_; }
147 
148  /// Returns true if the rule is static, i.e., has no dynamic state,
149  /// otherwise false.
150  ///
151  /// This is true if and only if the rule has a single state.
152  bool is_static() const { return states_.size() == 1; }
153 
154  /// Returns the static state of the rule.
155  ///
156  /// This is a convenience function for returning a static rule's single state.
157  ///
158  /// Throws a std::exception if `is_static()` is false.
159  const State& static_state() const {
161  return states_.begin()->second;
162  }
163 
164  private:
165  Id id_;
166  LaneSRoute zone_;
167  ZoneType zone_type_{};
168  std::unordered_map<State::Id, State> states_;
169 };
170 
171 
172 /// Abstract interface for the provider of the state of a dynamic
173 /// (multiple state) RightOfWayRule.
175  public:
177 
178  virtual ~RightOfWayStateProvider() = default;
179 
180  /// Result returned by GetState().
181  struct Result {
182  /// Information about a subsequent State.
183  struct Next {
184  /// ID of the State.
186  /// If known, estimated time until the transition to the State.
188  };
189 
190  /// ID of the rule's current State.
192  /// Information about the rule's upcoming State if a state transition
193  /// is anticipated.
195  };
196 
197  /// Gets the state of the RightOfWayRule identified by `id`.
198  ///
199  /// Returns a Result struct bearing the State::Id of the rule's current
200  /// state. If a transition to a new state is anticipated,
201  /// Result::next will be populated and bear the State::Id of the next
202  /// state. If the time until the transition is known, then
203  /// Result::next.duration_until will be populated with that duration.
204  ///
205  /// Returns nullopt if `id` is unrecognized, which would be the case
206  /// if no such rule exists or if the rule has only static semantics.
208  return DoGetState(id);
209  }
210 
211  protected:
212  RightOfWayStateProvider() = default;
213 
214  private:
215  virtual drake::optional<Result> DoGetState(
216  const RightOfWayRule::Id& id) const = 0;
217 };
218 
219 
220 } // namespace rules
221 } // namespace api
222 } // namespace maliput
223 } // namespace drake
const Id & id() const
Returns the Id.
Definition: right_of_way_rule.h:101
const YieldGroup & yield_to() const
Returns the YieldGroup.
Definition: right_of_way_rule.h:107
Rule describing right-of-way, a.k.a.
Definition: right_of_way_rule.h:40
ZoneType zone_type() const
Returns the zone&#39;s type.
Definition: right_of_way_rule.h:143
const LaneSRoute & zone() const
Returns the zone controlled by the rule.
Definition: right_of_way_rule.h:140
Provides a convenient wrapper to throw an exception when a condition is unmet.
Definition: bullet_model.cc:22
drake::optional< Result > GetState(const RightOfWayRule::Id &id) const
Gets the state of the RightOfWayRule identified by id.
Definition: right_of_way_rule.h:207
Vehicles are allowed to stop within the zone.
Type
Basic semantic type of a rule state.
Definition: right_of_way_rule.h:82
drake::optional< Next > next
Information about the rule&#39;s upcoming State if a state transition is anticipated. ...
Definition: right_of_way_rule.h:194
Semantic state of a RightOfWayRule.
Definition: right_of_way_rule.h:71
#define DRAKE_THROW_UNLESS(condition)
Evaluates condition and iff the value is false will throw an exception with a message showing at leas...
Definition: drake_throw.h:23
stx::optional< T > optional
Definition: drake_optional.h:22
const State & static_state() const
Returns the static state of the rule.
Definition: right_of_way_rule.h:159
std::vector< Number > result
Definition: ipopt_solver.cc:151
const std::unordered_map< State::Id, State > & states() const
Returns the catalog of possible States.
Definition: right_of_way_rule.h:146
TypeSpecificIdentifier<T> represents an identifier specifically identifying an entity of type T...
Definition: type_specific_identifier.h:39
#define DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN(Classname)
DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN defaults the special member functions for copy-construction, copy-assignment, move-construction, and move-assignment.
Definition: drake_copyable.h:57
Information about a subsequent State.
Definition: right_of_way_rule.h:183
const Id & id() const
Returns the rule&#39;s identifier.
Definition: right_of_way_rule.h:137
std::vector< RightOfWayRule::Id > YieldGroup
List of RightOfWayRule::Id&#39;s of rules/zones with priority.
Definition: right_of_way_rule.h:79
ZoneType
Description of stopping properties of the zone.
Definition: right_of_way_rule.h:48
A longitudinal route, possibly spanning multiple (end-to-end) lanes.
Definition: regions.h:72
Abstract interface for the provider of the state of a dynamic (multiple state) RightOfWayRule.
Definition: right_of_way_rule.h:174
ReferenceType type
Definition: loader.cc:34
State(Id id, Type type, const YieldGroup &yield_to)
Constructs a State instance.
Definition: right_of_way_rule.h:97
Type type() const
Returns the Type.
Definition: right_of_way_rule.h:104
Vehicles should not stop within the zone; vehicles should avoid entering the zone if traffic conditio...
Result returned by GetState().
Definition: right_of_way_rule.h:181
drake::optional< double > duration_until
If known, estimated time until the transition to the State.
Definition: right_of_way_rule.h:187
RightOfWayRule(const Id &id, const LaneSRoute &zone, ZoneType zone_type, const std::vector< State > &states)
Constructs a RightOfWayRule.
Definition: right_of_way_rule.h:123
RightOfWayRule::State::Id current_id
ID of the rule&#39;s current State.
Definition: right_of_way_rule.h:191
RightOfWayRule::State::Id id
ID of the State.
Definition: right_of_way_rule.h:185
bool is_static() const
Returns true if the rule is static, i.e., has no dynamic state, otherwise false.
Definition: right_of_way_rule.h:152
#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
Provides careful macros to selectively enable or disable the special member functions for copy-constr...