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...

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 `phases` is not connected end to end.
common::assertion_error	When `road_network` is nullptr.

TODO(#453): Validate end to end connection of the Phases.

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().

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()