Implementation:CARLA simulator Carla BlueprintLibrary Class

Knowledge Sources	CARLA
Domains	Client Library, Blueprint System, Actor Spawning
Last Updated	2026-02-15 05:00 GMT

Overview

BlueprintLibrary provides a searchable and filterable collection of ActorBlueprint objects available for spawning actors in the CARLA simulation.

Description

The BlueprintLibrary class manages an ordered map of ActorBlueprint instances, keyed by their string identifiers. It is typically obtained from the simulation world and provides several access patterns:

Construction

The constructor accepts a std::vector<rpc::ActorDefinition> and builds the internal map by emplacing each definition's ID with a newly constructed ActorBlueprint.

Filtering

• Filter(wildcard_pattern) -- Returns a new BlueprintLibrary (wrapped in SharedPtr) containing only blueprints whose tags or ID match the given Unix shell-style wildcard pattern. Internally iterates through all blueprints calling ActorBlueprint::MatchTags.
• FilterByAttribute(name, value) -- Returns a new BlueprintLibrary containing only blueprints that have the specified attribute with the matching value. For attributes with recommended values, checks against the recommended value list; otherwise, checks the current attribute value directly.

Access Methods

• Find(key) -- Returns a const_pointer to the blueprint with the given ID, or nullptr if not found.
• at(key) -- Returns a const_reference to the blueprint by string key; throws std::out_of_range if not found.
• at(pos) -- Returns a const_reference by numeric position; throws std::out_of_range if out of bounds.
• operator[] -- Positional access.
• size() -- Returns the number of blueprints.

The internal storage uses a map_type (ordered map), and a private constructor accepting this map type is used by the filter methods to create new library instances.

Usage

Retrieve the blueprint library from the world, filter by actor type (e.g., vehicle.*, sensor.camera.*), then select and configure specific blueprints for spawning.

Code Reference

Source Location

• Repository: CARLA
• File: LibCarla/source/carla/client/BlueprintLibrary.cpp (89 lines)

Signature

namespace carla {
namespace client {

class BlueprintLibrary {
public:
  BlueprintLibrary(const std::vector<rpc::ActorDefinition> &blueprints);

  SharedPtr<BlueprintLibrary> Filter(const std::string &wildcard_pattern) const;
  SharedPtr<BlueprintLibrary> FilterByAttribute(const std::string &name, const std::string &value) const;

  const_pointer Find(const std::string &key) const;
  const_reference at(const std::string &key) const;
  const_reference at(size_type pos) const;
  size_type size() const;

private:
  map_type _blueprints;
};

} // namespace client
} // namespace carla

Import

#include "carla/client/BlueprintLibrary.h"

I/O Contract

Inputs

Name	Type	Required	Description
blueprints	std::vector<rpc::ActorDefinition>	Yes	List of actor definitions from the server
wildcard_pattern	std::string	No	Filter pattern (e.g., "vehicle.*", "sensor.camera.*")
name	std::string	No	Attribute name for FilterByAttribute
value	std::string	No	Attribute value for FilterByAttribute
key	std::string	No	Blueprint ID for Find/at lookup

Outputs

Name	Type	Description
Filtered library	SharedPtr<BlueprintLibrary>	New library containing matching blueprints
Blueprint pointer	const_pointer	Pointer to found blueprint, or nullptr
Blueprint reference	const_reference	Reference to blueprint at given key/position
size	size_type	Number of blueprints in the library

Usage Examples

// Get the full blueprint library
auto library = world.GetBlueprintLibrary();

// Filter for vehicles
auto vehicles = library->Filter("vehicle.*");

// Filter by specific attribute
auto four_wheeled = library->FilterByAttribute("number_of_wheels", "4");

// Find a specific blueprint
auto bp = library->Find("vehicle.tesla.model3");
if (bp != nullptr) {
    auto actor = world.SpawnActor(*bp, transform);
}

// Access by index
for (size_t i = 0; i < vehicles->size(); ++i) {
    auto &blueprint = vehicles->at(i);
    std::cout << blueprint.GetId() << std::endl;
}

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_ActorBlueprint_Class - Individual blueprint entries in this library
• CARLA_simulator_Carla_Actor_Class - Actors spawned from blueprints