Query a CARLA recording
Paths. scripts/… and references/… below are relative to the
directory holding this SKILL.md. Your working directory is the user's
project, not that directory, so prefix them with its absolute path or the
command is not found.
Read facts out of a .log without replaying it. The server parses the file and
returns a text report. Three questions:
- What's in it? —
info (header: map, duration, frames, actor list).
- What crashed? —
collisions between two actor categories.
- What got stuck? —
blocked actors that barely moved.
Instructions
Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Run the query that answers the question (info / collisions / blocked)
- [ ] Step 3: Read the report; use ids/times to drive a targeted replay if needed
Commands need CARLA_HOST/CARLA_PORT from scripts/env.sh.
Step 1: Check prerequisites
bash scripts/check_env.sh
Step 2: Query
source scripts/env.sh
# header + actors (add --all for every frame; large)
python3 scripts/query.py info --file /tmp/run.log
# collisions: category codes h=hero v=vehicle w=walker t=traffic-light o=other a=any
python3 scripts/query.py collisions --file /tmp/run.log --type1 v --type2 a # any vehicle vs anything
python3 scripts/query.py collisions --file /tmp/run.log --type1 v --type2 w # vehicle vs walker
# actors that moved < 1 m (100 cm) over >= 30 s (stuck)
python3 scripts/query.py blocked --file /tmp/run.log --min-time 30 --min-distance 100
Units matter: --min-time is seconds, --min-distance is centimetres
(100 = 1 m).
Step 3: Act on it
The reports give frames, times and actor ids — feed them to
replay-recording (--start, --follow) to
jump to and watch the interesting moment.
Examples
Example 1: overview
User says: "what's in /tmp/run.log?"
info --file /tmp/run.log → map, duration, frame count, actors.
Example 2: find a crash
User says: "did any car hit a pedestrian?"
collisions --file /tmp/run.log --type1 v --type2 w. Each line gives the frame,
time and the two actor ids; then replay play --start <t> --follow <id>.
Example 3: find gridlock
User says: "which cars got stuck?"
blocked --file /tmp/run.log --min-time 20 --min-distance 50 (moved < 0.5 m in
20 s).
Troubleshooting
Problem: parse error / empty report
Cause: the .log is not on the server at that path, or has no frames.
Solution: use the server-side path; confirm the recording with info first.
Problem: collisions returns nothing but I saw a crash
Cause: wrong categories, or collisions need additional_data context.
Solution: widen with --type2 a (any); ensure the recording captured the actors.
Problem: blocked lists everything / nothing
Cause: --min-distance unit confusion (centimetres, not metres).
Solution: 100 = 1 m; raise --min-time to ignore brief stops at lights.
Outputs
Text reports printed to stdout (no world change, no file written). Use them to
target a replay-recording.
Detail (report fields, category codes, blocked-query semantics) in
references/queries.md.