Implementation:CARLA simulator Carla MapBuilder Interface

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

Overview

MapBuilder.h defines the public interface of the MapBuilder class, exposing all methods that the OpenDRIVE parser uses to incrementally construct the CARLA road network.

Description

The MapBuilder header (432 lines) declares the complete API surface for building a Map from parsed OpenDRIVE data. The class follows the builder pattern, accumulating road network components through a series of Add* and Create* methods before producing the final Map via Build().

The interface is organized by the OpenDRIVE element categories that call into it:

Road-Level Methods (called from road parser):

AddRoad() - Creates a new road with ID, name, length, junction association, predecessor/successor links, and right-hand traffic flag. Returns a Road * for subsequent configuration.
AddRoadSection() - Adds a lane section to a road at a given s-coordinate
AddRoadSectionLane() - Adds a lane to a section with type, level, and predecessor/successor lane IDs

Geometry Methods (called from geometry parser):

AddRoadGeometryLine() - Straight line geometry defined by start point, heading, and length
AddRoadGeometryArc() - Arc geometry with constant curvature
AddRoadGeometrySpiral() - Euler spiral (clothoid) with start and end curvature
AddRoadGeometryPoly3() - Cubic polynomial geometry
AddRoadGeometryParamPoly3() - Parametric cubic polynomial in U/V coordinates with configurable parameter range

Profile Methods (called from profiles parser):

AddRoadElevationProfile() - Elevation as a cubic polynomial in s
AddRoadObjectCrosswalk() - Crosswalk objects with full 3D orientation and boundary points

Lane Property Methods (called from lane parser):

CreateLaneAccess() - Lane access restrictions
CreateLaneBorder() - Lane border polynomial
CreateLaneHeight() - Inner/outer lane height offsets
CreateLaneMaterial() - Surface material with friction and roughness
CreateLaneRule() - Lane usage rules
CreateLaneVisibility() - Visibility distances in four directions
CreateLaneWidth() - Lane width polynomial
CreateLaneMarkRecord() / CreateLaneMarkTypeLine() - Lane marking definitions

Signal Methods:

AddSignal() - Registers a traffic signal with full position, orientation, dimensions, and type
AddSignalReference() - Links a signal to a specific road location
AddValidityToSignalReference() - Sets lane validity ranges for signal references

Junction and Controller Methods:

AddJunction(), AddConnection(), AddLaneLink() - Define junction topology
AddController(), AddControllerSignal() - Register signal controllers

Usage

Use this header to understand the full API available for constructing a Map. Implementers of new OpenDRIVE parsers or map importers should call these methods in the correct order: first add roads and geometry, then lane sections and lanes, then profiles and signals, and finally call Build() to finalize.

Code Reference

Source Location

Repository: CARLA
File: LibCarla/source/carla/road/MapBuilder.h
Lines: 1-432

Signature

namespace carla {
namespace road {

  class MapBuilder {
  public:
    std::optional<Map> Build();

    // Road structure
    carla::road::Road *AddRoad(
        const RoadId road_id, const std::string name,
        const double length, const JuncId junction_id,
        const RoadId predecessor, const RoadId successor, const bool is_rht);

    carla::road::LaneSection *AddRoadSection(
        carla::road::Road *road, const SectionId id, const double s);

    carla::road::Lane *AddRoadSectionLane(
        carla::road::LaneSection *section, const LaneId lane_id,
        const uint32_t lane_type, const bool lane_level,
        const LaneId predecessor, const LaneId successor);

    // Geometry
    void AddRoadGeometryLine(Road *road, double s, double x, double y, double hdg, double length);
    void AddRoadGeometryArc(Road *road, double s, double x, double y, double hdg, double length, double curvature);
    void AddRoadGeometrySpiral(Road *road, double s, double x, double y, double hdg, double length, double curvStart, double curvEnd);
    void AddRoadGeometryPoly3(Road *road, double s, double x, double y, double hdg, double length, double a, double b, double c, double d);
    void AddRoadGeometryParamPoly3(Road *road, double s, double x, double y, double hdg, double length,
        double aU, double bU, double cU, double dU,
        double aV, double bV, double cV, double dV, const std::string p_range);

