Detailed Description

Describes the sequence of paths that go from one api::RoadPosition to another.

It hosts a subset of the api::RoadGeometry that represents a valid routing graph for agent navigation. For scalability, the route is divided into a sequence of Phases. These entities allow agents to reduce the path search space by constraining the lookup towards the end goal.

Agents are expected to use the Router to obtain a Route. Once in the Route, they can iterate through the Phases or find a specific Phase via an INERTIAL or LANE Frame coordinate and start driving from there towards the end goal.

The first Phase's first start position identifies the beginning of the Route. The last Phase's first end position identifies the ending of the Route. The sequence of Phases form a continuous route where the end of one Phase exactly matches the beginning of the next Phase in the sequence.

Let:

s indicates the start of the Route.
e indicates the end of the Route.
x indicates the start or end of an api::LaneSRange.
* indicates the start or end of a Phase.
- indicates the path of an api::LaneSRange.
_ indicates the path of an api::LaneSRange within a Phase.
S0, S1, ...: are api::Segments.
L0, L1, ...: are api::Lanes.

Consider the following road geometry and routing request:

       S1       S2       S3      S4
                                      e    L0
                                    /  x   L1
                                  /  /
                                /  /
L0 x--------x--------x--------x  /
L1 x--------x--------x--------x
L2 x--------x--------x--------x--------    L0
           /
         /                        S5
       /
     /
S0 s   L0

A valid Route could be:

       S1       S2       S3      S4
                                      e    L0
                                    // x   L1
                                  // //
                                // // <-- Phase, index 3
L0 x--------x________*________*  //
L1 x--------x________*________*
L2 x--------*________*________x--------    L0
           // ^        ^_ Phase, index 2
         //    \                  S5
       //        Phase, index 1
     //   <-- Phase, index 0
S0 s   L0

Depending on where queried, different api::LaneSRoutes are returned, for example, if queried from s, the returned sequence will be: {S0:L0, S2:L2, S2:L1, S2:L0, S3:L0, S3:L1, S3:L2, S4:L0, S4:L1}

And if queried at any point in S3:L2: {S3:L2, S3:L1, S3:L0, S4:L0, S4:L1}.

#include <include/maliput/routing/route.h>

Public Member Functions
	MALIPUT_DEFAULT_COPY_AND_MOVE_AND_ASSIGN (Route)

	Route ()=delete

	Route (const std::vector< Phase > &phases, const api::RoadNetwork *road_network)
	Constructs a Route. More...

int	size () const

const Phase &	Get (int index) const
	Indexes the Phases. More...

const api::LaneSRange &	GetLaneSRange (int phase_index, int lane_s_range_index) const
	Indexes an api::LaneSRange in a Phase. More...

const api::RoadPosition &	start_route_position () const
	Returns the start of this Route. More...

const api::RoadPosition &	end_route_position () const
	Returns the end of this Route. More...

RoutePositionResult	FindRoutePosition (const api::InertialPosition &inertial_position) const
	Finds the RoutePositionResult which `inertial_position` best fits. More...

RoutePositionResult	FindRoutePosition (const api::RoadPosition &road_position) const
	Finds the RoutePositionResult which `road_position` best fits. More...

LaneSRangeRelation	ComputeLaneSRangeRelation (const api::LaneSRange &lane_s_range_a, const api::LaneSRange &lane_s_range_b) const
	Computes the relation between `lane_s_range_b` with respect to `lane_s_range_a`. More...

api::LaneSRoute	ComputeLaneSRoute (const api::RoadPosition &start_position) const
	Computes an api::LaneSRoute that connects `start_position` with end_route_position(). More...

std::vector< std::string >	ValidateEndToEndConnectivity () const
	Evaluates whether this Route is connected end to end. More...

Constructor & Destructor Documentation

◆ Route() [1/2]

Route ( )

delete

◆ Route() [2/2]

Route	(	const std::vector< Phase > &	phases,
		const api::RoadNetwork *	road_network
	)

Constructs a Route.

Parameters

phases	The sequence of Phases. It must not be empty. Phases must be connected end to end.
road_network	The api::RoadNetwork pointer. It must not be nullptr. The lifetime of this pointer must exceed that of this object.

Exceptions

common::assertion_error	When `phases` is empty.
common::assertion_error	When `road_network` is nullptr.

Member Function Documentation

◆ ComputeLaneSRangeRelation()

LaneSRangeRelation ComputeLaneSRangeRelation	(	const api::LaneSRange &	lane_s_range_a,
		const api::LaneSRange &	lane_s_range_b
	)		const

Computes the relation between lane_s_range_b with respect to lane_s_range_a.

Parameters

lane_s_range_a	An api::LaneSRange.
lane_s_range_b	An api::LaneSRange.

Returns: The LaneSRangeRelation between lane_s_range_b with respect to lane_s_range_a.

◆ ComputeLaneSRoute()

api::LaneSRoute ComputeLaneSRoute ( const api::RoadPosition & start_position ) const

Computes an api::LaneSRoute that connects start_position with end_route_position().

