Implementation:CARLA simulator Carla PythonAPI Header

Knowledge Sources	CARLA
Domains	Python Bindings, API, Boost.Python
Last Updated	2026-02-15 05:00 GMT

Overview

PythonAPI.h is the central header file for CARLA's Python API bindings, aggregating all necessary C++ includes and defining utility macros for exposing C++ classes to Python via Boost.Python.

Description

This header serves as the master include for the entire Python API binding layer. It performs three critical functions:

1. Include Aggregation

Pulls in all required headers organized into categories:

• Geometry types: BoundingBox, GeoLocation, Location, Rotation, Transform, Vector2D, Vector3D
• RPC types: VehicleAckermannControl, VehicleControl, VehiclePhysicsControl, WheelPhysicsControl, WalkerControl, WalkerBoneControlIn/Out, TrafficLightState, ActorId, Command, CommandResponse, WeatherParameters, EnvironmentObject, ObjectLabel
• Client classes: Actor, TrafficLight, Vehicle, Walker, WalkerAIController, LightManager, Junction, Map, Waypoint, Landmark, ClientSideSensor, LaneInvasionSensor, Sensor, ServerSideSensor, BlueprintLibrary, ActorBlueprint, Client, ActorList, World
• Sensor data: CollisionEvent, IMUMeasurement, ObstacleDetectionEvent, Image, LaneInvasionEvent, LidarMeasurement, SemanticLidarMeasurement, GnssMeasurement, RadarMeasurement, DVSEventArray, RadarData
• Image processing: ImageConverter, ImageIO, ImageView

2. GIL Release Macros

Defines a family of CALL_WITHOUT_GIL macros (for 0-5 arguments) that wrap C++ method calls to release the Python Global Interpreter Lock during execution, preventing Python from blocking during simulator communication:

• CALL_WITHOUT_GIL(cls, fn) through CALL_WITHOUT_GIL_5(cls, fn, T1_, T2_, T3_, T4_, T5_)
• Corresponding CONST_CALL_WITHOUT_GIL variants for const methods

3. Return Value Conversion Macros

• CALL_RETURNING_COPY -- For methods returning values that need copying
• CALL_RETURNING_LIST -- Converts C++ iterables to Python lists
• CALL_RETURNING_OPTIONAL -- Converts std::optional to Python object or None
• OptionalToPyObject -- Template helper for optional-to-Python conversion
• PyListToVector -- Template converting Python lists to std::vector

Also conditionally defines CARLA_PYTHON_API_HAS_OSM2ODR if the OSM2ODR header is available.

Usage

Include this header in any .cpp file that defines Boost.Python bindings for CARLA types. All binding source files (Control.cpp, World.cpp, SensorData.cpp, etc.) include this as their first header.

Code Reference

Source Location

• Repository: CARLA
• File: PythonAPI/carla/include/PythonAPI.h (599 lines)

Signature

// GIL release macros
#define CALL_WITHOUT_GIL(cls, fn) +[](cls &self) { \
      carla::PythonUtil::ReleaseGIL unlock; \
      return self.fn(); \
    }

#define CALL_WITHOUT_GIL_1(cls, fn, T1_) +[](cls &self, T1_ t1) { \
      carla::PythonUtil::ReleaseGIL unlock; \
      return self.fn(std::forward<T1_>(t1)); \
    }

// Return value conversion helpers
template <typename OptionalT>
static auto OptionalToPyObject(OptionalT &optional);

template<typename T>
std::vector<T> PyListToVector(boost::python::list &input);

#define CALL_RETURNING_LIST(cls, fn) +[](const cls &self) { ... }
#define CALL_RETURNING_COPY(cls, fn) +[](const cls &self) { ... }
#define CALL_RETURNING_OPTIONAL(cls, fn) +[](const cls &self) { ... }

Import

#include <PythonAPI.h>

I/O Contract

Inputs

Name	Type	Required	Description
cls	C++ class type	Yes	The C++ class being wrapped (used in macro expansion)
fn	Member function name	Yes	The method to expose to Python
T1_...T5_	Template parameter types	No	Argument types for methods with parameters

Outputs

Name	Type	Description
Lambda function	boost::python compatible callable	A lambda that releases the GIL and calls the wrapped C++ method
Python list	boost::python::list	For CALL_RETURNING_LIST macros, converts C++ iterables
Python object/None	boost::python::object	For CALL_RETURNING_OPTIONAL macros, converts optionals

Usage Examples

#include <PythonAPI.h>

// Using GIL-release macros in binding definitions
class_<cc::World>("World", no_init)
  .def("get_map", CALL_WITHOUT_GIL(cc::World, GetMap))
  .def("get_actors", CALL_RETURNING_LIST(cc::World, GetActors))
  .def("get_weather", CONST_CALL_WITHOUT_GIL(cc::World, GetWeather))
  .def("set_weather", CALL_WITHOUT_GIL_1(cc::World, SetWeather, cr::WeatherParameters))
;

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_Python_Control_Bindings - Uses this header for control type bindings
• CARLA_simulator_Carla_Python_World_Bindings - Uses this header for world bindings
• CARLA_simulator_Carla_Python_SensorData_Bindings - Uses this header for sensor data bindings
• CARLA_simulator_Carla_Python_LightManager_Bindings - Uses this header for light manager bindings