Implementation:CARLA simulator Carla GlobalRoutePlanner Trace Route

Knowledge Sources	CARLA Simulator CARLA Documentation
Domains	Graph Search, Path Planning, Autonomous Driving
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for computing a global route between two locations provided by the CARLA simulator agents library. The trace_route() method takes an origin and destination as carla.Location objects and returns a complete route as a list of (carla.Waypoint, RoadOption) tuples, using A* search over the pre-built road network graph.

Description

The method performs the following steps:

1. Waypoint projection: Projects the origin and destination locations onto the nearest road waypoints using carla.Map.get_waypoint().
2. Node resolution: Looks up the corresponding graph node IDs for both waypoints using the internal _id_map keyed by (road_id, section_id, lane_id).
3. A* search: Calls networkx.astar_path() on the road graph with Euclidean distance as the heuristic function, returning the optimal sequence of node IDs.
4. Path-to-route conversion: Iterates over consecutive node pairs in the path, retrieves the interpolated waypoints stored on each edge during graph construction, and determines the RoadOption maneuver annotation for each waypoint.
5. Route assembly: Returns the concatenated list of (carla.Waypoint, RoadOption) tuples forming the complete route from origin to destination.

Usage

Use trace_route() whenever you need a global route plan in CARLA. It is called internally by BasicAgent.set_destination() and BehaviorAgent.set_destination(), but can also be used standalone for route analysis, visualization, or feeding custom planners.

Code Reference

Source Location

• Repository: CARLA
• File: PythonAPI/carla/agents/navigation/global_route_planner.py
• Lines: L41-82

Signature

def trace_route(self, origin, destination):
    """
    This method returns list of (carla.Waypoint, RoadOption)
    from origin to destination.
    """
    route_trace = []
    # ... A* search and annotation logic ...
    return route_trace

Import

from agents.navigation.global_route_planner import GlobalRoutePlanner

I/O Contract

Inputs

Name	Type	Required	Description
origin	carla.Location	Yes	Starting location for the route. Will be projected to the nearest road waypoint.
destination	carla.Location	Yes	Target location for the route. Will be projected to the nearest road waypoint.

Outputs

Name	Type	Description
route_trace	list[tuple[carla.Waypoint, RoadOption]]	Ordered list of waypoints with associated maneuver annotations. Each tuple contains a carla.Waypoint on the road and a RoadOption enum indicating the driving action (LANEFOLLOW, LEFT, RIGHT, STRAIGHT, CHANGELANELEFT, CHANGELANERIGHT).

Usage Examples

Basic Example

import carla
from agents.navigation.global_route_planner import GlobalRoutePlanner

# Connect and build the planner
client = carla.Client('localhost', 2000)
world = client.get_world()
carla_map = world.get_map()
grp = GlobalRoutePlanner(carla_map, sampling_resolution=2.0)

# Define origin and destination
spawn_points = carla_map.get_spawn_points()
origin = spawn_points[0].location
destination = spawn_points[100].location

# Compute route
route = grp.trace_route(origin, destination)

print(f"Route has {len(route)} waypoints")
for i, (wp, road_option) in enumerate(route):
    loc = wp.transform.location
    print(f"  [{i}] x={loc.x:.1f}, y={loc.y:.1f} -> {road_option.name}")

Visualizing the Route in CARLA

import carla
from agents.navigation.global_route_planner import GlobalRoutePlanner

client = carla.Client('localhost', 2000)
world = client.get_world()
carla_map = world.get_map()
grp = GlobalRoutePlanner(carla_map, sampling_resolution=2.0)

spawn_points = carla_map.get_spawn_points()
route = grp.trace_route(spawn_points[0].location, spawn_points[50].location)

# Draw the route as debug points in the simulator
for wp, road_option in route:
    world.debug.draw_point(
        wp.transform.location + carla.Location(z=0.5),
        size=0.1,
        color=carla.Color(0, 255, 0),
        life_time=30.0
    )

Related Pages

Implements Principle

• Principle:CARLA_simulator_Carla_A_Star_Route_Planning