WWW-POSIM v0.6.16Simulator documentation
Documentation menu
WWW-POSIM / Simulator documentation

Sensor models & parameters

This catalogue describes how WWW-POSIM measurements are generated: Gazebo rendering sensors, kinematic sensors, POSIM acoustic plugins and application adapters. Built-in values belong to the supplied robot; builder values belong to a newly generated vehicle; provider features require a matching installed plugin. The final model SDF and sensor-manifest.json define a saved vehicle's actual configuration.

Measurement pipeline

  1. Physical state or rendered geometry

    Gazebo supplies link motion, world fields or ray intersections. Each sensor has a mounting transform and acquisition clock.

  2. Measurement model

    The plugin projects images, forms inertial measurements, solves beam velocities or computes acoustic returns. Noise and validity belong to this stage.

  3. Message and frame conversion

    ROS–Gazebo bridges or POSIM adapters preserve measurements while naming frames, converting units and reporting unavailable data.

  4. Research consumer or display

    A controller or estimator consumes stamped measurements. GUI images can be compressed, buffered or delivered at a lower rate.

Shared configuration and timing

Parameter / contract Meaning and selected behaviour
sensor/@type, custom gz:type Chooses the implementation: camera, rgbd_camera, gpu_lidar, imu, magnetometer, or a custom GNSS/DVL/multibeam sensor. The world must also load its corresponding system.
pose Six values: x/y/z in metres and roll/pitch/yaw in radians, relative to the parent link. Builder positions are limited to ±10 m and each angle to ±2π.
update_rate Requested acquisitions per simulation second. Builder range: 0.1–30 Hz. Physics steps, rendering and delivery can lower the observed rate; increasing this value cannot create additional physics states between steps.
always_on, connections Controls activation. Built-in cameras are requested on demand; builder payloads set always_on=true. A configured sensor can still be unavailable when its rendering/provider cannot start.
topic, frame_id, TF Builder payloads use /vehicle/sensors/{id}. Sensor mounts are relative to vehicle/base_link; camera image frames use optical right/down/forward axes, while body coordinates use forward/left/up.
Acquisition stamp Simulation time at measurement. Preserve it through logging and fusion. HLS playback time and browser reception time describe transport, not sensor acquisition.
noise Plugin-specific. IMU Gaussian noise supports per-axis white noise, bias and dynamic bias; camera image noise uses mean and standard deviation. A common XML tag does not imply the same error model across sensors.

Gazebo sensor implementations define the underlying models. WWW-POSIM selects and sometimes adapts them. SDF uploads change supported values in existing blocks while preserving their structure. Add available sensors through the vehicle builder. Optional Gazebo blocks described below are engine capabilities; the upload workflow does not accept arbitrary XML additions.

RGB cameras: forward and downward

Gazebo CameraSensor projects scene geometry through a camera into an Ogre2 render target and publishes an image plus camera calibration. Materials, lighting, occlusion and Underwater rendering determine colour. This is a rendered pinhole-camera model; the supplied cameras do not model a physical rolling shutter, exposure electronics or lens contamination.

Parameter WWW-POSIM values and effect
camera/image/width, height Built-in forward: 640 × 480; builder forward: 640 × 480; builder downward: 800 × 600 pixels. Builder dimensions are 64–1920 each, with width × height × rate limited to 30 million pixels/s per camera.
camera/horizontal_fov Built-in forward: 1.05 rad; builder: 1.4 rad, adjustable from 0.1 to 3 rad. Resolution and FOV determine pixel angular sampling and calibration.
camera/clip/near, far Built-in forward: 0.1–5,000 m; builder cameras: 0.1–100 m. Clipping is geometric; it does not specify useful underwater visibility.
update_rate 5 Hz initially for these cameras. Video and sensor transport has independent limits.
camera/noise, distortion, lens/intrinsics Gazebo supports Gaussian image noise, Brown radial/tangential distortion (k1, k2, k3, p1, p2) and supplied intrinsics. The app's generated camera definitions do not add noise or distortion blocks. Retain the final SDF and emitted CameraInfo.

Outputs are sensor_msgs/Image and sensor_msgs/CameraInfo; a compressed JPEG is a separate delivery representation. The observer's Vehicle/World camera is not a robot sensor. Implementation.

