Drake

Namespaces  
drake  
drake::maliput  
drake::maliput::api  
drake::maliput::multilane  
Functions  
std::unique_ptr< const api::RoadGeometry >  Load (const BuilderFactoryBase &builder_factory, const std::string &input) 
Loads the input string as a maliput_multilane_builder document using the provided builder_factory . More...  
std::unique_ptr< const api::RoadGeometry >  LoadFile (const BuilderFactoryBase &builder_factory, const std::string &filename) 
Loads the named file as a maliput_multilane_builder document using the provided builder_factory . More...  
Multilane is a backend implementation of Maliput, an interface to describe road geometries. Multilane provides two loader methods ( Load() and LoadFile() ) that will parse a YAML file or string by calling appropriate Builder methods to create a RoadGeometry
.
The serialization is a fairly straightforward mapping of the Builder interface onto YAML.
The basic idea is, however:
Parsing will fail if there is no way to concretely resolve all of the Endpoint references, e.g., if a document specifies that ConnectionA is an arc starting at the end of ConnectionB and that ConnectionB is an arc starting at the end of ConnectionA. All referential chains must bottom out in explicitlynamed Endpoints.
All the road geometry information must be under a root node called maliput_multilane_builder
, otherwise it will not be parsed.
The following list shows the expected units for floatingpoint quantities:
All positions, distances, lengths, angles and derivatives are floating point numbers. Other type of quantities will be integers.
Clarifications to better understand the nomenclature used within this description:
noncapitalized
strings will be used.maliput
, Capitalized
strings will be used.For points in space, a right handed, orthonormal and inertial ℝ³ frame is used. Its basis is (x̂, ŷ, ẑ), where x̂, ŷ are coplanar with the ground and ẑ points upwards, and positions are expressed as (x, y, z)
triples. Also, the Θ angle rotating around the ẑ axis is used to define headings. These rotations are right handed and an angle of 0° points in the x̂ direction. Angles with respect to a plane parallel to z = 0
can be defined. A heading vector pointing the direction of the lane at that point is used as rotation axis and the angle is clockwise. Those will express superelevation.
Below you can see a snippet with the general YAML structure.
maliput_multilane_builder
maliput_multilane_builder
holds all the common and default configurations to build a RoadGeometry
. All of them, except groups
, must be defined though some of them may be empty.
It will be represented as a mapping:
Where:
RoadGeometry
.connections
' reference curve.preferaccuracy
or preferspeed
The former guides the computations to be as accurate as precision states. The latter will be accurate whenever possible, but it's not guaranteed in favor of faster computations.endpoint
s to build connection
s. At least one point is required to anchor the connections to worldframe.connection
definitions. It may be empty if no Connection
is going to be defined.groups
where connections
can be put together. It may be empty or not defined if no group is going to be made.points
A collection of points in 3D space. Each one will be under a tag (used to reference it within connection
description) and defined by an endpoint_xy
and a endpoint_z
. Both sequences must be provided.
It will be represented as a mapping like:
Where:
xypoint
is the endpoint_xy
sequence.zpoint
is the endpoint_z
sequence.endpoint_xy
A point in the plane z = 0
expressed as (x, y, Θ)
, where (x, y)
defines the position and Θ defines the heading angle of the endpoint. All coordinates must be provided.
It will be represented as a sequence:
Where:
x
coordinate.y
coordinate.endpoint_z
Specifies elevation, slope, superelevation and its speed of change at a point over the plane z = 0
as `(z, z', Θ, Θ'), where
z` and Θ' are the elevation and superelevation of the road at the endpoint and z'
and Θ' are their respective derivatives with respect to an arclength coordinate t
that travels along curve’s projection over the z = 0
plane. All coordinates must be provided.
It will be represented as a sequence:
Where:
z
coordinate.z′
coordinate.connections
A connection
defines a Segment
and must provide the number of lanes, start endpoint
and end endpoint_z
information. Either line length
or arc
must be provided to define the planar geometry of that connection
. Optional extra information can also provided and it will modify the way the connection
will be created. connections
is a collection of connection
s and those will be identified by their tag. Each tag will name a connection
, can be referenced by other connection
s and to create group
s, and will be used as Segment
's ID as well.
start
endpoint
and end
endpoint_z
can either refer to a reference road curve or to the lane start and end Endpoint
s. When only start
and z_end
or explicit_end
are provided, those will refer to the reference road curve of the Connection
. r_ref
can be provided to state the offset distance from the reference road curve to ref_lane
connection
’s lane. Lanes are 0indexed. In addition, left and right shoulder distances can be provided and those will override default values. left_shoulder
and right_shoulder
must be bigger or equal to zero if provided.
Sample lineconnections mapping are shown below:
Within z_end
, THETA_DOT is optional, and typically should be omitted. When omitted, this value will be automatically calculated such that G1 continuity of the road surface is preserved. Otherwise, provided THETA_DOT will be used and the Builder will check whether or not G1 is preserved.
When explicit_end
is used, THETA_DOT will be set by Builder to preserve G1 road surface continuity.
Within z_end
, THETA_DOT is optional, and typically should be omitted. When omitted, this value will be automatically calculated such that G1 continuity of the road surface is preserved. Otherwise, provided THETA_DOT will be used and the Builder will check whether or not G1 is preserved.
When explicit_end
is used, THETA_DOT will be set by Builder to preserve G1 continuity of the road surface.
None of the lanebased flavors allow to have THETA_DOT at either start
or z_end
. Builder will adjust them to preserve G1 continuity of the road surface.
None of the lanebased flavors allow to have THETA_DOT at either start
or z_end
. Builder will adjust them to preserve G1 continuity of the road surface.
From examples above:
lanes
holds number of lanes, reference lane and distance from the reference lane to the reference curve.left_shoulder
is the extra space at the right side of the last lane of the connection. It will override default values.right_shoulder
is the extra space at the left side of the first lane of the connection
. It will override default values.start
is used to define the start endpoint
of one the connection
’s curves. It may have multiple options. Those can be split into two elements:ref
to point the reference curve.lane.LN
to point a specific lane.endpoint
in the points collection. Either forward
or reverse
should be used to indicate the direction of the endpoint
.endpoint
of a connection
’s reference curve or lane. Either forward or reverse should be used to indicate the direction of the endpoint
. When using the forward the endpoint
will be used as is. Otherwise (using reverse
) the Endpoint
will be reversed.length
is the connection
’s reference road curve planar line length.arc
is the connection
’s reference curve planar piece of arc.z_end
is the endpoint_z
information to end one of the connection
’s curves. It is composed of two elements too. The first one points to the reference curve when ref
is present. Otherwise, lane.LN
must be specified.explicit_end
is a node similar to start
. It is composed of two parts. The first one points to the reference curve when ref
is present. Otherwise, lane.LN
must be specified. The second part is used to point the endpoint
information which could be provided by a connection
or the points
collection. When using a connection
, two options are available: the reference curve or a lane.Possible combinations to define a connection
node are:
connection
must have either length
or arc
.connection
must have either z_end
or explicit_end
.start
and explicit_end
possible combinations:At least one connection must start with "LANE from POINT" or "REF from POINT" in order to anchor the road geometry in the world frame.
arc
Constant radius arcs are defined in terms of a radius and an angle span. arc
s are used to define planar curves on the the z = 0
plane, starting from an endpoint_xy
. Radius must be positive, and arc's center would be to the left (i.e. rotating +90° start endpoint_xy
’s heading vector) when theta is positive, otherwise it would be to the right (i.e. rotating 90° start endpoint_xy
’s heading).
It will be represented as a sequence:
Where:
arc
.arc
.groups
A group specifies a set of connections whose Segments will be placed together in the same Junction
. A connection
may only belong to a single group
. If a connection
is not in any group
, its Segment
will receive its own Junction
.
It will be represented as a mapping:
Where:
C\_1
, C\_2
, C\_3
are connections
’ IDs.