Expand description
A pure-Rust OpenDRIVE (.xodr) importer.
It works out OpenDRIVE’s curves and profiles once, at load, and returns a
RoadNetwork of lanes made of points. From there you sample points,
walk the lane graph, and mesh the road surface.
No C++, no bindings, no unsafe, and no math crate in the public API.
§Coordinate types
A position is a Point and a direction is a Vector. point - point
is a Vector, point + vector is a Point, and adding two points doesn’t
compile. Both are #[repr(C)] with three f32 fields.
Point::to_array hands one to another math library.
let net = xodr::load_file("maps/town07.xodr")?;
let lane = net.driving_lanes().next().expect("a driving lane");
let pose = lane.center.pose_at(25.0);
let route = net.route(pose.position, lane.center.point_at(400.0));§Which OpenDRIVE version
Any version loads. revMajor and revMinor are kept in
RoadNetwork::header and change nothing. A file that uses an element or
attribute from 1.8 or 1.9 but declares an older version raises
Warning::NewerThanDeclared. The crate reads the element anyway, since
the header is what is wrong.
Two elements read are not in 1.9:
- a lane’s
<visibility>, read as CARLA does. See Lane visibility. - a road’s
<neighbor>, from 1.4, as aRoadNeighborinRoadNetwork::road_neighbors. The crate derives no lane changes from it. One naming no baked road, or with asideordirection1.4 doesn’t allow, is dropped with aWarning::NeighborDropped.
Deprecated elements, poly3 and a signal’s <positionRoad> and
<positionInertial>, read like any other. The tests load real files
declaring 1.4, 1.6 and 1.7.
§Which elements
| Element | Attributes read |
|---|---|
<header> | revMajor, revMinor, name, version, date, vendor, north, south, east, west |
<header><geoReference> | its text |
<header><offset> | x, y, z, hdg |
<include>, anywhere | file |
<userData>, anywhere | code, value |
<dataQuality>, anywhere | none |
<dataQuality><error> | xyAbsolute, xyRelative, zAbsolute, zRelative |
<dataQuality><rawData> | date, source, sourceComment, postProcessing, postProcessingComment |
<header><license> | name, resource, spdxid, text |
<road> | id, name, length, junction, rule |
<road><link> | elementType, elementId, contactPoint, elementS, elementDir |
<link><neighbor> | side, elementId, direction |
<road><type> | s, type, country |
<type><speed> | max, unit |
<planView><geometry> | s, x, y, hdg, length |
<line> | none |
<arc> | curvature |
<spiral> | curvStart, curvEnd |
<poly3> | a, b, c, d |
<paramPoly3> | aU, bU, cU, dU, aV, bV, cV, dV, pRange |
<elevationProfile><elevation> | s, a, b, c, d |
<lateralProfile><superelevation> | s, a, b, c, d |
<lateralProfile><shape> | s, t, a, b, c, d |
<lateralProfile><crossfall>, from 1.4 | s, side, a, b, c, d |
<lateralProfile><crossSectionSurface> | none |
<crossSectionSurface><tOffset> | none |
<crossSectionSurface><surfaceStrips> | none |
<surfaceStrips><strip> | id, mode |
<strip><width>, <strip><constant>, <strip><linear>, <strip><quadratic>, <strip><cubic> | none |
<coefficients>, under each of those and <tOffset> | s, a, b, c, d |
<lanes><laneOffset> | s, a, b, c, d |
<lanes> | layer |
<laneSection> | s, length, singleSide |
<left>, <center>, <right> | none |
<lane> | id, type, level, direction, advisory, dynamicLaneType, dynamicLaneDirection, roadWorks |
<center><lane> | id, type, level |
<lane><width> | sOffset, a, b, c, d |
<lane><border> | sOffset, a, b, c, d |
<lane><height> | sOffset, inner, outer |
<lane><speed> | sOffset, max, unit |
<lane><rule> | sOffset, value |
<lane><access> | sOffset, rule, restriction |
<access><restriction> | type |
<lane><material> | sOffset, surface, friction, roughness |
<lane><visibility> | sOffset, forward, back, left, right |
<lane><roadMark> | sOffset, type, weight, color, material, width, height, laneChange |
<roadMark><type> | name, width |
<type><line> | length, space, tOffset, sOffset, rule, width, color |
<roadMark><explicit> | none |
<explicit><line> | length, tOffset, sOffset, rule, width |
<roadMark><sway> | ds, a, b, c, d |
<lane><link> | id, layer |
<junction> | id, name, type, mainRoad, sStart, sEnd, orientation |
<connection> | id, type, incomingRoad, connectingRoad, linkedRoad, contactPoint |
<connection><predecessor>, <connection><successor> | elementType, elementId, elementS, elementDir, contactPoint |
<laneLink> | from, to, overlapZone, fromLayer, toLayer |
<junction><priority> | high, low |
<road><railroad> | none |
<railroad><switch> | id, name, position |
<switch><mainTrack>, <switch><sideTrack> | id, s, dir |
<switch><partner> | id, name |
<station> | id, name, type |
<station><platform> | id, name |
<platform><segment> | roadId, sStart, sEnd, side |
<junctionGroup> | id, name, type |
<junctionGroup><junctionReference> | junction |
<junction><crossPath> | id, crossingRoad, roadAtStart, roadAtEnd |
<junction><roadSection> | id, roadId, sStart, sEnd |
<crossPath><startLaneLink> | s, from, to |
<crossPath><endLaneLink> | s, from, to |
<junction><planView> | its <geometry>s, as a road’s |
<junction><objects> | its <object>s and <objectReference>s, as a road’s |
<junction><boundary> | none |
<boundary><segment> | type, roadId, boundaryLane, sStart, sEnd, contactPoint, jointLaneStart, jointLaneEnd, transitionLength |
<junction><elevationGrid> | sStart, gridSpacing |
<elevationGrid><elevation> | left, center, right |
<objects><object> | id, type, subtype, name, dynamic, invalidated, temporary, orientation, validLength, s, t, zOffset, hdg, pitch, roll, perpToRoad, length, width, height, radius |
<objects><objectReference> | id, s, t, zOffset, orientation, validLength |
<objects><tunnel> | id, name, type, s, length, lighting, daylight |
<objects><bridge> | id, name, type, s, length |
<signals><signal> | id, name, dynamic, orientation, s, t, zOffset, hOffset, pitch, roll, country, countryRevision, type, subtype, value, unit, text, length, width, height, invalidated, temporary |
<signal><positionRoad> | roadId, s, t, zOffset, hOffset, pitch, roll |
<signal><positionInertial> | x, y, z, hdg, pitch, roll |
<signal><dependency>, <staticBoard><dependency>, <vmsBoard><dependency>, <sign><dependency>, <displayArea><dependency> | id, type |
<signal><reference>, <staticBoard><reference>, <vmsBoard><reference>, <sign><reference> | elementType, elementId, type |
<sign><positionRoad>, <sign><positionInertial> | as a signal’s |
<signals><signalReference> | id, s, t, orientation |
<signal><semantics>, <sign><semantics>, <roadRegulations><semantics>, <signalRegulations><semantics> | none |
<semantics><speed>, <semantics><supplementaryDistance> | type, value, unit |
<semantics><supplementaryTime> | type, value |
<semantics><lane>, <semantics><priority>, <semantics><supplementaryEnvironment> | type |
<semantics><prohibited>, <semantics><supplementaryAllows>, <semantics><supplementaryProhibits> | none |
<animal>, <person>, <vehicle> | none |
<person><type>, <vehicle><type> | its text |
<semantics><warning>, <semantics><routing>, <semantics><streetname>, <semantics><parking>, <semantics><tourist>, <semantics><supplementaryExplanatory> | none |
<signal><staticBoard> | none |
<staticBoard><sign> | id, name, country, countryRevision, type, subtype, value, unit, text, orientation, dynamic, invalidated, temporary, hOffset, pitch, roll, length, width, height, v, z |
<signal><vmsBoard> | displayType, displayWidth, displayHeight, v, z |
<vmsBoard><displayArea> | index, width, height, v, z |
<controller>, at the top level | id, name, sequence |
<controller><control> | signalId, type |
<junction><controller> | id, type, sequence |
<vmsGroup> | id |
<header><defaultRegulations> | none |
<defaultRegulations><roadRegulations> | type, and its <semantics> as a signal’s |
<defaultRegulations><signalRegulations> | type, subtype, and its <semantics> as a signal’s |
<vmsGroup><vmsBoardReference> | signalId, vmsIndex, groupIndex |
<validity>, under <object>, <objectReference>, <signal>, <signalReference>, <staticBoard>, <vmsBoard>, <sign>, <displayArea>, <tunnel> and <bridge> | fromLane, toLane, layer |
<object><parkingSpace> | access, restrictions |
<object><material> | surface, friction, roughness, roadMarkColor |
<object><userData> | code, value |
<object><repeat> | s, length, distance, bT, cT, dT, detachFromReferenceLine, and the Start/End pair of t, zOffset, length, width, height, radius |
<outlines><outline> | id, closed, outer, fillType, laneType |
<cornerRoad> | id, s, t, dz, height |
<cornerLocal> | id, u, v, z, height |
<skeleton><polyline> | id |
<vertexRoad> | id, s, t, dz, radius, intersectionPoint |
<vertexLocal> | id, u, v, z, radius, intersectionPoint |
<curveLocal> | id, u, v, z, height, hdg, length, and a <line>, <arc> or <paramPoly3> as in the plan view |
<markings><marking>, <outline><markings><marking> | side, color, weight, width, zOffset, lineLength, spaceLength, startOffset, stopOffset |
<borders><border> | type, width, outlineId, useCompleteOutline |
<cornerReference> | id |
<road><surface><CRG> | file, mode, purpose, orientation, sStart, sEnd, sOffset, tOffset, hOffset, xOffset, yOffset, zOffset, zScale |
<junction><surface><CRG> | file, mode, purpose, xOffset, yOffset, hOffset, zOffset, zScale |
<object><surface><CRG> | file, hideRoadSurfaceCRG, zScale |
Eight attribute values steer the import. Any other value falls back as shown:
<road rule>:LHT, else right-hand traffic. See Coordinate frame.<junction type>:direct,virtual,crossing, else common. A direct junction leads intolinkedRoad, a common one intoconnectingRoad. See Virtual junctions.<lane type>: theLaneType, elseLaneType::Unknown. No lane is dropped for its type.<link elementType>:junction, else road.contactPoint:end, else start.<paramPoly3 pRange>:arcLength, any case, else normalized.<laneSection singleSide>:trueor1, else every side.<lanes layer>:temporary, else permanent. See Lane layers.
Links and junctions resolve into a lane graph in the direction traffic
drives. A successor is a lane you can drive into from this lane’s exit end.
A lane section under 1 mm long, which many exporters write at a road’s end,
bakes no lanes, and links step over it. A <laneSection> without s starts
at 0.
A <laneSection singleSide="true"> gives only the sides it has elements
for. The spec doesn’t say what the other sides do. The crate carries them on
from the section before, so every section has both sides. A carried lane
keeps its records and their sOffsets, and each copy links to the next.
A direct junction joins roads end to end. The spec doesn’t say whether
traffic also flows back from the linked road. The crate links each
connection both ways unless the junction gives the way back itself. A
connection missing its incomingRoad or target road is dropped with a
Warning::ConnectionDropped.
A <junctionGroup>, such as a roundabout’s junctions, is a
JunctionGroup in RoadNetwork::junction_groups.
RoadNetwork::junction_groups_of gives every group of a road’s
Road::junction, since a junction may be in several. The router ignores
groups.
- A reference to a missing junction is dropped with a
Warning::JunctionReferenceDropped. A repeated one is dropped silently. - A missing or unknown
typeisJunctionGroupKind::Unknown, with aWarning::UnknownJunctionGroupType.
A <crossPath> is a pedestrian path across a junction’s roads. Each is a
CrossPath in RoadNetwork::cross_paths: the crossing road, and at
each end the lane it joins, its s, and the crossing road’s lane. It joins
lanes part way along, which Lane::successors can’t, so it sits beside
the lane graph. One naming a missing road or lane, or an s off the road,
is dropped with a Warning::CrossPathDropped.
A <junction type="crossing"> is where roads cross without joining, such
as a road and a railway. Each is a Crossing in
RoadNetwork::crossings, with a CrossingSection per <roadSection>:
the road, its stretch from sStart to sEnd, and each lane’s part as a
Coverage. An sEnd before sStart reads as the stretch between them.
A section naming a missing road, or an end off it, is dropped with a
Warning::RoadSectionDropped.
A junction’s <priority>s say which road gives way to which. Each is a
Priority in RoadNetwork::priorities, and
RoadNetwork::yields_to reads them for one road. One naming a road the
load didn’t bake is dropped with a Warning::PriorityDropped.
§Virtual junctions
A <junction type="virtual"> joins roads to a main road part way along it,
such as a driveway, without cutting it. Each is a VirtualJunction in
RoadNetwork::virtual_junctions, with its MainRoad and stretch, its
Orientation, and a VirtualLink where a road meets another part way
along. A link comes from a road link with an elementS, or a deprecated
<connection type="virtual">. Each side is a LinkPoint: a road end, or
an s and a direction.
- The router doesn’t follow these links. A connection whose incoming road is the main road adds no lane-graph link. Other connections read as in a common junction.
- Outside a virtual junction, a road link’s
elementSis ignored and itscontactPointused, as ASAM’sUC_ParamPoly3needs. - With no main road, a main road not in the load, or
sStartorsEndoff it, the junction keeps its links but has noMainRoad, with aWarning::VirtualJunctionWithoutMainRoad. The spec’s own example does the last. - A link naming a missing road, an
soff it, or anelementDirother than+or-is dropped with aWarning::VirtualLinkDropped.
The spec requires every road into a common junction to name it in its
<link>. Some files don’t, such as ASAM’s UC_X_Junction. The crate then
finds the end from the connecting road’s link back, at the end the
connection’s contactPoint names, and raises a
Warning::JunctionLinkMissing. A link back without a contactPoint, or
to an end already linked elsewhere, is not linked.
Each <object> bakes to one or more Objects in world coordinates, on
the road surface. An object stands upright: hdg turns it from the road’s
heading, pitch and roll from the horizontal, and zOffset raises it
straight up. With perpToRoad="true" it takes the road’s axes at its
origin instead, turned by hdg and raised along the normal, and ignores
pitch and roll.
The crate departs from the OpenDRIVE 1.9 spec here:
- The schema gives
pitchandrollagainst the horizontal. Figure 20 gives them in the road’s tilted frame. The crate follows the schema. - The spec says a
perpToRoadobject is perpendicular to the road at all points. The crate turns the whole object by the road’s axes at its origin, so a large outline doesn’t bend.
<repeat> sweeps and <cornerRoad> corners are in road coordinates and
rise straight up. <object type> gives the ObjectType, else
ObjectType::Unknown. The Shape:
- A plain object is a
Shape::Solid. Aradiusmakes itsExtenta cylinder.length,widthorheightmake a box, 0 where not given. The spec requires alength,widthandradiusabove 0 and aheightof 0 or more. The crate reads one outside that as not given, so aradiusof 0 doesn’t hide a box, and no solid is inside out. - A
<repeat>with adistancemakes aShape::Solideverydistancemetres. With adistanceof 0 it’s aShape::Sweepalong the road, such as a guard rail. Aradiusmakes the sweep a round pipe. - A repeat’s
truns straight fromtStarttotEnd. WithbT,cTordTit’s the cubictStart + bT ds + cT ds² + dT ds³, andtEndis ignored. Where the cubic ends over 1 mm fromtEnd, the crate raises aWarning::RepeatEndMismatch. The schema forbids negative coefficients. The crate departs from it and reads them as written. - With
detachFromReferenceLine="true", a repeat runs on the straight line between the ground at its two ends. Copies stand on the line.hdgandperpToRoadstill take the road’s heading and axes at eachs, since the spec detaches only positions.<cornerRoad>s move as if not detached. - Each
<outline>is aShape::Outline, read under<outlines>or, as in 1.4, straight under<object>. An object with outlines has no solid. - A
<skeleton>is aShape::Skeletonof<polyline>s, and replaces the solid too.<vertexRoad>and<vertexLocal>place as the matching corners do.RoadNetwork::object_meshdraws each segment as a frustum, mitred at bends up to about 140 degrees and squared beyond. A polyline with an unplaceable vertex, or under two, is dropped with aWarning::SkeletonDropped. An object left with nothing keeps its box. A missing or negative radius is 0. The spec’s text gives a vertex a width and height, but its schema only aradius. The crate reads the schema. - A
<curveLocal>is a line, arc or paramPoly3 in the object’s frame. Arcs and paramPoly3s are cut into edges of about 25 cm, at most 1024. Without alength, a curve runs to the next corner. A line withouthdgheads for the next corner, and other curves carry on the previous curve’s heading. The spec says each curve ends where the next starts:- where a curve’s
hdgleaves a gap that the previous heading would close, the crate uses that heading and raises aWarning::CurveHeadingIgnored. ASAM’sEx_SmoothObjectOutline_traffic_islandneeds this; - where a gap over 1 cm remains, the crate bridges it with a straight edge
and raises a
Warning::OutlineGap; - a paramPoly3 with
pRange="arcLength"and nolengthdrops its outline.
- where a curve’s
- Under a
<repeat>with adistance, outlines bake at every step.<cornerLocal>s follow the object’s frame,<cornerRoad>s shift with the step. The repeat’s dimensions don’t resize them. - An
outer="false"outline is a hole in the first closed outer outline of the object that encloses it. With afillTypeorlaneTypeit is also aShape::Outlineof its own. A plain one no outline encloses is dropped.
A junction’s <objects> stand along its <planView>, at z 0 plus
zOffset, since that line has no elevation. Object::lanes is empty, a
<surface> CRG covers the junction’s lanes, and
ObjectProvenance::junction_id names the junction. The spec allows that
line one <line>. The crate departs from it and bakes any road geometry.
Without one, the objects are dropped with a
Warning::JunctionObjectsDropped.
An <objectReference> bakes the object it names as if it stood at the
reference’s s, t and zOffset. Repeats and <cornerRoad>s move with
it. A reference to a missing id is skipped.
Object::lanes is the lanes along the object’s stretch, narrowed to its
<validity> ranges. A reference uses its own validities.
A <marking> becomes a Marking: a strip width wide along the edges
through the corners it names, dashed by lineLength and spaceLength. One
under an <outline>, as 1.9 writes it, belongs to that outline. One under
the object, as older versions write it, goes on the outline that has every
corner it names. A reference to a missing corner is skipped. With no corner
references it paints its side of a solid’s box.
A <border> becomes a Border, a band width wide, on the outline its
outlineId names or every outline it fits. It follows the whole outline
with useCompleteOutline, else the edges through its corner references.
Both lie on the surface under the edges: the road’s for <cornerRoad>, the
object’s plane otherwise, raised along the normal.
A closed outline with fillType="paint" is a painted area, such as an
arrow. The crate lays it flat, 5 mm above its corners. The spec says a
border cuts back a filled area. The crate departs from it and keeps the
full area. An open outline’s fillType does nothing.
<parkingSpace> becomes a ParkingSpace, each <material> a
Material, and each <userData> a UserData.
An Object keeps its subtype and whether it’s dynamic. Its road id,
id, (s, t), orientation and validLength are in its
ObjectProvenance, from load_str_with_provenance or
load_file_with_provenance, as LaneProvenance does for lanes.
ObjectProvenance::referenced_from names a reference’s original.
RoadNetwork::object_mesh meshes them. Markings and borders aren’t in
it. They’re already quads in Marking::pieces and Border::pieces.
Each <tunnel> and <bridge> is a Structure with no geometry. A
Coverage gives where it starts and ends on each lane, narrowed by its
<validity>s. RoadNetwork::structures_over finds them for a lane.
StructureProvenance has its road id, id, s and length.
Each <signal> is a Signal in RoadNetwork::signals. It keeps
country, type, subtype, value, unit and text as written, and
looks nothing up. Its board stands zOffset above the road at its (s, t),
which is Signal::applies_at. A + signal faces traffic along +s,
- or none the other way. hOffset turns it counter-clockwise. pitch
and roll are against the horizontal, so a board stays upright on a bank.
Angles wrap into (-π, π].
A <positionRoad> or <positionInertial> moves only the board. The signal
still applies at its own (s, t). One naming no road, or missing a
coordinate, leaves the board in place.
Signal::lanes is the lanes at s whose traffic runs the way
orientation says: along +s for +, against for -, all for none.
Two-way lanes are in both. Reversed and left-hand-traffic lanes get the
signals of their traffic, not their side. A <validity> replaces these
lanes. The spec says it must lie inside them, but esmini’s maps don’t, so
the crate departs from it. SignalProvenance has the road id, id,
(s, t) and orientation. A signal without s or t, or off its road, is
skipped.
A <signalReference> applies the signal on its own road too. Its lanes and
point join Signal::lanes and Signal::applies_at, and
SignalProvenance::references records it. With duplicate ids the first
signal wins. A reference to a missing id is skipped.
<dependency>s become Signal::dependencies, kept as written, since 1.7
and 1.9 disagree on which way they point. <reference>s become
Signal::references to a signal or the Objects an object baked to.
One to a missing id, or another elementType, is skipped.
<semantics> become Signal::semantics, a Semantic each, such as a
maximum speed or the RoadUsers barred. The crate applies only the speed
semantic, to RoadNetwork::speed_limits. See
Speed limits and road types. Unknown
children are skipped.
A <staticBoard> or <vmsBoard> makes the signal a board in
Signal::boards. A static board has a BoardSign per <sign>, and a
message board its display and DisplayAreas. Each stands where its v
and z put it on the board.
A sign’s own <validity>, <dependency>s and <reference>s override its
board’s, and a board’s override the signal’s. BoardSign::lanes,
BoardSign::dependencies and BoardSign::references take the nearest.
A sign with its own <positionInertial> or <positionRoad> stands there. A
sign’s dependency may name another sign on its board, a
SignTarget::Sign. A link to nothing baked is dropped with a
Warning::SignalLinkDropped. The crate departs from the spec here:
- A sign’s own validity applies where its signal stands, not where a
<signalReference>applies it. The spec doesn’t say. - The spec’s text gives a
<displayArea>a<validity>and dependencies, though its schema doesn’t. The crate reads them asDisplayArea::lanesandDisplayArea::dependencies, spelled<dependency>as for a signal, not<signalDependency>as in the spec’s example.
Each top-level <controller> is a Controller in
RoadNetwork::controllers, listed in each of its signals’
Signal::controllers. A <control> naming no signal is skipped. A
junction’s <controller> list is in each controller’s
ControllerProvenance.
Each <vmsGroup> is a VmsGroup in RoadNetwork::vms_groups: the
message boards on one gantry, with their vmsIndex and groupIndex. A
reference to no placed signal is dropped with a
Warning::SignalLinkDropped.
§Junction areas
A junction’s <boundary> and <elevationGrid> give the ground between and
around its roads. Each junction with either is a JunctionArea in
RoadNetwork::junction_areas.
JunctionArea::boundary is a closed ring on the road surface. A lane
segment runs along its boundaryLane’s outer border from sStart to
sEnd, or along the center line for lane 0. A joint segment runs across
its road at contactPoint, from jointLaneStart to jointLaneEnd.
JunctionArea::grid is a grid of heights along and across the
junction’s <planView>. JunctionArea::height_at reads it with the
spec’s bicubic interpolation. Slopes come from the cubic through four grid
points, or a straight line where there are fewer, so the ground can rise
between equal heights. JunctionArea::mesh triangulates the ground
inside the boundary at the grid’s spacing.
The crate departs from the OpenDRIVE 1.9 spec here:
- The grid overrides the elevation of the junction’s roads. The crate stands every road of the junction on it: elevation, superelevation and shape give way to the grid, and lane heights add to it. Where the grid doesn’t reach, which the spec forbids, the road’s own elevation holds. This applies to any junction type, though the spec gives grids to common junctions only.
- A
jointwith atransitionLengthblends the incoming road into the grid with the spec’s cubic. The spec divides the slopes by the zone’s depth. The crate multiplies, which makes the cubic meet both slopes, and reads the spec as a typo. The road’s height at the joint excludes lane heights. A joint without alanesegment each side gets no blend, with aWarning::TransitionDropped. - Segments must close the boundary. The crate joins them straight, with a
Warning::BoundaryNotClosedwhere two ends are over 10 cm apart. A segment naming a missing road or lane is dropped with aWarning::BoundarySegmentDropped. - Segments run counter-clockwise. A clockwise boundary is reversed, with a
Warning::BoundaryClockwise. - A joint runs from
jointLaneStarttojointLaneEnd. Where that leaves a gap, the crate reverses it, as it does a lane segment. - A missing
sStartis 0. A row withoutcenteris skipped. - The spec allows any
<planView>geometry. The crate reads a grid only along one straight<line>with agridSpacingabove 0, else drops it with aWarning::ElevationGridDropped. - The spec’s height formula swaps rows and columns between its matrix and
its product of powers. The crate follows the product, with
salong the rows.
§Railways
Each railway <switch> is a Switch in RoadNetwork::switches: where
it sits on the main track, where the side track leaves, its setting, and
its Partner. Each point is a TrackPoint. Like a cross path, a switch
sits beside the lane graph.
Each <station> is a Station in RoadNetwork::stations, with its
platforms and the track each runs beside. A switch or platform segment
naming a missing road, an s off it, an sEnd before sStart, no
position, or a dir or side the spec doesn’t allow, is dropped with a
Warning::RailwayDropped. The spec allows three positions. The crate
keeps a switch with any other as SwitchPosition::Unknown, as it keeps
an unknown object type.
§Lane layers
A road has a permanent lane layer and may have a temporary one, as for road
works. Each is a <lanes> with its own sections and <laneOffset>.
Lane::layer gives a lane’s layer. Section indexes count permanent
sections first, as in LaneProvenance::section. A temporary section’s
length ends it early. A second <lanes> of one Layer raises a
Warning::Ignored. Temporary lanes have their own speed limits, rules,
access, materials and visibility.
- Only the permanent layer defines the surface.
RoadNetwork::surface_meshandRoadNetwork::road_pointfollow it.RoadNetwork::temporary_meshhas the temporary lanes, to draw on top. A temporary lane past the permanent surface isn’t clipped. - A lane
<link>may name lanes on either layer, so traffic moves onto the temporary layer and back. A junction<laneLink>usesfromLayerandtoLayer. - A
<validity layer>picks that layer’s lanes, one without picks the permanent layer. An object or signal with no<validity>applies to both. - Temporary lanes take precedence for driving, as the spec says.
RoadNetwork::nearest_lane,RoadNetwork::lane_position,RoadNetwork::routeandRoadNetwork::advancefind a temporary driving lane that holds the point. A temporary lane traffic may not use hides the lane under it fromRoadNetwork::nearest_lane. Each has a_withform taking aLayerPolicy:LayerPolicy::Both, the default, orLayerPolicy::PermanentOnly.
The crate departs from the OpenDRIVE 1.9 spec here:
- A link with no
layermeans the permanent layer. The crate keeps it on the lane’s own layer if that layer has a next section, so a temporary layer’s sections join. - A road with only a temporary
<lanes>bakes it as the permanent layer. - A permanent
<laneSection>’slength, which the spec forbids, is ignored.
§Lane borders
A lane’s <border>s give the t of its outer border, measured from the
reference line. Its width is that less the inner neighbour’s outer border,
so a lane can open out of nothing. Lane::width and Lane::widths
follow. A width lane outside a border lane stacks on it.
The crate departs from the OpenDRIVE 1.9 spec here:
- Widths and borders are exclusive, and widths win in a section with both.
The crate reads each lane on its own: widths if it has any, else borders.
A lane with borders in a section with widths raises a
Warning::WidthAndBorder. - Borders are forbidden with a
<laneOffset>. The crate ignores the offset for borders, with aWarning::BorderWithLaneOffset. - A border inside the lanes within it gives the lane 0 width, with a
Warning::BorderCrossesInnerLane. - A record without
ais skipped. A missingsOffset,b,cordis 0. Records out of order are sorted.
§Lateral shapes
A road’s <shape>s give its cross-section, such as a crown. The shapes at
one s form a profile of cubics in t. Between profiles, height varies
linearly in s, along the road’s normal.
Each lane border stands on the shape plus the lane’s <height>, and the
lane is straight between its borders. Lane::bank takes the slope. The
mesh stays closed. A crown that breaks on a border is exact. A curve inside
a lane is lost: c w² / 4 for a parabola c t², 5.5 mm on a 3.5 m lane of
a 2.5 % crown. Objects, signals and marks stand on the shape as meshed.
LaneProvenance::heights gives the <height>s only.
The crate departs from the OpenDRIVE 1.9 spec here:
- The default shape is 0, so the road would step up to the first profile. The crate holds the first profile before it and the last after it.
- Each profile covers the road. Where one starts inside the right edge, the
first shape’s value holds out to the edge, with a
Warning::ShapeShortOfRoad. - The surface curves between borders. The crate’s is straight, as above.
- A lane height includes the shape, but an
attachedCRG adds to the road without it. - A shape without
sortis skipped. A missinga,b,cordis 0. Shapes out of order are sorted.
A <crossfall>, from OpenDRIVE 1.4, folds in as a shape does. The road
falls from its reference line at an angle, a cubic in s, on the side it
names: height -tan(angle) * |t|. Any side other than left or right
means both. A crossfall and shapes add.
§Cross-section surfaces
A <crossSectionSurface> is another way to give the cross-section: up to
two strips each side, shifted by a <tOffset>. A strip’s height is a cubic
in dt, whose coefficients <constant>, <linear>, <quadratic> and
<cubic> are cubics in s. An inner strip, id 1 or -1, reaches its
<width>. An outer strip, 2 or -2, runs on to the road’s edge, on the inner
strip’s edge for mode="relative" or the reference plane for
independent.
It bakes as Lateral shapes do. Level lanes keep out of
it. Where the two sides differ at dt 0, each lane uses its own side.
The crate departs from the OpenDRIVE 1.9 spec here:
- A surface with
<shape>s or<superelevation>is forbidden. The crate adds them, with aWarning::CrossSectionWithShape. - A missing or unknown outer
modeisindependent, the unknown one with aWarning::UnknownStripMode. - A strip with another
id, a repeatedid, or an outer strip without an inner one of known width is dropped with aWarning::StripDropped. - Past an inner strip with no outer strip, the inner one runs on. A side with no strip is flat.
- The spec’s left-side rule reads
t_effective < w_leftfor the outer strip. The crate reads>, mirroring the right side.
§Level lanes
A level="true" lane is kept out of superelevation and shape. It runs
level from its inner neighbour’s outer border, so its Lane::bank is 0.
Its <height>s add on top. It’s built from the tilted cross-section, so in
plan it is w / cos φ wide: 2.5 mm more on a 2 m lane at 5 %.
The crate departs from the OpenDRIVE 1.9 spec here:
- Every lane outside a level lane must be level. The crate holds it level
anyway, with a
Warning::LaneNotLevel. - A level lane starts at its neighbour’s border height, including the
neighbour’s
<height>.
§Lane heights
A lane’s <height>s raise it off the road, as a sidewalk stands above the
lanes beside it. Each gives the height at the inner and outer border from
its sOffset. The centerline rises by the mean, and Lane::bank takes
the slope, so the mesh and Lane::sample_at see the raised surface.
LaneProvenance::heights gives them per centerline vertex. A change of
pace gets a station, so a 1 m ramp bakes 1 m long.
The mesh tilts a raised lane’s cross axis rather than moving each edge, so on a grade each edge shifts along the road by half the rise times the grade: 1.5 mm for 0.1 m at 3 %. Where the two borders ramp at different paces, a quad twists and misses the surface by up to a quarter of the rise: 25 mm halfway up a 0.1 m ramp. The step up to a raised lane is left open.
Objects, signals and marks stand on the lane under them. A kerb mark
belongs to the lane below, so it stays on the road. A perpToRoad object
leans with the road, not the lane.
The crate departs from the OpenDRIVE 1.9 spec here:
- Heights hold until the next. The crate ramps linearly between them, as esmini’s maps expect, and holds the last after it.
- The first height also holds before it.
- A missing
sOffset,innerorouteris 0, and a negativesOffsetis 0. - Heights out of order are sorted.
- Heights on the center lane, which the spec forbids, are ignored.
- The spec doesn’t say what stands on a raised lane. The crate stands objects, signals and marks on it.
- A point on the border between two lanes is on the inner one.
- Past the outermost lane, a point takes that lane’s outer height.
- A height includes the surface, but an
attachedCRG adds to the road without it.
§Road marks
Each <roadMark> is a RoadMark in RoadNetwork::road_marks, along
its lane’s outer border from its sOffset to the next mark or the
section’s end. The center lane’s run along the center line.
RoadMark::left and RoadMark::right name the lanes either side,
looking along +s. type is a RoadMarkType, laneChange a
LaneChange, and color stays text. RoadMarkProvenance has its
road, section, lane, s and length.
RoadMark::lines are quads on the lane mesh. Each <type><line> or
<explicit><line> is a RoadMarkLine with a width, colour,
LinePattern and LineRule, offset by tOffset from the border. A
<type><line> repeats, an <explicit><line> paints once. A mark with no
lines gets stand-ins: one line for solid and broken, two for double
types. <sway>s shift the lines sideways. A mark at the same sOffset as
the next is replaced by it, with a Warning::RoadMarkDropped.
The crate departs from the OpenDRIVE 1.9 spec here:
- A missing
color,typeorsOffsetisstandard,noneor 0. An unknowntypeisRoadMarkType::Unknown. - A negative
sOffsetis 0. - A missing
weightis standard. - A width of 0 counts as none, so the next applies: line, type, mark, then
weight. esmini writes 0 on all three. A
RoadMark’s own width is its<type>’s, which the spec says supersedes the<roadMark>’s. - A line with a
lengthand aspaceof 0 is continuous, not empty. Otherwise every mark in esmini’smulti_intersections.xodrvanishes. So is one with alengthand nospace, as its dashes touch. - A
nonemark paints nothing, even with lines. tOffsetand<sway>move along +t on either side. Nothing sways before the firstds.- A missing
ruleisLineRule::None. - A line is 0.12 m wide, 0.25 m bold.
brokenis 4 m dashes with 8 m gaps. Double lines sit one width either side of the border.none,edge,grass,curb,botts dotsandcustompaint nothing. - Dash lengths are measured along the reference line.
- Marks out of order are sorted.
- A lane with no
<width>or<border>is dropped with its marks, with aWarning::LaneDropped.
§Speed limits and road types
RoadNetwork::speed_limits and RoadNetwork::road_types are Along
stretches along each lane’s centerline. RoadNetwork::speed_limit_at and
RoadNetwork::road_type_at read them at a point. A limit is in m/s, or
SpeedLimit::Unlimited. Where the map says nothing, there’s no stretch.
- A road’s
<type>, and its<speed>, hold from itssto the next or the road’s end. Itscountryis inRoadNetwork::road_countries.max="undefined"sets nothing. - A lane’s
<speed>holds from itssOffsetto the next or the section’s end, and overrides the road’s. - A
<speed>withoutunitis in m/s. Header::default_regulationsholds<defaultRegulations>. The firstmaximumspeed of a road type’s<roadRegulations>applies where the road’s<type>and lanes give none. A road with no<type>gets none.<signalRegulations>are kept only. The crate also readssubType, as the spec’s example spells it.- A speed limit sign overrides the records, since the spec says limits from
signals take preference. A
<speed>semantic of typemaximumorzonestarts a limit, andmaximumEndorzoneEndends one. It runs from the sign, and each<signalReference>, along each lane it applies to in the direction of travel, to the next speed sign. Where it differs from the record it overrides, the crate raises aWarning::SpeedLimitDisagrees.
The crate departs from the OpenDRIVE 1.9 spec here:
- The spec doesn’t say how far a sign reaches. The crate stops it at the next speed sign or the road’s end, and not through a junction.
- Files before 1.8 have no
<semantics>, so their signs set no limit. The crate doesn’t read limits from country sign codes. - A
zonespeed is a maximum untilzoneEnd.minimumandrecommendedset nothing. - A two-way lane takes the direction its sign faces.
- A
<speed>outside the spec’s values or units, or too large for anf32, is dropped with aWarning::SpeedLimitDropped. The road’s or the previous limit holds there. - A
<type>withoutsis skipped. A missing or negativesOffsetis 0. Records out of order are sorted. - An unknown
typeisRoadType::Unknown.
§Lane rules, access and materials
RoadNetwork::lane_rules, RoadNetwork::lane_access and
RoadNetwork::lane_materials are Along stretches of each lane’s
<rule>s, <access>es and <material>s, with *_at methods. Each holds
from its sOffset to the next of its kind or the section’s end.
- A rule is free text. One without
valueis skipped. Rules at the samesOffsetjoin with"; ". Access::Allowlists the only road users allowed,Access::Denythose barred. A lane with no access stretch is open to all. Adenyof onlynonelifts earlier restrictions. Adenyofnoneand others denies the others.- Files before 1.8 name one user per
<access>inrestriction. Entries at onesOffsetmerge, in any order. Theirallows merge into one, less the denied users. - Of two materials, speeds or visibilities at one
sOffset, the later wins. - A material is a
Material. A negative or overflowing friction or roughness reads as none. Its friction is unused. A CRG gives friction throughRoadSurface.
The crate departs from the OpenDRIVE 1.9 spec here:
- An
<access>withoutrule, or with one other thanallowordeny, is dropped with aWarning::AccessDropped. The lane is open up to the next. - A missing or negative
sOffsetis 0. Entries out of order are sorted.
§Lane visibility
RoadNetwork::lane_visibility gives how far a driver can see from each
lane, as Along stretches of a Visibility: ahead, behind, left and
right, in metres. RoadNetwork::lane_visibility_at reads it at a point.
Each <visibility> holds from its sOffset to the next or the section’s
end.
OpenDRIVE 1.9 doesn’t define <visibility>. The crate reads sOffset,
forward, back, left and right, as CARLA does:
- The distances stay as named. Whether
forwardmeans traffic’s way or+sis undefined. - One with a distance missing, not a number, negative or too large for an
f32is dropped with aWarning::VisibilityDropped. - A missing or negative
sOffsetis 0. Entries out of order are sorted.
§Road surfaces
Each road or junction <surface><CRG> is a CrgSurface in
RoadNetwork::crg_surfaces. The importer reads the record, not the file.
RoadSurface::new loads the files through your closure, and
RoadSurface::sample gives height, normal and friction under a point in
f64. Off the CRG, the surface mesh answers. The CRG doesn’t change the
mesh.
Where several records of one purpose cover a point, the last wins, per rule
road.crg.use_last_entry. Junction records come after road records, so
they win.
Modes:
attachedlays the grid along the road and adds its height. The spec’s formula includes the file’s reference line height, slope and bank, but its text says to disregard them. The crate follows the text.attached0lays it the same way, replacing the road’s height.genuinestarts the file’s reference line at(sOffset, tOffset), turned byhOffset.globalkeeps the file’s coordinates, moved byxOffset,yOffsetandhOffset.
Along the road, u = s - sOffset and v = t - tOffset. The reference line
is sampled every 0.25 m and joined with arcs. That is exact on lines and
arcs, and within a micrometre on a spiral reaching a 50 m radius in 50 m.
orientation="opposite" negates u and v. The spec’s matrix also swaps
them, contradicting its text. The crate follows the text.
A road CRG covers sStart to sEnd. A junction CRG covers the lanes of
the junction’s roads and must be global. Other modes are skipped there.
purpose is elevation unless it says friction. Any other is dropped
with a Warning::CrgDropped. A friction CRG ignores zOffset and
zScale, and skips OpenCRG’s height shift, giving the file’s values as is.
An object’s <surface> CRG is a CrgMode::Object record per box. Its
(u, v) are the object’s own. Inside the box it adds zScale times the
file’s height to the surface below and tilts the normal. With
hideRoadSurfaceCRG, true by default, it hides an attached road CRG
there. zOffset and height play no part. It covers its own road’s lanes,
or a junction object’s junction roads.
The crate departs from the spec here:
- The spec turns the file with the object. The crate uses the heading alone, so a pitched or rolled object’s file lies flat.
hideRoadSurfaceCRGover another mode is forbidden. The crate keeps the road CRG, adds the object’s, and raises aWarning::CrgHideIgnored.- A surface on anything but a box raises a
Warning::ObjectSurfaceDropped.
§Included files
An <include> is replaced by the children of the included file’s root,
which must match the <include>’s parent. Nested includes are read too.
load_filereads from the map’s folder or below, and refuses paths out of it, links followed.load_str_withreads through your function.load_strreads none.
Includes nest at most 8 deep and total at most MAX_INCLUDED_BYTES. One
that can’t be read is left out with a Warning::IncludeDropped, whose
IncludeProblem says why.
§What the importer ignores
The crate raises one Warning::Ignored per feature below in each road,
junction, and the rest of the document, with a count.
Warning::is_ignored tells these from faults.
- a second
lanesof oneLayeron a road. The first is kept; - a
roadSectionof a junction that isn’t a crossing.
The center lane, lane 0, never becomes a Lane. Its road marks are read,
and its id, type, level and link are kept as a
CenterLaneProvenance in Provenance::center_lanes. The lane graph
doesn’t follow its link.
§Kept for the caller
These are kept but build nothing:
- every
<userData>and<dataQuality>, on any element, as anAdditionalDatainProvenance::additionalwith its element’s path and road. Nothing inside a<userData>is read. An object’s is also inObject::user_data; - the
<header>inRoadNetwork::header, with its<license>inHeader::license; - a road’s
nameinRoad::name, a junction’s inProvenance::junctionsas aJunctionProvenance; - a road type’s
country, inRoadNetwork::road_countries; - a road mark’s
materialand typename, inRoadMarkProvenance; - a lane’s
advisoryas aLaneAdvisory,dynamicLaneType,dynamicLaneDirectionandroadWorks, inLaneProvenance; - the center lane’s attributes, as above;
- an object’s
invalidated,temporary, markingweight, materialroadMarkColor, outlinefillTypeandlaneType, andSkeletonIds, inObjectProvenance.fillType="paint"also lays the outline flat; - a sign’s own attributes, as a
SignProvenanceinSignalProvenance::signs; - a switch’s
Partner; - a junction
<laneLink>’soverlapZone, as aLaneLinkOverlapinProvenance::lane_link_overlaps.
§Coordinate frame
OpenDRIVE’s own frame: right-handed, Z up, metres, the reference line
in the X-Y plane and elevation along +Z. A coordinate in the .xodr is the
coordinate you get back. A left turn curves toward +Y, and t is positive
to the left. A Y-up engine rotates on the way in.
Traffic follows each road’s rule. With right-hand traffic, the default,
negative (right) lanes run along +s. With rule="LHT" the left lanes do.
Links, lane changes and a signal’s orientation follow. Any value other
than RHT or LHT reads as RHT, with a Warning::UnknownTrafficRule.
A lane’s direction overrides its side. reversed runs it against its
side, and both makes it a Direction::Both lane. A deprecated
type="bidirectional" lane without direction is two-way too. Any other
value reads as standard, with a Warning::UnknownLaneDirection.
Two joining two-way lanes lead into each other both ways, even where only
one names the other. A two-way lane’s successors are the lanes off either
end that run away from it. The lane graph links lane changes only between
lanes running the same way. RoadNetwork::left_of and
RoadNetwork::may_change_left don’t check this.
RoadNetwork::route drives a two-way lane toward the next lane on the
route, and RoadNetwork::advance goes both ways.
§Road coordinates
RoadNetwork::roads keeps each baked road. A RoadPosition is a road,
s along its reference line and t across it.
RoadNetwork::road_point turns one into a point on the surface, and
RoadNetwork::road_position turns a point back.
RoadNetwork::road_lane gives a lane’s road, section and <lane id>.
RoadNetwork::road_by_od_id finds a Road by its <road id>.
use xodr::{load_file, RoadPosition};
let net = load_file("maps/town07.xodr")?;
let road = net.road_by_od_id("5").expect("road 5").id();
let point = net.road_point(RoadPosition { road, s: 10.0, t: -1.75 });
let back = point.and_then(|p| net.road_position(p));The surface includes elevation, superelevation, shape and lane height. t
runs along the tilted cross-section, so on a bank φ it is t cos φ in
plan. Signals, objects and marks are placed through the same call. The
forward call is exact to f32.
- The inverse takes the road whose surface is nearest in 3D, so a point on
a bridge finds the bridge. Where roads overlap in a junction, any may come
back.
RoadNetwork::road_position_onpicks the road. - A point off every road gets the nearest road’s
(s, t), withsclamped. - Round trips agree to 0.2 mm on the test maps, or the
f32step where that’s larger: 0.5 m in UTM coordinates. - At a section seam where
<height>steps, the seam belongs to the section starting there. - A network from
RoadNetwork::newhas no roads, so road queries answerNone. - Where a road bends tighter than its lanes’ half-width, a point can have two road positions. The crate returns one.
§Lane positions
A LanePosition is a lane, a road s, and an offset from the lane’s
center toward +t. RoadNetwork::lane_point and
RoadNetwork::lane_position convert both ways.
Two kinds of s exist. LanePosition, RoadPosition, signals and
objects use the reference line’s. Projection, Along stretches and
Lane::sample_at use distance along the baked centerline. On bends they
drift apart, up to 21 % on the test maps. RoadNetwork::centerline_s
converts.
RoadNetwork::nearest_lane projects onto the baked centerline, sampled
at most 2 m and 0.05 rad apart. It is within 6 mm of the exact center at
the 95th percentile. RoadNetwork::lane_position is exact and about ten
times slower.
§Moving along the lanes
RoadNetwork::advance moves a LanePosition a distance along the
lanes, the way traffic runs, or back for a negative distance. It returns
one Advance per branch. A branch that runs out of lanes is an
Advance::DeadEnd with the distance left.
for branch in net.advance(here, 25.0) {
let ahead = net.lane_point(branch.position());
}The distance is along lane centerlines, as a vehicle travels. The offset keeps its side of traffic, so it flips sign onto a road running the other way.
Branches multiply at every fork and don’t merge. From one lane of Town07, 2 km gives 72,912 places in about 150 ms, and each further 400 m about seven times more. Nothing caps it. Step a few metres at a time and pick a branch at each fork. An infinite or NaN distance gives none.
RoadNetwork::left_of and RoadNetwork::right_of step to the lane
beside, relative to the lane’s traffic.
RoadNetwork::may_change_left and RoadNetwork::may_change_right read
the border mark’s LaneChange. increase allows crossing toward the
higher <lane id>, decrease toward the lower. They answer None with no
lane beside, no mark, or an unknown laneChange. Where one mark ends and
the next begins, the next answers. laneChange applies whatever the mark’s
type, so a curb with the default both allows crossing.
§Geo reference
RoadNetwork::geo_reference gives the <geoReference> PROJ string and
<offset> as written, and applies neither. To place the map on the earth,
apply the offset, then the projection.
The spec rotates by the offset’s hdg, then adds x, y and z.
netconvert writes the opposite direction, so check the sign against a
known point. A missing or unreadable offset value is 0. A blank
<geoReference> is none, meaning a local frame.
§Robustness
A road the importer can’t read is skipped, not fatal. load_str errors
only if no lane comes out. Non-finite numbers such as NaN and 1e400 are
rejected as read, as is a number too large for the f32 it’s stored in.
A road over MAX_LENGTH, or past MAX_BAKED_LENGTH of lanes in the
file, is skipped with a Warning::RoadSkipped.
Provenance::warnings says what the load did. Each Warning names
where it happened and prints as a sentence. The Warning enum documents
every kind. The crate prints nothing.
Two drops raise no warning, since exporters write them and nothing is lost: a lane section under 1 mm long inside its road, and a road mark at or past its section’s end.
§Importer contract
Code baking other map formats into a RoadNetwork must:
- build lane geometry with
Polyline::try_newand return an error on bad input, not call the panickingPolyline::new; - build contiguous lanes split from one curve with
Polyline::try_new_with_tangents, passing the exact end tangents, or the joint shows a seam; - treat
LaneIds as opaque, not as indexes.
RoadNetwork::surface_mesh pulls in the inner edge on curves tighter
than the half-width, so the surface doesn’t fold. The outer edge keeps its
width.
Re-exports§
pub use opencrg;
Structs§
- Additional
Data - One
<userData>or<dataQuality>, with where in the file it is. - Along
- A value that holds on part of one lane, from
fromtotometres along its centerline. Distances start at the lane’s first point, as inCoverage. A network leaves out a stretch whosefromortois NaN, since it covers no point. - Board
Sign - One
<sign>on a static board: its catalogue codes and meaning, as on aSignal, and where it is. - Border
- A band along edges of an object’s outline, such as the kerb round a traffic island, centred on the edges.
- Center
Lane Provenance - What a lane section’s center lane, lane 0, says about itself. It never
bakes to a
Lane, so its attributes are kept here. - Control
- One signal a
Controllercontrols. - Controller
- A group of signals that always show the same state, such as the lights of one approach to a junction. The map does not say what they show, or when.
- Controller
Id - An opaque controller identifier. Not a position in
RoadNetwork::controllers, so look controllers up withRoadNetwork::controller. - Controller
Provenance - The OpenDRIVE identity of one baked signal controller: the top-level
<controller>it came from, and the junctions that list it. - Corner
- One point of an outline or a sweep: where it meets the ground and where its top edge is, both in the network’s frame.
- Coverage
- The part of one lane a structure covers, from
fromtotometres along the lane’s centerline. Distances start at the lane’s first point, as inPolyline::point_at. - CrgAlong
- How a CRG file’s
(u, v)follow the road’s(s, t)in theattachedandattached0modes:u = s - s_offsetandv = t - t_offset, both negated ifopposite. - CrgObject
- Where an object’s
<surface>CRG lies, from the object. - CrgPose
- A position and heading in the map’s frame.
- CrgSurface
- One
<CRG>under a<road>or<junction><surface>. - Cross
Path - A path across a junction’s roads for pedestrians, from an OpenDRIVE
<crossPath>: a crossing road, and the lanes it joins at each end, part way along them. - Cross
Path End - One end of a
CrossPath: the lane of another road it joins, where along that road, and the lane of the crossing road there. - Cross
Path Provenance - The OpenDRIVE identity of one cross path: the
<junction>and the<crossPath id>it came from. - Crossing
- A crossing, from an OpenDRIVE
<junction type="crossing">: where two or more roads cross at one level, such as a road and a railway, and traffic cannot change from one to the other. It has no connecting roads, only the stretch of each road where traffic crosses. - Crossing
Section - One road’s stretch through a
Crossing, from a<roadSection>. - Data
Error - The error range of measured data, in metres, from an
<error>. A number the file leaves out or can’t give isNone. - Data
Quality - A
<dataQuality>: its<error>and<rawData>, where it gives them. - Default
Regulations - The rules a map sets once for all its roads and signs, from its
<defaultRegulations>, such as the speed limit on a rural road where it is drawn. A road’s, a lane’s or a signal’s own rules override them. - Dependency
- A signal another depends on.
- Display
Area - A
<displayArea>of aMessageBoard. - Elevation
Grid - A junction’s
<elevationGrid>: heights at evenly spaced points along the junction’s reference line and square to it, and the surface through them. - GeoOffset
- A
<header><offset>. The spec takes a point from the map’s frame to the PROJ frame by rotating it byhdgabout z, then addingx,y,z. Some exporters write the opposite sign, so check a map before relying on it. - GeoReference
- A map’s
<header><geoReference>and<header><offset>, as the file gives them. The crate applies neither:Lanepoints stay in the file’s own frame. See Geo reference. - GridRow
- One row of an
ElevationGrid: the heights at its points, square to the junction’s reference line. - Header
- A map’s
<header>, as the file gives it. The crate reads none of it to decide how to read the map, so the version in particular changes nothing about what bakes. See Which OpenDRIVE version. - Junction
Area - A junction’s area, from an OpenDRIVE junction’s
<boundary>and<elevationGrid>: the edge of the ground its traffic may use, sidewalks included, and the height of that ground. - Junction
Controller Provenance - One entry of a
<junction>’s<controller>list. - Junction
Group - Junctions that routing should see as one, such as the junctions round a
roundabout, from an OpenDRIVE
<junctionGroup>. - Junction
Provenance - What a
<junction>says about itself: itsid, and thenamethe network keeps nowhere else. - Lane
- One lane: a strip of road surface described by its centerline and width.
Not necessarily drivable; a sidewalk and a median are lanes too, and
Lane::kindis what separates them. - Lane
Height - How far a lane’s surface stands off the road at one station, from its
<height>s: along the road’s normal, at the lane’s inner and outer border, in metres. The spec gives only these two. The lane goes straight across from one to the other, as libOpenDRIVE and esmini read it. - LaneId
- An opaque lane identifier. Not a vector index into
RoadNetwork.lanes. An importer may assign arbitrary ids, such as OpenDRIVE lane keys, so look lanes up withRoadNetwork::lane, never by position. - Lane
Link Overlap - A junction
<laneLink>’soverlapZone: how far the traffic of two lanes that overlap shares the space, which the spec intends for direct junctions. The crate keeps it and uses none of it. - Lane
Position - A place on a lane:
salong its road’s reference line, andoffsetacross from the lane’s center, as esmini’sSetLanePostakes them. - Lane
Provenance - The OpenDRIVE identity of one baked lane: which road, lane section, and
original
<lane id>it was tessellated from. - Lane
Span - The slice of a
Meshbelonging to one lane: a half-open range intovertices(and, in step,normals) and one intoindices. - License
- A map’s licence, from its header’s
<license>, as the file writes it. A value it leaves out is empty. - Main
Road - The road a
VirtualJunction’s roads branch off, and the stretch of it the junction spans. - Marking
- Paint on an object, such as the stripes of a crosswalk: a strip along edges of its outline or one side of its box, solid or dashed, centred on the edges.
- Material
- What an object’s or a lane’s surface is made of.
- Mesh
- A triangle mesh (Z-up, meters): per-vertex positions and normals, plus
triangle indices. The road surface from
RoadNetwork::surface_mesh, or the objects fromRoadNetwork::object_mesh, shared by the physics collider (which needs only positions) and a renderer (which needs normals for lighting). - Mesh
Sampler - A mesh plus a ground-plane index over its triangles. Borrows the mesh, so it cannot outlive or diverge from the geometry it describes.
- Message
Board - A
<vmsBoard>: a display that shows what a scenario tells it to. - Object
- One object in the world.
- Object
Id - An opaque object identifier. Not a position in
RoadNetwork::objects, so look objects up withRoadNetwork::object. - Object
Provenance - The OpenDRIVE identity of one baked object: which road and
<object>it came from, and where on that road it is anchored. - Object
Span - The slice of a
Meshbelonging to one object: a half-open range intovertices(and, in step,normals) and one intoindices. - Parking
Space - Who may use a parking space, and on what terms.
- Partner
- A switch’s
<partner>. - Platform
- One
<platform>of aStation, along one or more stretches of track. - Platform
Segment - A stretch of track a
Platformruns beside. - Point
- A place in the world: right-handed, Z-up, metres.
- Polyline
- A polyline in 3D (Z-up, meters), queried by arc length. This is the baked form every curve reduces to: an importer samples clothoids/arcs into points; consumers only ever see the points. At least two points.
- Pose
- A position plus a horizontal heading along a lane. Z is up (elevation).
- Priority
- One road giving way to another where both are in the same junction, from
an OpenDRIVE junction
<priority>. - Priority
Provenance - The OpenDRIVE identity of one junction priority: the
<junction>whose<priority>gives it. - Projection
- The result of projecting a world point onto a polyline.
- Provenance
- The OpenDRIVE identity of everything a load baked, from
load_str_with_provenanceorload_file_with_provenance. - RawData
- Where measured data came from, from a
<rawData>, as the file writes it. A value it leaves out is empty. - Reference
- Something a signal relates to.
- Road
- One road: its reference line, the profiles along it, and where its lanes
lie across it. What turns a
RoadPositioninto a point, and back. - RoadId
- A road’s identity: its position in
RoadNetwork::roads. Look a road up withRoadNetwork::road. - Road
Lane - Where a lane lies on its road: the road, the lane section, and its
OpenDRIVE
<lane id>. - Road
Mark - One road mark: the paint along a stretch of one lane border, and what it tells traffic about crossing it.
- Road
Mark Id - An opaque road mark identifier. Not a position in
RoadNetwork::road_marks, so look marks up withRoadNetwork::road_mark. - Road
Mark Line - One painted line of a road mark.
- Road
Mark Provenance - The OpenDRIVE identity of one baked road mark: which road, lane section
and
<lane>its<roadMark>is on, and the stretch of road it covers. - Road
Neighbor - A road running beside another, from an OpenDRIVE road
<neighbor>: the road that names it, which side of that road it is on, and whether it runs the same way. - Road
Network - The “compiled map”: everything a consumer needs, baked and format-agnostic.
- Road
Position - A place on a road in its own coordinates, as OpenDRIVE gives them.
- Road
Regulation - The rules for one type of road, from a
<roadRegulations>. - Road
Sample - The road surface at one station: where a body sits and how it is oriented on
a (possibly canted) road, plus the bank angle a vehicle model consumes. This
is what draping a body onto the road needs. See
crate::Lane::sample_atandcrate::RoadNetwork::sample_near. - Road
Surface - The road surface a vehicle drives on: the surface mesh, refined by the map’s OpenCRG files where they cover it.
- Section
- One cross-section of a
Shape::Sweep: its two edges at one station.leftis the edge toward +t, left of the road’s reference line heading. - Sign
Dependency - A dependency of a
BoardSign. - Sign
Provenance - What a
<sign>on a static board says about itself that the crate builds nothing from. It turns a sign by none of its angles. - Signal
- One signal: what it means, the lanes it applies to, and the board it is.
- Signal
Id - An opaque signal identifier. Not a position in
RoadNetwork::signals, so look signals up withRoadNetwork::signal. - Signal
Provenance - The OpenDRIVE identity of one baked signal: which road and
<signal>it came from, and where on that road it takes effect. - Signal
Reference Provenance - A
<signalReference>: a road, and a station on it, where a signal also applies. The signal itself stands where its<signal>puts it. - Signal
Regulation - The rules for one type of sign, from a
<signalRegulations>. - Skeleton
Ids - The
idof one<skeleton><polyline>and of each of its vertices, in order. Each is empty where the map gives none. - Skeleton
Vertex - One vertex of a
Shape::Skeletonpolyline. - Station
- A railway station, from a
<station>, and its platforms. - Structure
- A tunnel or a bridge, and the lanes it covers.
- Structure
Id - An opaque structure identifier. Not a position in
RoadNetwork::structures, so look structures up withRoadNetwork::structure. - Structure
Provenance - The OpenDRIVE identity of one baked tunnel or bridge: which road and
<tunnel>or<bridge>it came from, and the stretch of road it spans. - Surface
Hint - Search state for one moving point, such as a wheel, passed to
RoadSurface::sample. Each query starts where the last one ended, so a point that moves a few metres per step is found without scanning the whole road.SurfaceHint::default()is empty. - Surface
Sample - The road surface under a point, from
RoadSurface::sample. - Switch
- A railway switch, from a road’s
<railroad><switch>: where a train on the main track may turn onto the side track. - TooFew
Points - Why a list of points is not a polyline.
- Track
Point - A place on a track: a road, the
salong it, and which way along it the switch leads. - User
Data - One piece of vendor data a map attaches to an object, kept as text.
- Vector
- A displacement between places, or a direction. Metres, or dimensionless when it is a unit direction.
- Virtual
Junction - A virtual junction, from a
<junction type="virtual">: roads that leave or join a main road part way along it, such as a driveway, without cutting it. - Virtual
Link - Where a road meets another part way along it, in a
VirtualJunction. It runs the way the file links them: from a road’s<predecessor>into the road, or from the road into its<successor>. - Visibility
- How far a driver can see from a lane, in metres, from an OpenDRIVE
<visibility>: its four distances as the file names them. - VmsBoard
Reference - One board of a
VmsGroup. - VmsGroup
- The variable message boards on one gantry, from a
<vmsGroup>, which a scenario treats as one display.
Enums§
- Access
- Who may use a lane, from its OpenDRIVE
<access>. Each road user is a restriction type as the file names it, such asbusorbicycle. - Additional
- What an
AdditionalDatasays. - Advance
- Where one branch of
RoadNetwork::advanceended. - CrgMode
- How a CRG file lies on the map, from
<CRG mode>. - CrgPurpose
- What the values in a CRG file are, from
<CRG purpose>. - Direction
- Travel direction of a lane relative to its geometry’s start→end.
- Extent
- The volume a placed object occupies, in its own frame:
lengthalong its heading,widthacross it,heightup from its origin. - Import
Error - Why an OpenDRIVE document did not import.
- Include
Problem - Why an
<include>was left out. - Junction
Group Kind - What a
JunctionGroup’s junctions together are, from itstype. - Lane
Advisory - Whether traffic from the lanes beside a lane may also use it, from a
<lane>’sadvisory. A bike lane that cars may also use is one. - Lane
Change - Which way traffic may cross a road mark. Lanes are numbered up toward the left of the road’s reference direction, so crossing toward higher numbers is crossing to the left.
- Lane
Type - What a lane is for.
- Layer
- The lane layer a lane is on, from its
<lanes layer>, or the permanent layer for a road whose only<lanes>is a temporary one. - Layer
Policy - Which lane layers a query looks at, where a road has two.
- Line
Pattern - How a road mark’s line is broken up along the road.
- Line
Rule - What a line tells traffic about crossing it from the inside of the road, or from the left on the line between the two sides.
- Link
Point - One side of a
VirtualLink. - Mesh
Error - Why a mesh cannot be turned into a physics trimesh.
- Object
Type - What an object is.
- Orientation
- Which direction of its road an object or a signal applies to, from its
orientation. - Referenced
- What a
Referencenames. - RoadEnd
- One end of a road: where its
<predecessor>or its<successor>joins it. - Road
Mark Type - What a road mark is.
- Road
Mark Weight - How heavy a road mark’s lines are.
- Road
Skip Reason - Why a
<road>baked nothing. - Road
Type - What a road is for, which sets the traffic rules on it.
- Road
User - A road user a
Semanticnames. - Semantic
- One thing a signal means, from an OpenDRIVE
<semantics>child. Eachkindis the file’stype, such asmaximumfor a speed, empty if it gives none. - Shape
- Where an object is and what volume it fills.
- Side
- The left or the right of a road, looking along its
+s. - Sign
Target - What a
SignDependencynames: a signal, or a sign on the same board, as the spec’s example of a speed sign and the plates under it does. - Signal
Board - A board a signal is, from a
<staticBoard>or a<vmsBoard>. - Speed
Limit - The fastest traffic may drive on a lane.
- Structure
Kind - Whether a structure is a tunnel or a bridge, and what describes each.
- Switch
Position - Which way a
Switchis set, from itsposition. - Unit
- The unit of a signal’s
value. - Warning
- One thing a load dropped, or read against a rule of the OpenDRIVE spec,
in
Provenance::warnings.
Constants§
- MAX_
BAKED_ LENGTH - The most lane and road CRG one load bakes, in metres: each lane’s length
and each road
<CRG>’s stretch, a metre of which counts as eight, summed over the file. It is 2,000 km, about six times the lanes of the largest real map the crate is tried on. The crate samples each every few centimetres to metres, so a small broken file that repeats a long road’s lanes or CRG records would otherwise need more memory than any machine has. A road past it is skipped, and a road CRG past it dropped. - MAX_
INCLUDED_ BYTES - The most bytes a document may read in through its includes, all told. A file that includes another many times, which includes another many times, would otherwise grow without bound.
- MAX_
LENGTH - The longest road or geometry the crate bakes, in metres. The crate samples a road every few centimetres to metres along its length, so a length from a broken file, such as 1e13, would need more memory than any machine has. Real roads are far shorter.
Functions§
- load_
file - Load an OpenDRIVE file from disk and bake it into a
RoadNetwork. - load_
file_ with_ provenance - Like
load_file, but also returns the OpenDRIVEProvenanceof every baked lane, object, structure, signal, controller and road mark, for a viewer or editor that must name the road and original id each one came from. - load_
str - Bake an OpenDRIVE document (as a string) into a
RoadNetwork. - load_
str_ with - Like
load_str_with_provenance, reading each file an<include>names withread, which returns its text or why it can’t.readgets the file’s path as the<include>writes it, joined to the folder of the file that includes it, so a nested include names a path from the document’s own folder. - load_
str_ with_ provenance - Like
load_str, but also returns the OpenDRIVEProvenanceof every baked lane, object, structure, signal, controller and road mark. Each record carries the id of what it describes.