The display adapter subscribes while a viewer or compressed-image consumer needs frames. An accepted transport subscription alone does not prove that images are arriving: after 10 wall-clock seconds without a frame, the adapter renews the subscription while demand remains. A fresh decoded frame is still required for the live state. This recovery does not change the sensor's simulation-time rate, measurement timestamps or navigation freshness checks.

Inspection RGB-D camera

Gazebo RgbdCameraSensor renders colour, a floating-point depth image and a point cloud from the same camera geometry. It uses the rendered depth buffer, rather than stereo matching or a physical structured-light/ToF measurement. Water colour attenuation does not add uncertainty to the numeric depth channel.

Parameter Built-in BlueROV2 inspection configuration
pose (0.4, 0, −0.25) m on base_link, pitch π/4: a separate downward-looking lens.
camera/image, horizontal_fov 640 × 480 pixels; 1.05 rad horizontal FOV.
camera/clip/near, far 0.1–80 m. Gazebo also supports separate depth_camera/clip bounds; the app does not override them independently here.
update_rate, always_on 5 Hz requested; activated on demand.

ROS outputs use Image, CameraInfo and PointCloud2 where bridged. Retain invalid/out-of-range depth values when processing; an image colour map is not the depth data. The cloud is one camera observation, not an accumulated SLAM map. Implementation.

Planar LiDAR

Gazebo GpuLidarSensor uses GPU ray rendering against visible scene geometry, applies the configured range/noise rules and publishes a scan. Its range is geometric, not an optical return-power or underwater laser-propagation calculation. A planar scan misses objects outside its mounting height and scan plane.

SDF parameter Built-in WAM-V / builder WAM-V
lidar/scan/horizontal/samples 360 samples; angular resolution=1.
min_angle, max_angle −π to +π rad; one horizontal scan plane.
lidar/range/min, max, resolution Built-in: 0.2 / 50 / 0.02 m. Builder: 0.1 / 50 / 0.01 m; builder maximum range is adjustable from 1 to 100 m. Resolution is a model setting, not a measured accuracy guarantee.
update_rate, pose Normally 5 Hz. Built-in mounting is 2.5 m above the base; the shared demo uses a bow mount at (3.5, 0, 1.0) m to intersect its buoys. Builder mounts are saved explicitly.
lidar/noise No additional noise block in the app's generated planar scanner. Gazebo itself supports range-noise models.

ROS output: sensor_msgs/LaserScan. Preserve angle metadata and nonfinite returns; do not interpret no return as zero distance. Implementation.

Downward single Ping

The application's Ping adapter reduces a 5 × 5 Gazebo GPU-ray scan to its nearest valid return and publishes one sensor_msgs/Range. It models a finite beam footprint and range validity. It does not compute acoustic echo intensity, time-series waveforms or multipath.

Parameter Builder configuration
Horizontal/vertical samples 5 × 5 rays; each axis spans ±0.00872665 rad (±0.5°). Legacy dedicated demonstration sensors can use a different fan.
range/min, max, resolution 0.1 / 30 / 0.01 m; maximum range adjustable from 1 to 100 m.
update_rate, pose 5 Hz initially; downward mount from the saved vehicle recipe.
Published field_of_view Cone enclosing the square ray bundle, computed from its half-angles. The return can come from any ray in that footprint.

Too-close input becomes negative infinity; no return becomes positive infinity; unknown input remains NaN when there is no valid hit. The original acquisition stamp is retained. Ping and DVL are alternative downward payloads in the current builder. A single range constrains distance along a beam footprint; it does not identify a unique seabed point.

Doppler velocity log

Gazebo's DopplerVelocityLog finds bottom targets in rendered beam cones. It projects sensor-to-target relative kinematic velocity onto beam directions, adds beam noise, then solves velocity by least squares using SVD. This is a beam/kinematics measurement model; it does not synthesize acoustic carrier waveforms and estimate their Doppler spectra.