    // Profiles
    void AddRoadElevationProfile(Road *road, double s, double a, double b, double c, double d);
    void AddRoadObjectCrosswalk(Road *road, const std::string name, double s, double t, double zOffset,
        double hdg, double pitch, double roll, const std::string orientation,
        double width, double length, const std::vector<road::element::CrosswalkPoint> points);

    // Lane properties
    void CreateLaneAccess(Lane *lane, double s, const std::string restriction);
    void CreateLaneBorder(Lane *lane, double s, double a, double b, double c, double d);
    void CreateLaneHeight(Lane *lane, double s, double inner, double outer);
    void CreateLaneMaterial(Lane *lane, double s, const std::string surface, double friction, double roughness);
    void CreateLaneRule(Lane *lane, double s, const std::string value);
    void CreateLaneVisibility(Lane *lane, double s, double forward, double back, double left, double right);
    void CreateLaneWidth(Lane *lane, double s, double a, double b, double c, double d);
    void CreateLaneMarkRecord(Lane *lane, double s, int id, std::string type,
        std::string weight, std::string color, std::string material,
        double width, std::string lane_change, double height);

    // Signals
    void AddSignal(/* ... signal parameters ... */);
    void AddSignalReference(/* ... reference parameters ... */);

    // Junctions
    void AddJunction(const JuncId id, const std::string name);
    void AddConnection(const JuncId junction_id, const ConId connection_id,
        const RoadId incoming_road, const RoadId connecting_road);
    void AddLaneLink(const JuncId junction_id, const ConId connection_id,
        const LaneId from, const LaneId to);
  };

} // namespace road
} // namespace carla

Import

#include "carla/road/MapBuilder.h"

I/O Contract

Inputs

Name	Type	Required	Description
road_id	`RoadId`	Yes	Unique identifier for the road segment
junction_id	`JuncId`	Yes	Junction ID (-1 if road is not part of a junction)
predecessor / successor	`RoadId`	Yes	Connected road IDs for road graph topology
s	`double`	Yes	Position along the road reference line (OpenDRIVE s-coordinate)
x, y, hdg	`double`	Yes	Start position and heading for geometry elements
a, b, c, d	`double`	Yes	Cubic polynomial coefficients for various profiles
lane_type	`uint32_t`	Yes	Bitmask of lane type flags (Driving, Sidewalk, etc.)

Outputs

Name	Type	Description
Map	`std::optional<Map>`	The finalized road network from Build()
Road *	`carla::road::Road *`	Pointer to a newly created road for further configuration
LaneSection *	`carla::road::LaneSection *`	Pointer to a newly created lane section
Lane *	`carla::road::Lane *`	Pointer to a newly created lane

Usage Examples

Complete Road Construction Flow

#include "carla/road/MapBuilder.h"

carla::road::MapBuilder builder;

// 1. Add road structure
auto *road = builder.AddRoad(1, "Highway", 500.0, -1, 0, 2, true);

// 2. Define geometry (straight line)
builder.AddRoadGeometryLine(road, 0.0, 0.0, 0.0, 0.0, 500.0);

// 3. Add elevation
builder.AddRoadElevationProfile(road, 0.0, 10.0, 0.005, 0.0, 0.0);

// 4. Add lane section with driving lanes
auto *section = builder.AddRoadSection(road, 0, 0.0);
auto *left_lane = builder.AddRoadSectionLane(section, 1, 1, false, 0, 0);
auto *right_lane = builder.AddRoadSectionLane(section, -1, 1, false, 0, 0);

// 5. Set lane widths
builder.CreateLaneWidth(left_lane, 0.0, 3.5, 0.0, 0.0, 0.0);
builder.CreateLaneWidth(right_lane, 0.0, 3.5, 0.0, 0.0, 0.0);

// 6. Build the final map
auto map = builder.Build();

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment