Implementation:CARLA simulator Carla LocalizationStage

Knowledge Sources	CARLA
Domains	Traffic_Management, Autonomous_Driving
Last Updated	2026-02-15 05:00 GMT

Overview

The LocalizationStage class maintains a horizon of waypoints ahead of each traffic-managed vehicle and handles lane change decisions, path following, and route import logic within the Traffic Manager pipeline.

Description

LocalizationStage inherits from the Stage base class and implements per-vehicle waypoint buffer management. It is called once per vehicle per tick and performs the following operations:

• Waypoint Buffer Management: Maintains a Buffer (deque of SimpleWaypointPtr) for each vehicle. The buffer represents the planned path ahead. Waypoints behind the vehicle (based on dot product with heading) are purged, and new waypoints are appended to maintain a speed-dependent horizon length. At higher speeds (above HIGHWAY_SPEED), a longer horizon rate is used.
• Buffer Initialization: If a vehicle's buffer is empty (e.g., newly registered), the closest waypoint from the InMemoryMap is looked up and pushed as the initial waypoint.
• Junction Detection: Determines if a vehicle is at a junction entrance by comparing the junction status of the front waypoint and a look-ahead waypoint. A special-case exception exists for the roundabout in Town03.
• Lane Change Logic: Processes forced lane changes from user parameters and automatic lane changes based on configurable probabilities: keep slow lane percentage, random left lane change percentage, and random right lane change percentage. Lane changes are gated by minimum speed and minimum distance since the last lane change. The AssignLaneChange method computes the actual waypoint shift.
• Custom Path Import: The ImportPath method allows users to inject custom paths (sequences of cg::Location) into the waypoint buffer, overriding normal waypoint generation.
• Custom Route Import: The ImportRoute method allows users to inject custom routes (sequences of road options encoded as uint8_t) which are resolved against the map topology.
• Junction Safe Space: The ExtendAndFindSafeSpace method extends the waypoint buffer through junctions and identifies safe stopping points, ensuring vehicles do not block intersections.
• Track Traffic Registration: Each waypoint added or removed from a buffer is registered/deregistered with TrackTraffic via PushWaypoint and PopWaypoint, enabling the collision stage to track overlapping paths.

Usage

LocalizationStage is instantiated by TrafficManagerLocal and runs as part of the per-tick parallel pipeline. Its output (LocalizationFrame) is consumed by MotionPlanStage for target waypoint selection and by CollisionStage indirectly through the shared BufferMap.

Code Reference

Source Location

• Repository: CARLA
• File: LibCarla/source/carla/trafficmanager/LocalizationStage.cpp
• Header: LibCarla/source/carla/trafficmanager/LocalizationStage.h

Signature

class LocalizationStage : Stage {
public:
  LocalizationStage(const std::vector<ActorId> &vehicle_id_list,
                    BufferMap &buffer_map,
                    const SimulationState &simulation_state,
                    TrackTraffic &track_traffic,
                    const LocalMapPtr &local_map,
                    Parameters &parameters,
                    std::vector<ActorId>& marked_for_removal,
                    LocalizationFrame &output_array,
                    RandomGenerator &random_device);

  void Update(const unsigned long index) override;
  void RemoveActor(const ActorId actor_id);
  void Reset();
};

Import

#include "carla/trafficmanager/LocalizationStage.h"

I/O Contract

Inputs

Name	Type	Required	Description
vehicle_id_list	const std::vector<ActorId>&	Yes	List of registered vehicle actor IDs
buffer_map	BufferMap&	Yes	Mutable map of waypoint buffers keyed by actor ID
simulation_state	const SimulationState&	Yes	Cached kinematic state for all actors
track_traffic	TrackTraffic&	Yes	Mutable structure tracking waypoint occupancy across vehicles
local_map	const LocalMapPtr&	Yes	Shared pointer to the in-memory map for waypoint queries
parameters	Parameters&	Yes	Per-vehicle and global configuration including lane change settings, custom paths, and routes
marked_for_removal	std::vector<ActorId>&	Yes	Vehicles flagged for removal (used in OSM mode when routes end)
random_device	RandomGenerator&	Yes	Random number generator for lane change probability decisions

Outputs

Name	Type	Description
output_array	LocalizationFrame&	Array of LocalizationData structs per vehicle containing target waypoint, junction flag, and angular deviation
buffer_map	BufferMap&	Updated waypoint buffers with extended paths and lane changes applied
track_traffic	TrackTraffic&	Updated waypoint occupancy tracking

Usage Examples

// Created inside TrafficManagerLocal:
localization_stage(LocalizationStage(vehicle_id_list,
                                     buffer_map,
                                     simulation_state,
                                     track_traffic,
                                     local_map,
                                     parameters,
                                     marked_for_removal,
                                     localization_frame,
                                     random_device));

// Called per vehicle in the parallel update loop:
localization_stage.Update(vehicle_index);

// Output consumed by MotionPlanStage:
const LocalizationData &localization = localization_frame.at(index);

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_TrafficManagerLocal
• CARLA_simulator_Carla_InMemoryMap
• CARLA_simulator_Carla_CollisionStage
• CARLA_simulator_Carla_MotionPlanStage
• CARLA_simulator_Carla_ALSM