Custom <gz:dvl> parameter Selected application profile
type, arrangement phased_array; four beams, rotations 45°, 135°, −45°, −135°, tilt 30°, aperture 2°.
tracking/bottom_mode/when best; bottom tracking is configured. Water-mass tracking is an upstream capability, not enabled by this profile.
tracking/bottom_mode/noise/stddev Gaussian beam-speed standard deviation 0.002 m/s. Solved velocity covariance depends on beam geometry.
minimum_range, maximum_range, resolution 0.1 / 20 / 0.01 m; builder maximum range adjustable from 1 to 100 m.
update_rate, reference_frame 1 Hz initially; reference pose 0 0 0 0 0 0. Mount rotation and lever arm remain part of calibration.

The ROS adapter accepts a bottom velocity with at least three locked beams, valid covariance, the expected frame and advancing stamps. It emits geometry_msgs/Vector3Stamped plus JSON std_msgs/String status; loss of lock does not synthesize a zero velocity. Status also carries per-beam bottom ranges. A range is the minimum within a beam cone, not necessarily the centre-ray intersection, and absent range variance means unknown uncertainty. Gazebo implementation.

Imaging multibeam sonar

The dedicated POSIM provider converts rendered ray geometry into acoustic backscatter, beam-corrected frequency responses and range-bin intensity. Its Rust/WGPU, CUDA and CPU compute paths are described in the Acoustic processing catalogue, including the distinction between acoustic observations and geometry point clouds.

Parameter group Application provider configuration
Horizontal beams / angular bounds 256 over −π/3 to +π/3 rad (120°).
Vertical rays / angular bounds 256 over −π/18 to +π/18 rad (20°).
sonarFreq, maxDistance, ray range 700 kHz; processing maximum 15 m; ray range 0.2–15 m.
update_rate, raySkips 2 Hz initially; skip factor 1.
soundSpeed, bandwidth, sourceLevel, sensorGain Provider SDF settings; retain them with raw data. They control propagation/range processing and display scaling and are not all builder controls.

The exploratory comparison uses a wider tilted fan; its settings are stated beside the figures. marine_acoustic_msgs/ProjectedSonarImage is the builder's raw output. A coloured fan image is a presentation of that observation. This provider must pass the host's compatibility checks before selection.

IMU: acceleration and angular velocity

Gazebo ImuSensor receives simulated kinematics, subtracts gravity expressed in the sensor frame to form specific force, applies configured per-axis noise, and publishes angular velocity and acceleration. Its orientation is obtained from simulator orientation relative to the configured reference; it is not an onboard attitude estimator.

Parameter Meaning and application selection
update_rate WAM-V: 200 Hz; built-in BlueROV2: 1,000 Hz requested. Both are bounded by physics stepping.
pose, orientation_reference_frame Mount/reference determine axes. BlueROV2 ROS direct control sets the IMU mount to zero rotation; the ArduPilot model retains its interface-specific orientation. Use emitted frames and TF.
imu/linear_acceleration/{x,y,z}/noise mean, stddev in m/s²; bias_mean/bias_stddev select bias and dynamic_bias_stddev/dynamic_bias_correlation_time configure its evolution. The supplied base IMUs do not configure these noise blocks.
imu/angular_velocity/{x,y,z}/noise Corresponding gyro parameters in rad/s. dynamic_bias_stddev and dynamic_bias_correlation_time describe a time-correlated bias when enabled.

Output: sensor_msgs/Imu; raw IMU and MAVROS fused attitude are different signals. No-noise configuration and truth-derived orientation must be stated when using this input for VIO or controller evaluation. IMU and Gaussian noise implementation.

The ArduPilot JSON interface interpolates completed physics states into intermediate SITL samples. The Route planning & control describes its sampling rates and behaviour when the timestep changes. ROS IMU acquisition remains bounded by physics stepping; interpolated SITL samples add no new physical detail.

Magnetometer

Gazebo MagnetometerSensor rotates the world magnetic-field vector into the sensor frame and adds configured per-axis noise. The BlueROV2 application model adds a 20 Hz magnetometer. Application worlds select SI tesla and ENU world-field conventions through use_units_gauss=false and use_earth_frame_ned=false on the Gazebo system.

Parameter Meaning
World magnetic_field Field vector used by the simulator; retain the world definition with the experiment.
pose, update_rate Sensor mounting and requested sample rate; added BlueROV2 sensor is at the base-link origin, 20 Hz.
magnetometer/{x,y,z}/noise Gaussian mean/standard deviation in tesla; no additional noise block is set on the added sensor.

