`car_dreamer.toolkit`

Here are the API calls provided by our task development suite. See Customization for guides on how to customize your own task.

class WorldManager(env_config)

The class to manage the world in CARLA. You can spawn various actors using this class. The actors spawned by this class will be automatically destroyed when reset. This class also provides methods to get information about these actors.

property actor_actions: Dict[int, List[Tuple[Command, Waypoint]]]

Get the actions of all actors spawned by this manager.

Returns:: a dictionary mapping vehicle IDs to their known actions.
Return type:: dict[int, list[tuple[Command, carla.Waypoint]]]

Warning

Actors not controlled by autopilot will not have actions. They will not be included in the returned dictionary. And some actors may have an empty list if there is no known action.

property actor_ids: List[int]: Get the ids of all actors spawned by this manager.

property actor_polygons: Dict[int, List[Tuple[float, float]]]

Get the bounding box polygons of all actors spawned by this manager.

Returns:: a dictionary mapping actor IDs to their bounding box polygons.
Return type:: dict[int, list[tuple[float, float]]]

property actor_transforms: Dict[int, Transform]

Get the transforms of all actors spawned by this manager.

Returns:: a dictionary mapping actor IDs to their transforms.
Return type:: dict[int, carla.Transform]

property actors: List[Actor]: Get all actors spawned by this manager.

carla_actors(actor_type: str = '') → List[Actor]

Get all actors of a specific type directly through CARLA APIs.

Parameters:: actor_type – the type of the actors to retrieve (e.g., ‘vehicle’, ‘traffic_light’).
Returns:: a list of actors of the specified type.

destroy_actor(actor_id: int) → None: Destroy an actor. Call this method if you want to manually destroy an actor spawned by this manager.

Warning

Do not call this method for actors spawned by spawn_unmanaged_actor. Directly call carla.Actor.destroy instead.

get_blueprint(pattern_filter: str, attribute_filter: Dict[str, str] | None = None) → ActorBlueprint: Randomly get a blueprint from the library based on the pattern filter and attribute filter.

get_blueprint_library(pattern_filter: str, attribute_filter: Dict[str, str] | None = None) → BlueprintLibrary: Get blueprint library based on the pattern filter and attribute filter.

get_random_spawn_point() → Transform: Get a random spawn point of the map.

get_spawn_points() → List[Transform]: Get spawn points of the map.

on_reset(callback: Callable[[], None]) → None: Register a callback function to be called when the environment is reset. If called multiple times, it will overwrite the previous callback.

on_step(callback: Callable[[], None]) → None: Register a callback function to be called when the environment steps. If called multiple times, it will overwrite the previous callback.

spawn_actor(transform: Transform | None = None, blueprint: ActorBlueprint | None = None, max_try_time: int | None = None) → Actor

Equivalent to try_spawn_actor(transform, blueprint), but retry if failed.

Parameters:: max_try_time – if None, try until success, else raise an exception after max_try_time.

See also

try_spawn_actor

spawn_auto_actors(n: int, transforms: List[Transform] | None = None, blueprints: BlueprintLibrary | None = None) → List[Actor]

Spawn n actors that are automatically controlled by autopilot.

Parameters:

n – number of actors to spawn.
transforms – if None, use random spawn points.
blueprints – if None, use vehicle.* with number_of_wheels 4 as default.

Returns:

a list of spawned actors, note that the length of the list may be less than n.

spawn_unmanaged_actor(transform: Transform, blueprint: ActorBlueprint, **kwargs) → Actor: Spawn an actor with the given blueprint and transform. Actors spawned by this method will be omitted by this manager. That is, they will not be included when retrieving actor information or destroyed when reset. This is useful when creating sensors for car_dreamer.toolkit.observer.handlers.SensorHandler.

try_spawn_actor(transform: Transform | None = None, blueprint: ActorBlueprint | None = None) → Actor | None

Spawn an actor with the given blueprint and transform.

Parameters:

transform – if None, use a random spawn point.
blueprint – if None, use vehicle.audi* with number_of_wheels in 4 as default.

Returns:

the spawned actor. If fails, return None.

