Implementation:CARLA simulator Carla MapBuilder

Knowledge Sources	CARLA
Domains	Road Network, OpenDRIVE, Map Construction
Last Updated	2026-02-15 05:00 GMT

Overview

MapBuilder is the implementation of the road network construction pipeline that accumulates parsed OpenDRIVE data elements and assembles them into a finalized Map object.

Description

The MapBuilder class (implementation in MapBuilder.cpp, 1158 lines) provides the builder pattern for constructing CARLA's road network representation from parsed OpenDRIVE XML data. The OpenDRIVE parser calls MapBuilder methods sequentially to register roads, lanes, geometry, profiles, signals, and other road elements.

The construction process involves two phases:

Phase 1 - Data Accumulation: During parsing, the following families of methods populate internal data structures:

• AddRoadElevationProfile() - Stores RoadInfoElevation polynomial coefficients (s, a, b, c, d) for road elevation
• AddRoadObjectCrosswalk() - Registers crosswalk objects with position, orientation, dimensions, and boundary points
• CreateLaneAccess(), CreateLaneBorder(), CreateLaneHeight(), CreateLaneMaterial(), CreateLaneRule() - Attach lane-level metadata as RoadInfo objects stored in temporary containers (_temp_road_info_container and _temp_lane_info_container)
• Lane width, visibility, marking, and speed information methods follow the same pattern
• AddSignal() and AddSignalReference() register traffic signals with their positions and road references
• Geometry methods (AddRoadGeometryLine, AddRoadGeometryArc, AddRoadGeometrySpiral, AddRoadGeometryPoly3, AddRoadGeometryParamPoly3) define the road reference line shape

Phase 2 - Build(): The Build() method finalizes the map through a series of resolution steps:

1. CreatePointersBetweenRoadSegments() - Resolves successor/predecessor relationships between roads, establishing the road graph connectivity
2. RemoveZeroLaneValiditySignalReferences() - Cleans up invalid signal references
3. Moves all accumulated RoadInfo objects from temporary containers into their respective Road and Lane InformationSet instances
4. SolveSignalReferencesAndTransforms() - Resolves signal positions using road coordinate transforms
5. SolveControllerAndJuntionReferences() - Links controllers to their managed signals and junctions
6. CreateJunctionBoundingBoxes() - Computes bounding boxes for junction areas
7. ComputeJunctionRoadConflicts() - Identifies road overlap conflicts within junctions
8. CheckSignalsOnRoads() - Validates signal placement on roads

The method returns an std::optional<Map> by moving the internal _map_data into a new Map instance.

Usage

MapBuilder is used exclusively by the OpenDRIVE parser pipeline. The parser reads the XML file, calls the appropriate MapBuilder methods for each element, and then calls Build() to produce the final Map. This class should not be used directly outside of the parsing context.

Code Reference

Source Location

• Repository: CARLA
• File: LibCarla/source/carla/road/MapBuilder.cpp
• Lines: 1-1158

Signature

namespace carla {
namespace road {

  // Build method - the main entry point
  std::optional<Map> MapBuilder::Build();

  // Elevation and profiles
  void MapBuilder::AddRoadElevationProfile(
      Road *road, const double s,
      const double a, const double b, const double c, const double d);

  // Crosswalks
  void MapBuilder::AddRoadObjectCrosswalk(
      Road *road, const std::string name, const double s, const double t,
      const double zOffset, const double hdg, const double pitch,
      const double roll, const std::string orientation,
      const double width, const double length,
      const std::vector<road::element::CrosswalkPoint> points);

  // Lane properties
  void MapBuilder::CreateLaneAccess(Lane *lane, const double s, const std::string restriction);
  void MapBuilder::CreateLaneBorder(Lane *lane, const double s, const double a, const double b, const double c, const double d);
  void MapBuilder::CreateLaneHeight(Lane *lane, const double s, const double inner, const double outer);
  void MapBuilder::CreateLaneMaterial(Lane *lane, const double s, const std::string surface, const double friction, const double roughness);
  void MapBuilder::CreateLaneRule(Lane *lane, const double s, const std::string value);

} // namespace road
} // namespace carla

Import

#include "carla/road/MapBuilder.h"

I/O Contract

Inputs

Name	Type	Required	Description
road	Road *	Yes	Pointer to the target road being configured
lane	Lane *	Yes	Pointer to the target lane being configured
s	double	Yes	Distance along the road reference line in meters (OpenDRIVE s-coordinate)
a, b, c, d	double	Yes	Polynomial coefficients for elevation, border, or width profiles
points	std::vector<CrosswalkPoint>	Yes	Boundary vertices defining crosswalk geometry
name	std::string	No	Human-readable name for roads, signals, or objects

Outputs

Name	Type	Description
Map	std::optional<Map>	The fully constructed and resolved road network map, or empty on failure
Road *	carla::road::Road *	Pointer to a newly added road (from AddRoad())
LaneSection *	carla::road::LaneSection *	Pointer to a newly added lane section (from AddRoadSection())
Lane *	carla::road::Lane *	Pointer to a newly added lane (from AddRoadSectionLane())

Usage Examples

Building a Map from OpenDRIVE Data

#include "carla/road/MapBuilder.h"

carla::road::MapBuilder builder;

// Add a road (called by OpenDRIVE parser)
auto *road = builder.AddRoad(
    /*road_id=*/1, /*name=*/"MainStreet",
    /*length=*/100.0, /*junction_id=*/-1,
    /*predecessor=*/0, /*successor=*/2, /*is_rht=*/true);

// Add geometry
builder.AddRoadGeometryLine(road, 0.0, 0.0, 0.0, 0.0, 100.0);

// Add elevation profile
builder.AddRoadElevationProfile(road, 0.0, 0.0, 0.01, 0.0, 0.0);

// Add lane section and lanes
auto *section = builder.AddRoadSection(road, 0, 0.0);
builder.AddRoadSectionLane(section, -1, /*Driving=*/1, false, 0, 0);

// Finalize the map
auto map = builder.Build();
if (map.has_value()) {
    // Use the constructed map
}

Adding Lane Properties

// Configure lane width polynomial (a + b*ds + c*ds^2 + d*ds^3)
builder.CreateLaneWidth(lane, 0.0, 3.5, 0.0, 0.0, 0.0);

// Set lane material properties
builder.CreateLaneMaterial(lane, 0.0, "asphalt", 0.9, 0.01);

// Set speed limit
builder.AddRoadInfoSpeed(road, 0.0, 50.0, "km/h");

Related Pages

• Implementation:CARLA_simulator_Carla_MapBuilder_Interface
• Implementation:CARLA_simulator_Carla_Road_Map
• Implementation:CARLA_simulator_Carla_OpenDriveParser