Output: sensor_msgs/MagneticField. This measurement does not simulate vehicle hard/soft-iron interference or local magnetic anomalies. WAM-V's ArduPilot compass path uses the SITL field model; do not substitute the ROS magnetometer topic for evidence of what the FCU actually fuses. Implementation.

Satellite GNSS receiver

POSIM's custom posim::Gnss measures the world-space antenna position, transforms it into geographic coordinates, adds seeded position/velocity noise, queues latency and gates fixes by water exposure and obstruction. Its output is bridged to NavSatFix/status and, in GNSS navigation mode, to MAVLink GPS_INPUT.

Parameters Meaning
update_rate, latency, reacquire_seconds Acquisition cadence, delayed delivery and continuous dry acquisition interval, in simulation time.
horizontal_stddev, vertical_stddev, velocity_stddev, seed Gaussian error magnitudes and reproducibility.
link_name, mounting pose, water_level, wave_topic, dry_margin Antenna lever arm and wave-aware immersion test.
enabled, obstruction topic Receiver selection and imposed reception blockage.

The GNSS & navigation provides the authoritative values, covariance, ENU/NED conversion, vertical datum and EKF distinctions. Satellite geometry and multipath are outside this receiver model.

Pressure and depth: separate signal paths

The workspace's simulator-depth display and ArduSub's estimated depth must be distinguished from POSIM's standalone SubseaPressureSensorPlugin. That plugin is used by additional POSIM models such as RexROV and Slocum; it is not a selectable pressure payload in the current WWW-POSIM builder.

The plugin reads model-origin depth below the mean z=0 plane, clamps depth above water to zero, and adds a linear hydrostatic pressure increment to standard pressure. It publishes sensor_msgs/FluidPressure in pascals and optionally geometry_msgs/PointStamped inferred depth.

Plugin parameter Meaning / implementation default
namespace, topic Model lookup and output topic; default topic sea_pressure.
standard_pressure, kPa_per_meter 101.325 kPa baseline; 9.80638 kPa/m increment. Internal kPa is converted to Pa for ROS.
estimate_depth_on, update_rate Optional inverse pressure-to-depth output; default enabled. Rate 0 means no added plugin rate cap.
saturation Parsed with default 3,000, but not applied in the measurement path of this implementation. It is not an enforced range cutoff.

The current implementation adds zero pressure noise while reporting a variance based on a 3 kPa standard deviation. That field is not evidence of sampled pressure noise. It uses model position rather than a separately calibrated pressure-port mount and does not sample wave-surface pressure. Implementation.

USBL components in POSIM

POSIM also contains UsblTransceiver and UsblTransponder. They exchange simulated device positions and commands and produce relative-location messages. The transponder perturbs its world coordinates with Gaussian noise; this is a position-based acoustic-location test component, not a phase-difference array receiver or an acoustic propagation solver. It is not exposed as a standard WWW-POSIM builder payload.

Parameter group Meaning
namespace, device names/IDs, attached objects Identify the transceiver, transponders, models and message routes.
enable_ping_scheduler, ping_frequency, interrogation_mode Scheduled interrogation and common/individual addressing.
sound_speed Initial propagation-speed setting, default 1,540 m/s; callbacks can replace it with a depth/temperature approximation.
Transponder mu, sigma Position-noise mean and standard deviation, defaults 0 and 1 m.

The propagation wait uses a wall-clock sleep in the callback, so this component should not be treated as a precise simulation-time time-of-flight instrument. See the transceiver and transponder for exact message paths and configuration requirements.

Odometry, truth and research records

Gazebo's OdometryPublisher exposes simulated pose/twist; the automatic-voyage controller also publishes measured native state. This is a reference signal, not wheel odometry or a sensor-fusion estimate. Record its parent/child frames, publication frequency and coordinate-rebase events. Keep FCU or SLAM estimates on separately identified paths.

For a reproducible sensor experiment, retain the final SDF, sensor manifest, TF extrinsics, calibration messages, application/provider revisions, simulation timestep, random seeds, acquisition stamps, validity messages and raw observations. Video, screen captures and colour maps supplement those records. Optional sensors and providers · Simulation, rendering & sensors · Marine dynamics & rendering.

Search documentation