Read a sensor
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.
Point this at an existing sensor (make one with create-sensor)
and either show it in a window, save its stream to disk, or get a one-shot
info summary. The goal is: select a sensor → see it.
Selector (any one): --id N · --type sensor.camera.rgb · --attached-to hero.
Capture in lock-step, not as an observer
save takes the world's clock when the world is asynchronous, then ticks it
once per frame: one tick, one frame. --no-sync keeps the old passive
behaviour, and if another client already owns the clock this one observes
instead (the clock rule the spawn skills follow).
This is not a nicety. Capturing as a passive observer wedges the recording
client on this build. Measured against a healthy server, with the world
ticking and a second client still able to pull frames from the very same
sensor:
| write path | frames before it froze |
|---|
save_to_disk inside the listen callback, HD | 396 |
| same, 720p | 147 |
save_to_disk moved to the main loop, queued | 222 |
own cv2 encode from raw_data | 248 |
| lock-step, client owns the clock | 401 of 401, no stall |
Every observer variant froze in futex_wait with no error and no further
I/O — so the write path was never the cause, the delivery model was. Replacing
save_to_disk and then the encoder was wasted effort; owning the clock fixed
it outright, and matches the pattern that captured 5388 frames for a video on
this same build.
Two consequences worth knowing:
- Timing is exact. 401 frames over 20.00 s of simulated time at 20 Hz,
nothing dropped or duplicated, and the run is reproducible.
save_to_disk is still avoided for camera frames: the buffer is
converted and written here (cv2, falling back to PIL). That change did not
fix the stall on its own, but it keeps the encode where its cost is visible.
The duration budget is read off the world clock (elapsed_seconds), not summed
from per-frame deltas: summing counts observed frames, so a consumer slower
than the server takes minutes to "reach" 20 seconds.
Live Traffic Manager traffic and a lock-step capture are incompatible
Measured on 0.10.0: with the camera owning a 20 Hz clock and a
[[spawn-vehicles]] holder attached as an observer, all 40 vehicles stood
still for the whole 500-frame capture. The Traffic Manager lives in the
process that created it and only steps when that process ticks the world, so
a TM held by one client and a clock owned by another never advances. Traffic
moved in earlier tests only because the holder was itself the ticker — and a
holder that ticks forces this capture into observer mode, which is what wedges
it.
So pick one:
| what you want | how |
|---|
| a capture with moving traffic | record the traffic first, then replay it into a lock-step capture. The replayer is server-side, needs no TM, and moved 33 of 50 replayed vehicles under the camera's clock |
| live TM traffic on screen, no frame capture | let the traffic holder own the clock and watch it in the window |
| a capture of a static scene | camera alone, as above |
The replay recipe, in order:
# 1. record the traffic while its holder owns the clock
python3 ../spawn-vehicles/scripts/vehicles.py spawn --count 50 --base-type car --hold &
python3 ../record-simulation/scripts/record.py clip --file /tmp/traffic.log --seconds 20
# 2. stop the holder, clear the scene, spawn the camera
# 3. capture in lock-step while the replay feeds the actors
python3 scripts/read_sensor.py save --id <cam> --out ./frames --seconds 20 &
python3 ../replay-recording/scripts/replay.py play --file /tmp/traffic.log --duration 20 --keep-scene
--keep-scene matters in step 3: without it the replay skill stops holders and
puts the world back to asynchronous, which takes the clock away from the
capture.
Instructions
Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Make sure the sensor exists (create-sensor) and the world is ticking
- [ ] Step 3: info (sanity) → show (window) or save (dataset)
Commands need CARLA_HOST/CARLA_PORT from scripts/env.sh.
Step 1: Check prerequisites
bash scripts/check_env.sh
Step 3: Read
source scripts/env.sh
# quick sanity: one reading + summary
python3 scripts/read_sensor.py info --id 123
# or by the actor it's on / by type
python3 scripts/read_sensor.py info --attached-to hero --type camera.rgb
# LIVE WINDOW (cameras + lidar); 0 = until you close it
python3 scripts/read_sensor.py show --id 123 --seconds 30
# SAVE a dataset: PNGs for cameras, .ply for lidar, JSONL for imu/gnss/…
python3 scripts/read_sensor.py save --id 123 --out ./capture --seconds 10
python3 scripts/read_sensor.py save --id 123 --out ./capture --frames 50
# MULTI-SENSOR: tile several cameras/lidars in one window
python3 scripts/read_sensor.py grid --ids 123,124,125 --seconds 30
# ROS 2: which topics does this sensor publish, and is it actually publishing?
python3 scripts/read_sensor.py ros-info --id 123
Reading it from ROS 2 instead
On a server started with --ros2 the sensor also publishes DDS topics, and
ros-info reports them without needing ROS 2 installed — it derives the names
the way the server does and reads back is_enabled_for_ros():
sensor id=123 (sensor.camera.rgb)
ros_name='front' frame_id='front' parent_frame=hero
rt/carla/hero/front/image [sensor_msgs/Image] qos=best_effort, volatile, depth=1 (ROS node sees /carla/hero/front/image)
rt/carla/hero/front/camera_info [sensor_msgs/CameraInfo] ...
rt/tf: yes
enabled_for_ros=NO — this sensor is NOT publishing. Fix with: ...
Then, from a ROS 2 environment on the same domain — and with the checkout's
RMW profile exported, or nothing arrives (see below):
set +u; source /opt/ros/humble/setup.bash # setup.bash breaks under set -u
export FASTRTPS_DEFAULT_PROFILES_FILE=$CARLA_UE4_ROOT/PythonAPI/examples/ros2/config/fastrtps-profile.xml
ros2 topic echo --once /carla/hero/front/camera_info
ros2 topic hz /carla/hero/front/image # rate sanity, cheaper than echo
Points to know, all verified against a live server:
- A local subscriber without that RMW profile gets nothing.
topic list shows
the topics, hz prints nothing, no error appears anywhere: CARLA's Fast DDS is
built with shared memory and a stock ROS 2 install does not match it. The
profile forces UDP-only. visualize-ros-rviz local-env prints the exports.
enabled_for_ros=NO means silence, not a slow topic. Enable it with
[[create-sensor]] ros --id N (or --ros at spawn).- Image and point-cloud topics are best-effort (
PublisherQos::SensorData),
history depth 1: a late or slow subscriber loses frames rather than stalling the
server. IMU/GNSS/collision are reliable.
- Durability is transient_local on fastdds — on every topic, not just
rt/carla/map: the middleware only ever raises durability and Fast DDS's default
writer QoS is already transient_local. Do not rely on "volatile" anywhere.
- Rates follow the tick, not the sensor. With
sensor_tick unset on an async
-nullrhi server the lidar measured ~2.7 kHz. Set sensor_tick or use sync
mode for realistic rates.
- Stamps are simulation time, driven by the same clock as
rt/clock — run
subscribers with use_sim_time or every timestamp looks wrong.
- This skill's
show/save and a ROS subscriber can run at once; they are
independent consumers of the same sensor.
On CARLA 0.10.0 (the UE5 line: 5.5 and 5.8)
Reading sensor data is unchanged. Two notes:
ros-info no longer lists rt/carla/map — that publisher does not exist on
0.10.0 (see [[world-data]]).
enable_for_ros and friends moved class, from carla.Actor on 0.9.x to
carla.ServerSideSensor on 0.10.0. A spawned sensor is a ServerSideSensor on
both versions, so calls on the actor handle work either way; they are simply not
on the carla.Sensor base class, which is what you get if you introspect the
wrong type.
New on 0.10.0 and readable by this skill without changes: the fisheye camera
variants and sensor.lidar.hss_lidar (both UE5 lines), plus
sensor.camera.rt_lens, sensor.other.autoware_gnss and
sensor.other.vehicle_status (UE 5.8 only)
([[create-sensor]] lists them). ServerSideSensor.send() is new, for pushing
custom V2X messages.
Examples
Example 1: see the ego's camera
User says: "show me the ego's camera"
create-sensor spawn --type camera.rgb --attach-to hero (note the id), then
read_sensor.py show --id <id>. A window opens with the live feed.
Example 2: capture a short dataset
User says: "save 5 seconds from the front camera"
save --id <id> --out ./front --seconds 5 → numbered PNGs in ./front.
Example 3: what is the GNSS reading?
User says: "what's the GPS saying?"
info --type other.gnss --attached-to hero → one line with lat/lon/alt.
Troubleshooting
Problem: info times out / no data
Cause: the world isn't advancing (sync mode, no ticks) or sensor_tick is large.
Solution: tick the world (set-world-settings) or run async; lower sensor_tick.
Problem: show errors about display / no window
Cause: no display (headless), or pygame missing.
Solution: run where there's a display; on a headless box use save instead. The
window is client-side (independent of the server's own rendering).
Problem: depth/semantic image looks wrong when saved raw
Cause: those need a colour converter.
Solution: this skill auto-applies LogarithmicDepth / CityScapes for save and show.
Problem: ros2 topic echo prints nothing but info here shows data
Cause: the sensor ticks because this skill is listening; it is not enabled for
ROS, or the subscriber is on a different ROS_DOMAIN_ID.
Solution: ros-info (reports both), then [[create-sensor]] ros --id N; match
the domain the server was started with ([[run-carla-server]]).
Problem: ROS timestamps look decades off / TF complains about the future
Cause: the subscriber uses wall time; CARLA stamps simulation time.
Solution: run subscribers with use_sim_time and let them follow /clock.
Problem: data stops when the command ends
Cause: listening is a callback in this process; it ends with the command.
Solution: keep show/save running for the capture; the sensor itself persists.
Outputs
save: PNGs (cameras), .ply (lidar), or data.jsonl (imu/gnss/radar/events)
under --out.show: a live window (no files).info: one summary line.
Detail (callbacks vs queues, sync-mode alignment, save formats, converters) in
references/read-sensor.md.