Implementation:CARLA simulator Carla Road Map

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

Overview

Map is the central road network representation in CARLA that implements OpenDRIVE-based waypoint generation, lane querying, signal search, topology resolution, and mesh generation for the entire road graph.

Description

The Map class (in carla::road) serves as the primary interface for all road-related queries within the CARLA simulator. It wraps a MapData object and provides a rich set of methods for navigating the road network.

The implementation file (Map.cpp, 1613 lines) contains extensive logic organized into several functional areas:

Static Helper Functions:

ConcatVectors - Efficiently merges two vectors by moving elements from the smaller into the larger
GetDistanceAtStartOfLane / GetDistanceAtEndOfLane - Compute s-coordinates with EPSILON offsets to avoid floating-point precision errors at lane section boundaries
ForEachDrivableLane / ForEachLane / ForEachDrivableLaneAt - Template functions that iterate over lanes of specified types in road sections, invoking a callback with each Waypoint

Waypoint Generation:

GetClosestWaypointOnRoad() - Uses an R-tree spatial index to find the nearest road segment to a given 3D location, then maps it to a specific lane
GetWaypoint() - Similar to above but filters by lane type (default: Driving)
GenerateWaypoints() - Produces evenly-spaced waypoints across all drivable lanes at a given distance interval
GenerateWaypointsOnRoadEntries() - Returns waypoints at the entrance of every drivable lane
GenerateWaypointsInRoad() - Generates waypoints within a specific road segment

Topology and Connectivity:

GetSuccessors() / GetPredecessors() - Resolves lane-level connectivity across road boundaries, handling both simple road connections and junction roads
GetNext() / GetPrevious() - Returns waypoints at a given distance ahead or behind, following the road graph
GenerateTopology() - Builds the complete road topology as pairs of start/end waypoints for each drivable lane

Lane and Road Information:

GetLane(), GetLaneType(), GetLaneWidth() - Access lane properties at a waypoint
GetMarkRecord() - Retrieves lane marking records for left and right boundaries
CalculateCrossedLanes() - Determines which lane markings are crossed between two locations
GetAllCrosswalkZones() - Collects all crosswalk area polygons from road objects

Signal Handling:

GetSignalsInDistance() - Searches for signals along the road from a waypoint up to a given distance, following successors
GetAllSignalReferences() - Returns all signal references across the entire map

Mesh Generation:

GenerateMesh() - Creates 3D meshes for the road surface using MeshFactory
GenerateChunkedMesh() - Splits roads into length-limited chunks for efficient rendering
GetAllCrosswalkMesh() - Generates meshes for crosswalk geometry

Usage

Use Map for any operation that requires knowledge of the road network structure. This includes vehicle autopilot route planning, waypoint-based navigation, lane change detection, signal awareness, and procedural road mesh generation for rendering. The Map is constructed by MapBuilder from parsed OpenDRIVE data and is immutable once built.

Code Reference

Source Location

Repository: CARLA
File: LibCarla/source/carla/road/Map.cpp
Lines: 1-1613

Signature

namespace carla {
namespace road {

  class Map : private MovableNonCopyable {
  public:
    using Waypoint = element::Waypoint;

    Map(MapData m);

    const geom::GeoLocation &GetGeoReference() const;

    // Geometry
    std::optional<Waypoint> GetClosestWaypointOnRoad(
        const geom::Location &location, int32_t lane_type) const;
    std::optional<Waypoint> GetWaypoint(
        const geom::Location &location, int32_t lane_type) const;
    std::optional<Waypoint> GetWaypoint(
        RoadId road_id, LaneId lane_id, float s) const;
    geom::Transform ComputeTransform(Waypoint waypoint) const;

    // Road information
    const Lane &GetLane(Waypoint waypoint) const;
    Lane::LaneType GetLaneType(Waypoint waypoint) const;
    double GetLaneWidth(Waypoint waypoint) const;
    JuncId GetJunctionId(RoadId road_id) const;
    bool IsJunction(RoadId road_id) const;

    // Waypoint generation
    std::vector<Waypoint> GetSuccessors(Waypoint waypoint) const;
    std::vector<Waypoint> GetPredecessors(Waypoint waypoint) const;
    std::vector<Waypoint> GetNext(Waypoint waypoint, double distance) const;
    std::vector<Waypoint> GetPrevious(Waypoint waypoint, double distance) const;
    std::vector<Waypoint> GenerateWaypoints(double distance) const;
    std::vector<Waypoint> GenerateWaypointsOnRoadEntries(Lane::LaneType type) const;

    // Signals
    std::vector<SignalSearchData> GetSignalsInDistance(
        Waypoint waypoint, double distance, bool stop_at_junction) const;
    std::vector<const element::RoadInfoSignal*> GetAllSignalReferences() const;
  };

} // namespace road
} // namespace carla

Import

#include "carla/road/Map.h"

I/O Contract

Inputs

Name	Type	Required	Description
location	`geom::Location`	Yes	3D world position for waypoint lookup
lane_type	`int32_t` (Lane::LaneType bitmask)	No	Filter for lane types; defaults to Driving
waypoint	`Waypoint`	Yes	Reference waypoint for successor/predecessor/next queries
distance	`double`	Yes	Distance in meters for waypoint generation or search range
road_id	`RoadId`	Yes	Specific road identifier for targeted queries
m	`MapData`	Yes	Complete parsed road network data (move-constructed)

Outputs

Name	Type	Description
Waypoint	`std::optional<Waypoint>`	Closest matching waypoint, or empty if none found
Waypoints	`std::vector<Waypoint>`	List of generated or connected waypoints
Transform	`geom::Transform`	3D position and orientation at a waypoint
SignalSearchData	`std::vector<SignalSearchData>`	Signals found within search distance
Mesh	`std::unique_ptr<geom::Mesh>`	Generated 3D mesh geometry for road surfaces

Usage Examples

Finding the Closest Waypoint

#include "carla/road/Map.h"

// Given a Map instance and a world location
geom::Location vehicle_pos{100.0, 50.0, 0.5};
auto waypoint = map.GetWaypoint(vehicle_pos);
if (waypoint.has_value()) {
    geom::Transform transform = map.ComputeTransform(*waypoint);
    // Use transform for vehicle alignment
}

Generating Evenly Spaced Waypoints

// Generate waypoints every 2 meters across all drivable lanes
auto waypoints = map.GenerateWaypoints(2.0);
for (const auto &wp : waypoints) {
    geom::Transform t = map.ComputeTransform(wp);
    // Process each waypoint location
}

Following the Road Graph

// Get waypoints 10 meters ahead of the current position
auto next_wps = map.GetNext(current_waypoint, 10.0);
for (const auto &wp : next_wps) {
    // Each entry represents a possible path (multiple if lane splits)
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment