Sensors¶
Every sensor Lagrange simulates, how to put one on your robot, how to read it, and how to make it fail. The models themselves (equations, parameters with units and defaults, signals, references and checks) are in the design notes: sensors.md, and for users the sensors physics page.
There are two families:
Built-in types: IMU, lidar, camera, thermal camera, radar, GNSS, magnetometer and barometer. Each has its own USD schema (
ImuAPI_1,GnssAPI_1, …) and its own ROS 2 topics.Built-in kinds: 37 more sensors, from bumpers to sonar, simulated by Lagrange itself with no plugin. A kind is a custom sensor (
<sensor type="KIND">in URDF or SDFormat, USDCustomSensorAPI_1) whose kind Lagrange knows. Each writessensor/<name>/<quantity>signals. Its parameters, signals and model are in sensors.md §9, one section per kind (linked below).
A <sensor type> that is neither (gas, say) is a custom sensor for a plugin
to implement, like the sample tof and ultrasonic (lagrange_tof) and thermistor and
ir_thermometer (lagrange_thermal_probe) plugins.
Every sensor, by robot¶
“URDF type” is what goes in <sensor type="..."> inside a <gazebo reference="LINK"> block. A
sensor can sit on any robot; the grouping only says where each is usually found.
On every robot¶
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
IMU |
specific force and angular rate, with noise, bias and random walk |
|
|
Lidar, 2D or 3D |
ranges and intensities; channel tables, flash and Livox-style rosette patterns; motion distortion |
|
|
Camera |
colour, depth and instance images; lens, noise, exposure, rolling shutter; fisheye up to 360° |
|
|
|
a smart battery’s fuel gauge: voltage, current, charge, temperature |
|
|
|
any current or voltage signal of the run, through an ADC |
|
|
|
one laser beam’s range (TFmini-S style) |
|
|
|
the RSSI of every access point heard |
|
|
|
ultra-wideband ranges to fixed anchors, with line of sight |
|
Drones¶
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
GNSS |
latitude, longitude, height and velocity through the site’s geo origin |
USD |
|
Magnetometer |
the Earth’s field (World Magnetic Model 2025) plus EMI |
USD |
|
Barometer |
static pressure and temperature (ICAO standard atmosphere) |
USD |
|
|
angular flow of the ground under it (PMW3901, PX4Flow) |
|
|
|
pitot-static differential pressure and airspeed |
|
|
|
each ESC’s motor speed, current, voltage and temperature |
|
|
|
a landing pad’s direction and distance, as MAVLink |
|
|
|
other aircraft of the run, as ADS-B reports |
|
|
|
a tether’s tension through a load cell |
|
Cars¶
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
Radar |
detections with range, Doppler velocity, RCS and SNR |
USD |
|
|
a 4D imaging radar: range, azimuth, elevation and Doppler per detection, angle cells from its virtual array, Doppler folding, ground ghosts |
|
|
|
the car’s own CAN bus: wheel speeds, steering angle, yaw rate, gear |
|
|
|
pressure and temperature in every tyre, with the low-pressure warning |
|
|
|
traffic agents’ Basic Safety Messages and the lights’ signal phase and timing |
|
Mobile robots and AMRs¶
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
|
a contact switch: pressed, how hard, from where |
|
|
|
the range to the floor below; a drop |
|
|
|
dead-reckoned pose and twist from the wheel encoders |
|
|
|
a safety laser scanner’s protective and warning fields |
|
|
|
where guide tape is under a row of channels |
|
|
|
floor tags read by RFID or a downward QR camera |
|
Arms¶
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
|
a six-axis wrench at a wrist |
|
|
|
link-side torque in a joint |
|
|
|
a gripper’s opening, current, grip force, and whether it holds or slips |
|
|
|
a proximity skin: distances from an array of short-range elements |
|
The environment¶
These read the weather domain’s air (--weather, a WeatherAPI_1 prim or a profile) and the sun.
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
|
wind velocity, ultrasonic or cup and vane |
|
|
|
relative humidity and air temperature |
|
|
|
rain rate and accumulation |
|
|
|
visibility (meteorological optical range) and extinction |
|
|
|
PM1, PM2.5, PM4 and PM10 dust |
|
|
|
illuminance on its face |
|
|
|
the sun’s direction |
|
Underwater¶
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
|
a multibeam imaging sonar’s fan, or a single-beam echosounder |
|
Vision and machine learning¶
event_camera and stereo_camera draw the scene, so they need a Vulkan device (a GPU, or the
software device on a machine without one).
Sensor |
What it measures |
URDF type |
Model |
|---|---|---|---|
Thermal camera |
each pixel’s apparent temperature (Planck band) |
|
|
|
left and right images and a stereo depth with its error (RealSense D435 style) |
|
|
|
brightness-change events (DVS) |
|
|
|
ground-truth labels for a camera: 2D and 3D boxes, classes, a segmentation image |
|
Adding one to your robot¶
In URDF, a sensor goes in a <gazebo reference="LINK"> block: the link it is fixed to, its
<pose> on that link, its <update_rate> in Hz, and its parameters inside an element named as its
type. Every leaf element is a parameter by its path: <rangefinder><range><max>12</max></range>
is range/max = 12 (the outer element named as the type is left out). Numbers are in SI units.
<gazebo reference="base_link">
<sensor name="altimeter" type="rangefinder">
<pose>0 0 -0.05 0 1.5708 0</pose> <!-- looking down: +x turned to -z -->
<update_rate>100</update_rate>
<rangefinder><range><min>0.1</min><max>12</max></range></rangefinder>
</sensor>
<sensor name="front_bumper" type="bumper">
<pose>0.30 0 0.03 0 0 0</pose>
<update_rate>100</update_rate>
<bumper><threshold>10</threshold></bumper>
</sensor>
</gazebo>
Parameters left out take the defaults of the kind’s section in §9. The sample AMR with bumpers,
cliff sensors, wheel odometry, a safety scanner and wheel torque sensors is
assets/robots/amr_diffdrive/amr_diffdrive_safety.urdf; the example
lagrange_example_sensors runs it.
In USD, a sensor is a prim with SensorAPI_1 and CustomSensorAPI_1; a parameter’s path takes
: for /:
def Xform "altimeter" (
prepend apiSchemas = ["SensorAPI_1", "CustomSensorAPI_1"]
)
{
string sensor:custom:kind = "rangefinder"
double sensor:custom:param:range:max = 12
double sensor:rate = 100
}
SDFormat takes the same <sensor type="KIND"> as URDF. In an overlay file (--overlay,
formats.md §9) the same schemas go on a create_child prim.
The built-in types: an IMU, lidar, camera or thermal camera from URDF or SDFormat as in Gazebo; GNSS,
magnetometer, barometer and radar through their USD schemas (GnssAPI_1, MagnetometerAPI_1,
BarometerAPI_1, RadarAPI_1), as the sample quadcopter’s overlay
(assets/robots/quad_x500/quad_x500.overlay.yaml) and the sample sedan (assets/robots/sedan/sedan.usda) do. GNSS, magnetometer and barometer run only when the site’s
geo origin is given (--geo-origin LAT,LON,HEIGHT or the profile’s world.geo_origin).
Sensor timing (<latency>, <jitter>) and faults (below) apply to every sensor, built-in or kind.
Reading it¶
Every sensor writes signals named sensor/<name>/<quantity>, in SI units: a bumper named
front_bumper writes sensor/front_bumper/pressed, force and direction. lagrange graph
lists every signal of a run; each kind’s section in §9 lists its own.
Python, headless and without ROS:
import lagrange
sim = lagrange.Simulation(
"assets/robots/amr_diffdrive/amr_diffdrive_safety.urdf", world=lagrange.sample_world()
)
sim.step_until(2.0)
print(sim.read("sensor/cliff_front_left/range")) # m
print(sim.read("sensor/safety/min_distance")) # m
print(sim.read("sensor/wheel_odom/pose")) # x, y, z, then the quaternion
sim.read returns a signal’s components as a list of numbers (a Bool reads 0 or 1);
sim.image("sensor/<name>/<quantity>")
returns an image (a camera’s image, depth and instance, a stereo camera’s left, right and
depth, an event camera’s image, detections’ semantic) as a numpy array, or None before the
first frame. sim.signals() lists every signal as a dict {"name", "unit", "components"}
([s["name"] for s in sim.signals() if s["name"].startswith("sensor/")] for the sensors’ names).
What the loader noted about your files and took its own way (an unknown lidar pattern, a lens it
does not draw) is printed to stderr as [import] ... when the Simulation is made, as the command
line prints it, and sim.notes() returns those lines.
ROS 2: the built-in types publish their own topics (/scan, /points, /imu,
/<name>/image_raw, /<name>/fix, …; see the command line). A kind’s images go out
as sensor_msgs/Image on /<name>/<quantity>/image_raw with their camera_info, and a kind’s
numbers go out by default on standard messages on /<name>/<quantity>: sensor_msgs/Range for
rangefinders and cliff sensors, LaserScan for safety scanners and sonars, nav_msgs/Odometry for
wheel odometry, BatteryState, WrenchStamped, vision_msgs/Detection2DArray, … (the table is
ROS topics of the built-in kinds).
A topic mapping (--ros-topics FILE.yaml) renames or replaces them; an entry for the same topic or
signal wins over the default, and kind_topics: false in the file turns the defaults off:
publish:
- {signal: sensor/front_bumper/pressed, topic: /bumper/front, type: std_msgs/msg/Bool}
lagrange my_robot.urdf --ros-topics topics.yaml
The message types a mapping can use are listed under Plugin outputs on ROS 2.
Viewer: the Scopes plot any number signal (search for sensor/); the Sensors workspace shows
each camera and each kind with images (the Camera panel’s modes are then its images: left,
right, depth); lidars draw their points in the viewport.
Recordings: --record run.mcap keeps the sensor signals (faults included; arrays over 1024
components are left out).
Breaking it: sensor faults¶
To test how your software copes when a sensor fails, give the run faults. They work on every sensor, built-in or kind:
# the IMU's z rate jumps by 0.02 rad/s at 5 s; the front bumper stops reporting at 20 s
lagrange amr --sensor-fault imu:angular_rate=bias,value=0.02,at=5,component=2 \
--sensor-fault front_bumper=disconnect,at=20
The modes are dropout, stuck, bias, drift, noise and disconnect, each in a time window;
ROS, Python, plugins, recordings and the viewer all see the faulted values, while the ground truth
(/ground_truth/odom, /tf, the bodies’ signals) stays clean. The keys, run-file and profile
forms are in Sensor faults; the model in
sensors.md. In Python:
lagrange.Simulation(robot, sensor_faults=["imu=stuck,at=2,for=1"]).
For perfect sensors instead, switch the domain to its substitute: --domain sensors=off (or the
profile’s sensors: {enabled: false, substitute: ground_truth}) gives exact values at the right
times, and draws no images.
See them run¶
Short clips of real runs, recorded by tools/videos/make_videos.py (all the clips:
feature videos):
radar_4d.mp4: the sedan’s 4D imaging radar in the town, its detections in the 3D view (Overlays → Radar detections) and in the Sensors workspace’s radar view, coloured by radial velocity.
sensor_faults.mp4: the AMR’s gyro biased, then stuck, against the true yaw rate.
lidar_patterns.mp4: a channel table, a flash lidar and a Livox-style rosette in the same room.
fisheye.mp4: a 90° pinhole and a 220° equidistant fisheye on the AMR.
event_camera.mp4: a camera and an event camera with the same pixels.
amr_sensor_kinds.mp4: the safety AMR’s scanner entering its warning field at a rack, and a wheel’s torque.
What is not modelled¶
Each kind’s section in §9 and the physics page list their own limits. Across them:
Kinds that find things are detectors, not image processing.
detections,landing_target,tag_readerandline_sensordecide what is seen from the scene’s prims and geometry; no fiducial or tape texture is drawn or decoded.optical_flowcomputes flow from motion and depth, not by matching images.No real recordings yet. The models are checked against closed forms and data sheets, not against logs of the real parts. The data-sheet defaults were checked against the documents on 2026-11-12 (
docs/plan/sensor-defaults-verification-2026-11-12.md); the defaults marked illustrative in §9 have no primary source: give your part’s figures.Lidar: no beam divergence or multiple returns. Scan patterns and fisheye lenses come from URDF, SDFormat (Lagrange’s
lagrange:elements, formats.md §9.3) and USD (LidarAPI_1’sscanPattern,channelElevations,rosette:*;CameraSensorAPI_1’slensType,cutoffAngle; formats.md §3.8), andlagrange_importkeeps them; a USD file that uses them runs as a grid lidar and a pinhole camera in Lagrange 1.2 or older.Camera: no motion blur, absolute radiance or colour filter array; a fisheye has no vignetting, rolling shutter or exposure model, and
detections,stereo_cameraandevent_cameratake their camera as a pinhole.GNSS: no outages, multipath or latency model; magnetometer: no crustal field and no hard- or soft-iron effects; radar: no rain attenuation, multipath or ghosts.
No gas sensors: no domain carries gas concentrations.