Use from ROS
MVSim comes with a ROS 1 and ROS 2 node (an executable named mvsim_node), which is shipped with the ROS package named mvsim.
Note
You can also use the cli application mvsim if you want to test or run your world without launching a whole ROS system.
See mvsim cli.
Generic launch file
This launch file can be used to launch a simulated world integrated with ROS from the command line, or can be also included into your own launch file by setting its ROS launch arguments.
Basic usage from the command line
roslaunch mvsim launch_world.launch \
world_file:=/path/to/your/my.world.xml \
headless:=True
ros2 launch mvsim launch_world.launch.py \
world_file:=/path/to/your/my.world.xml \
headless:=True
All launch parameters
All these parameters apply to both, ROS 1 and ROS 2 launch files above:
$ ros2 launch mvsim launch_world.launch.py --show-args
Arguments (pass arguments as '<name>:=<value>'):
'world_file':
Path to the *.world.xml file to load
'headless':
no description given
(default: 'False')
'do_fake_localization':
Publish tf "map" -> "odom" from the ground truth (fake localization).
Set to False when running SLAM or a localization node (e.g. AMCL).
(default: 'True')
'publish_tf_odom2baselink':
publish tf "odom" -> "base_link"
(default: 'True')
'force_publish_vehicle_namespace':
Use vehicle name namespace even if there is only one vehicle
(default: 'False')
'disable_sim_time_clock':
Do not use the internal simulation clock: do not publish '/clock' and
stamp all messages with wall-clock time instead, as done before
simulation time support was added
(default: 'False')
'realtime_factor':
Simulation speed: <1 slower, >1 faster than real time, 0 as fast as
possible. (ROS 2 only)
(default: '1.0')
'publish_sensor_tf':
Publish the TF of each sensor wrt "base_link". Disable it if
robot_state_publisher publishes them from the URDF.
(default: 'True')
'use_rviz':
Whether to launch RViz2
(default: 'True')
'rviz_config_file':
If use_rviz:="True", the configuration file for rviz
(default: '')
Running SLAM or localization
By default (do_fake_localization:=True), mvsim_node publishes the TF map → odom
from the ground truth. SLAM and localization nodes (e.g. slam_toolbox, AMCL) publish that
same TF, and two publishers make the robot jump between both estimates (more and more, as
odometry drifts). Disable fake localization in that case, e.g.:
ros2 launch mvsim demo_warehouse.launch.py do_fake_localization:=False
ros2 launch slam_toolbox online_async_launch.py use_sim_time:=True \
slam_params_file:=my_mapper_params.yaml # with "scan_topic" set to the 2D lidar topic
mvsim_node (ROS 2) warns if it detects another node publishing map → odom while
fake localization is enabled.
Note
As with real robots, 2D lidar SLAM works best on flat ground: on slopes, a planar scanner
sees the terrain or misses the walls, which degrades scan matching. For worlds with hills
(e.g. the outdoor part of demo_indoor_outdoor), use a 3D lidar SLAM instead.
How to include it into your own launch
You can use this code to bootstrap your own launch files:
<launch>
<!-- Arguments -->
<arg name="world_file" default="$(find my_package)/mvsim/demo.world.xml" />
<arg name="headless" default="False" />
<arg name="do_fake_localization" default="True" />
<arg name="publish_tf_odom2baselink" default="True" />
<arg name="force_publish_vehicle_namespace" default="False" />
<arg name="disable_sim_time_clock" default="False" />
<arg name="use_rviz" default="True" />
<arg name="rviz_config_file" default="$(find mvsim)/mvsim_tutorial/demo_depth_camera.rviz" />
<!-- Include the original launch file -->
<include file="$(find mvsim)/launch/launch_world.launch">
<arg name="world_file" value="$(arg world_file)" />
<arg name="headless" value="$(arg headless)" />
<arg name="do_fake_localization" value="$(arg do_fake_localization)" />
<arg name="publish_tf_odom2baselink" value="$(arg publish_tf_odom2baselink)" />
<arg name="force_publish_vehicle_namespace" value="$(arg force_publish_vehicle_namespace)" />
<arg name="disable_sim_time_clock" value="$(arg disable_sim_time_clock)" />
<arg name="use_rviz" value="$(arg use_rviz)" />
<arg name="rviz_config_file" value="$(arg rviz_config_file)" />
</include>
</launch>
import os
from launch import LaunchDescription
from launch.actions import IncludeLaunchDescription
from launch.substitutions import LaunchConfiguration
from launch.launch_description_sources import PythonLaunchDescriptionSource
from ament_index_python.packages import get_package_share_directory
def generate_launch_description():
# *** REMEMBER: Change this to your actual world file ***
world_file = os.path.join(
get_package_share_directory('my_package'), 'mvsim', 'demo.world.xml')
# and replace this RViz file with yours as needed:
rviz_config_file = os.path.join(
get_package_share_directory('mvsim'), 'mvsim_tutorial', 'demo_depth_camera_ros2.rviz')
headless = 'False'
do_fake_localization = 'True'
publish_tf_odom2baselink = 'True'
force_publish_vehicle_namespace = 'False'
disable_sim_time_clock = 'False'
use_rviz = 'True'
# Create LaunchDescription
ld = LaunchDescription()
# Add actions to LaunchDescription
ld.add_action(IncludeLaunchDescription(
PythonLaunchDescriptionSource(
os.path.join(get_package_share_directory('mvsim'), 'launch', 'launch_world.launch.py')
),
launch_arguments={
'world_file': world_file,
'headless': headless,
'do_fake_localization': do_fake_localization,
'publish_tf_odom2baselink': publish_tf_odom2baselink,
'force_publish_vehicle_namespace': force_publish_vehicle_namespace,
'disable_sim_time_clock': disable_sim_time_clock,
'use_rviz': use_rviz,
'rviz_config_file': rviz_config_file
}.items()
))
return ld
Simulation time and the /clock topic
The mvsim_node acts as the ROS time source for the whole system:
It publishes the global
/clocktopic (rosgraph_msgs/Clock) with the current simulation time (the wall-clock time at simulation start plus the elapsed simulated seconds).Every message header it publishes (
/odom,/base_pose_ground_truth,/tf, and all sensor topics) is stamped with that same simulation time. Sensor messages in particular are stamped with the exact instant the observation was generated inside the simulation, so their timestamps are unaffected by any latency in the asynchronous ROS publisher threads.
Because header stamps track simulation time rather than wall-clock time, they stay coherent even when the simulation cannot keep up with real time (real-time factor below 1.0 due to heavy sensor/GUI load).
Note
Run your downstream nodes with use_sim_time:=true so they consume
/clock. The mvsim_node itself drives the clock and normally runs
with use_sim_time:=false; setting use_sim_time:=true on the mvsim
node is discouraged (a warning is printed) since it would make the node
depend on the very clock it publishes.
Disabling the simulation clock
If you prefer the previous behavior, set the disable_sim_time_clock
parameter (ROS launch argument) to true. In that case:
mvsim_nodedoes not publish/clock.All header stamps, including sensor observations, use plain wall-clock time (as reported by the ROS clock), regardless of the real-time factor.
ros2 launch mvsim launch_world.launch.py \
world_file:=/path/to/your/my.world.xml \
disable_sim_time_clock:=True
Performance diagnostics
MVSim measures its own performance over consecutive windows of 2 seconds of simulated time: achieved real time factor, wall-clock time spent in physics and waiting for OpenGL-based sensors, and, per sensor, its processing time and achieved output rate.
In the GUI: hover the mouse over the real time factor in the bottom status bar.
ROS 2: published as
diagnostic_msgs/DiagnosticArrayon/diagnostics(status namemvsim: performance), atdiagnostics_rateHz (node parameter, default1.0,0disables it). Times are given as a percentage of the simulated time, so100%means as much time as real time. The status isWARNif the achieved real time factor is below 90% of the requested one (realtime_factor). This publisher is only built ifdiagnostic_msgsis found.C++:
World::getPerformanceStats().
Example (ROS 2): publish at 2 Hz and watch the values:
ros2 run mvsim mvsim_node --ros-args \
-p world_file:=/path/to/my.world.xml \
-p diagnostics_rate:=2.0
# In another terminal:
ros2 topic echo /diagnostics
# ...or with a GUI: ros2 run rqt_runtime_monitor rqt_runtime_monitor
Each message holds the keys realtime_factor, realtime_factor_requested,
window_simul_time, physics_steps, physics_time_percent,
sensors_wait_time_percent, and, for each sensor, <vehicle>/<sensor>/time_percent and
<vehicle>/<sensor>/rate_hz.
Example (C++):
const mvsim::World::PerformanceStats st = world.getPerformanceStats();
std::cout << "RTF: " << st.realtime_factor << "\n";
for (const auto& [name, s] : st.sensors)
{
std::cout << name << ": " << s.observations / st.window_simul_time << " Hz\n";
}
Sensor TFs
By default, mvsim_node publishes the TF from base_link to each sensor frame. If another
node already publishes them (e.g. robot_state_publisher from a URDF, see
mvsim-urdf2xml), set the node parameter publish_sensor_tf to false, e.g.
ros2 launch mvsim launch_world.launch.py world_file:=... publish_sensor_tf:=False.