try_spawn_aggresive_actor(transform: Transform | None = None, blueprint: ActorBlueprint | None = None) → Actor | None: Similar to try_spawn_actor(transform, blueprint). But the actor will be automatically controlled by autopilot and ignore traffic lights and other vehicles.

See also

try_spawn_actor

class Observer(world: WorldManager, obs_config: dict)

An observer is a collection of data handlers, each providing some observation data.

The output of the Observer can be configured through env.observation.enabled, which is passed to the constructor in obs_config.

In addtion, register_simple_handler provides a flexible way to supplement the observation data with a callback.

The output of the Observer can be configured through env.observation.enabled. See observation configuration for possible choices.

destroy() → None: Destroy all the registered handlers.

get_observation(env_state: Dict) → Tuple[Dict, Dict]: Get the current observation data from all the registered handlers.

get_observation_space() → Space: Get the combined observation space from all the registered handlers.

register_simple_handler(key: str, observation_fn: Callable[[], Dict], observation_space: Space) → None

Register a simple observation function that may optionally use environment state.

Parameters:

key – str, the key in observation space
observation_fn – Callable[[], Dict], the callback function which returns the observation data
observation_space – spaces.Space, the observation space

reset(ego: Actor) → None: Reset all the registered handlers with the given ego vehicle.

class RandomPlanner(vehicle: Actor, sampling_radius=0.8): Generate random routes based on map topology

class FixedPathPlanner(vehicle: Actor, vehicle_path: List[Tuple[float, float, float]], use_road_waypoints: List[bool] | None = None, sampling_radius=0.8): Route planner for a given vehicle and a given route

class FixedEndingPlanner(vehicle: Actor, end: Location, sampling_radius=0.8): Route planner for a given vehicle and a given ending

class Command(value): Enumeration for high-level commands.

class FollowDirections(value): Enumeration for the follow task directions

class TTCCalculator

A class for calculating Time-to-Collision (TTC) between vehicles as static methods.

static find_nearby_vehicles(world, ego_vehicle, map)

Find nearby vehicles within the specified proximity threshold.

Parameters:

world – The simulation world.
ego_vehicle – The ego vehicle.
map – The simulation map.
dist_threshold – The distance threshold to consider vehicles as nearby.

Returns:

List of nearby vehicles.

static get_ttc(ego_vehicle, world, map)

Compute the minimum Time-to-Collision (TTC) between the ego vehicle and nearby vehicles.

Parameters:

world – The simulation world.
ego_vehicle – The ego vehicle.
map – The simulation map.
ttc_threshold – The threshold to stop calculations if a low TTC is found.

Returns:

The minimum TTC value.

static get_ttc_to_target(ego_vehicle, target_vehicle)

Compute the Time-to-Collision (TTC) between the ego vehicle and a target vehicle.

Parameters:

ego_vehicle – The ego vehicle.
target_vehicle – The target vehicle.

Returns:

The computed TTC value.

static is_vehicle_ahead(ego_vehicle, map, target_location)

Check if a target vehicle is ahead of the ego vehicle within the proximity threshold.

Parameters:

ego_vehicle – The ego vehicle.
map – The simulation map.
target_location – The location of the target vehicle.
dist_threshold – The maximum distance to consider a vehicle as nearby.

Returns:

True if the target vehicle is ahead and within the proximity threshold, False otherwise.

get_location_distance(location1: Tuple[float, float], location2: Tuple[float, float]) → float

Compute the distance between two locations

Parameters:

location1 – tuple(float, float)
location2 – tuple(float, float)

Returns:

float, distance between the two locations

get_vehicle_orientation(vehicle: Actor) → float

Get the orientation of a vehicle.

Parameters:: vehicle – carla.Actor
Returns:: orientation of the vehicle

get_vehicle_pos(vehicle: Actor) → Tuple[float, float]

Get the position of a vehicle.

Parameters:: vehicle – carla.Actor
Returns:: x, y position of the vehicle

get_vehicle_velocity(vehicle: Actor) → Tuple[float, float]

Get the velocity of a vehicle.

Parameters:: vehicle – carla.Actor
Returns:: tuple(float, float), x, y velocity of the vehicle

car_dreamer.toolkit

`car_dreamer.toolkit`