The resulting api::LaneSRoute aims for reducing the number of lane switches. When start_position is not within this Route, it will be transformed by FindRoutePositionBy() to a point within it and then the api::LaneSRoute will be computed.

Simple agents / users should consider using this method to avoid dealing with the complexities of api::LaneSRange switching within a Phase and between Phases.

Parameters

start_position The start api::RoadPosition of this path. It must be valid.

Returns: The api::LaneSRoute connecting start_position and end_route_position().

Exceptions

common::assertion_error When start_position is not valid.

◆ end_route_position()

const api::RoadPosition& end_route_position ( ) const

Returns the end of this Route.

This is a convenience method for Get(size() - 1).end_positions().front().

◆ FindRoutePosition() [1/2]

RoutePositionResult FindRoutePosition ( const api::InertialPosition & inertial_position ) const

Finds the RoutePositionResult which inertial_position best fits.

The fitting of the inertial_position into the complete Route will use the same set of rules api::RoadGeometry::ToRoadPosition() uses to find a matching api::RoadPositionResult within the api::RoadGeometry. When the inertial_position does not fall into the volume defined by the set of api::LaneSRanges each Phase has, the returned Phase will be the one that minimizes the Euclidean distance to the Route. The mapping is done right on r=0, h=0 over the api::Lanes, i.e. at the centerline. This means that the returned distance and INERTIAL- Frame are evaluated there as well.

Parameters

inertial_position The INERTIAL-Frame position.

Returns: A RoutePositionResult.

◆ FindRoutePosition() [2/2]

RoutePositionResult FindRoutePosition ( const api::RoadPosition & road_position ) const

Finds the RoutePositionResult which road_position best fits.

The fitting of the road_position into the complete Route will use the same set of rules api::RoadGeometry::ToRoadPosition() uses to find a matching api::RoadPositionResult within the api::RoadGeometry. When the road_position does not fall into the volume defined by the set of api::LaneSRanges each Phase has, the returned Phase will be the one that minimizes the Euclidean distance to the Route. The mapping is done right on r=0, h=0 over the api::Lanes, i.e. at the centerline. This means that the returned distance and INERTIAL- Frame are evaluated there as well.

Parameters

road_position The road position. It must be valid.

Returns: A RoutePositionResult.

Exceptions

common::assertion_error When road_position is not valid.

◆ Get()

const Phase& Get ( int index ) const

Indexes the Phases.

Parameters

index The index of the Phase. It must be non-negative and less than size().

Returns: The Phase at index.

Exceptions

std::out_of_range When index is negative or >= size().

◆ GetLaneSRange()

const api::LaneSRange& GetLaneSRange	(	int	phase_index,
		int	lane_s_range_index
	)		const

Indexes an api::LaneSRange in a Phase.

Convenient method for advanced users.

Parameters

phase_index	The index of the api::LaneSRange in the Phase specified by `phase_index`. It must be non-negative and less than `size()`.
lane_s_range_index	The index of the api::LaneSRange. It must be non-negative and less than `Phase::lane_s_ranges().size()`.

Returns: The api::LaneSRange indexed at the phase_index -th Phase at the lane_s_range_index -th position.

Exceptions

std::out_of_range When any of the preconditions of phase_index or lane_s_range_index are unmet.

◆ MALIPUT_DEFAULT_COPY_AND_MOVE_AND_ASSIGN()

MALIPUT_DEFAULT_COPY_AND_MOVE_AND_ASSIGN ( Route )

◆ size()

int size ( ) const

Returns: The number of Phases.

◆ start_route_position()

const api::RoadPosition& start_route_position ( ) const

Returns the start of this Route.

This is a convenience method for Get(0).start_positions().front().

◆ ValidateEndToEndConnectivity()

std::vector< std::string > ValidateEndToEndConnectivity ( ) const

Evaluates whether this Route is connected end to end.

End to end connectivity for a Route implies the following conditions:

The first Phase contains only one start position.
The last Phase contains only one end position.
The number of end positions in a given Phase and start positions in the following Phase are the same.
For each end position in a given Phase there is a one-to-one relation in the start positions in the following Phase such that:
- The positions are coincident in the INERTIAL-Frame (geometrical connectivity) and,
- The positions belong to the same api::Lane or are endpoints of api::Lanes that share opposing api::LaneEnds in an api::BranchPoint (topological connectivity).

Router implementations are expected to construct Routes and validate they are connected end to end. Users of a Route may expect Routes built by Router implementations to be end to end connected.

Returns: A vector of strings with the errors found in the end to end connectivity. When there is no error and the connectivity checks are successful, this method returns an empty vector.

The documentation for this class was generated from the following files:

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ Route() [1/2]

◆ Route() [2/2]

Member Function Documentation

◆ ComputeLaneSRangeRelation()

◆ ComputeLaneSRoute()

◆ end_route_position()

◆ FindRoutePosition() [1/2]

◆ FindRoutePosition() [2/2]

◆ Get()

◆ GetLaneSRange()

◆ MALIPUT_DEFAULT_COPY_AND_MOVE_AND_ASSIGN()

◆ size()

◆ start_route_position()

◆ ValidateEndToEndConnectivity()