Principle:CARLA simulator Carla Recording Event Querying
| Knowledge Sources | |
|---|---|
| Domains | Simulation, Recording |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Recording event querying provides post-hoc filtering and analysis of specific event types within a recorded simulation, such as collisions between actors and stuck-vehicle detection, without requiring a full replay.
Description
While recording introspection provides a general overview of all events in a recording, event querying enables targeted filtering of specific event categories. This is the difference between reading an entire log file and running a database query against it: event querying returns only the events that match specified criteria, making it far more efficient for focused analysis.
CARLA provides two primary event query capabilities:
- Collision querying: Filters the recording for collision events between specified actor types. Collisions can be filtered by a pair of type codes that specify the categories of actors involved. The type codes are: h (Hero vehicle), v (Vehicle), w (Walker/pedestrian), t (Traffic Light), o (Other), and a (Any). For example, querying with types v and w returns all vehicle-pedestrian collisions.
- Blocked actor detection: Identifies actors that remained stationary (or near-stationary) for longer than a specified duration. This detects vehicles that got stuck due to traffic deadlocks, pathfinding failures, or other anomalies. The query accepts a minimum time threshold and a minimum distance threshold to define what constitutes "blocked."
These queries operate on the recording file directly, parsing the binary log and applying the filter criteria without instantiating any simulation actors. The results are returned as formatted text strings suitable for console output or programmatic parsing.
Usage
Use recording event querying when you need to:
- Find all collisions of a specific type in a recording for safety analysis.
- Detect stuck vehicles that may indicate traffic management issues or map problems.
- Generate collision statistics across multiple recordings for aggregate safety metrics.
- Identify replay targets by finding the times and actors involved in specific events, then using those parameters for targeted replay.
- Validate scenario outcomes by checking whether expected events (or no events) occurred during a recorded test run.
Theoretical Basis
Recording event querying implements predicate-based filtering over temporal event streams. The recording file is a sequential log of typed events with timestamps. Each query defines a predicate (e.g., "collision between a vehicle and a walker") and the system scans the log, evaluating the predicate against each event and collecting matches.
The collision type filtering uses a categorical matching system with the type codes h, v, w, t, o, and a. The a (Any) wildcard enables broad queries, while specific type pairs enable targeted filtering. The type assignment is determined by the actor's blueprint category in the recording metadata.
The blocked actor detection implements a temporal stationarity test. For each actor, the system tracks the cumulative distance traveled over a sliding time window. If an actor's total displacement over the window falls below the distance threshold and the window duration exceeds the time threshold, the actor is flagged as blocked. This is formally a threshold test on the integral of velocity magnitude over time:
- If the total distance traveled is less than min_distance over a period of min_time, the actor is classified as blocked.
This approach correctly identifies truly stuck actors while ignoring actors that are legitimately stationary (e.g., parked vehicles that were never activated, or vehicles waiting at a red light for normal durations). The thresholds can be tuned to control the sensitivity of the detection: lower thresholds catch more subtle blocking events, while higher thresholds focus on severe stuck situations.
Both query types return results as formatted text with timestamps, actor IDs, and actor types, providing sufficient information to drive targeted replay investigations.