MultiVehicle simulator (MVSim)

Lightweight, realistic dynamical simulator for 2D ("2.5D") vehicles and robots. It is tailored to analysis of vehicle dynamics, wheel-ground contact forces and accurate simulation of typical robot sensors (e.g. 2D and 3D lidars).

This package includes C++ libraries, standalone applications, and ROS 1 and ROS 2 nodes.

License: 3-clause BSD License Copyright (C) 2014-2024 Jose Luis Blanco jlblanco@ual.es (University of Almeria) and collaborators

Please, refer to the MVSim SoftwareX paper (or the ArXiV preprint) for a gentle introduction to the project architecture. If you want to cite MVSim in your work, please use:

@article{blanco2023mvsim,
  title = {MultiVehicle Simulator (MVSim): Lightweight dynamics simulator for multiagents and mobile robotics research},
  journal = {SoftwareX},
  volume = {23},
  pages = {101443},
  year = {2023},
  issn = {2352-7110},
  doi = {https://doi.org/10.1016/j.softx.2023.101443},
  url = {https://www.sciencedirect.com/science/article/pii/S2352711023001395},
  author = {José-Luis Blanco-Claraco and Borys Tymchenko and Francisco José Mañas-Alvarez and Fernando Cañadas-Aránega and Ángel López-Gázquez and José Carlos Moreno}
}

Installation

See installation documentation for all the details and options.

The easiest way to install if you already have ROS 1 or ROS 2 is:

sudo apt install ros-$ROS_DISTRO-mvsim

Then jump to next steps to see how to launch some of the demo worlds.

Demo videos

Build matrix status

Distro	Build dev	Build releases	Stable version
ROS 1 Noetic (u20.04)		amd64 arm64 armhf
ROS 2 Humble (u22.04)		amd64 arm64
ROS 2 Iron (u22.04)		amd64 arm64
ROS 2 Jazzy @ u24.04		amd64 arm64
ROS 2 Rolling (u24.04)		amd64 arm64

EOL distro	Stable version
ROS 1 Melodic (u18.04)
ROS 2 Foxy (u20.04)

Docs

• Main documentation site
• https://wiki.ros.org/mvsim

If you clone this repository, remember to checkout the git submodules too:

git clone https://github.com/MRPT/mvsim.git --recursive

Launch demos

See more on first steps here.

Standalone:

mvsim launch mvsim_tutorial/demo_warehouse.world.xml
mvsim launch mvsim_tutorial/demo_2robots.world.xml
mvsim launch mvsim_tutorial/test_mesh.world.xml

ROS 1:

roslaunch mvsim demo_depth_camera.launch

ROS 2:

ros2 launch mvsim demo_warehouse.launch.py
ros2 launch mvsim demo_depth_camera.launch.py

Main features

• Lightweight in memory, CPU and library requirements.
• Fully configurable via .xml "world" files.
• Headless mode, suitable for dockerized environments.
• World maps:
  • Occupancy gridmaps: input as images or MRPT binary maps (from icp-slam, rbpf-slam, etc.)
  • Elevation meshes.
• Vehicle models:
  • Differential driven (2 & 4 wheel drive).
  • Ackermann steering (kinematic & dynamic steering, different mechanical drive models).
  • Ackermann steering with mechanical differentials of full grade.
• Sensors:
  • 2D and 3D Lidars: Robots see each other, their own bodies, etc.
  • RGB cameras
  • Depth cameras
• Interface to vehicles: Custom Python interface, or ROS. Choose among:
  • Raw access to forces and motor torques.
  • Twist commands (using internal controllers).

Changelog for package mvsim

0.10.0 (2024-08-28)

• Depend on new mrpt_lib packages (deprecate mrpt2)
• Merge pull request #52 from finani/fix-fake-amcl Fix fake amcl topic (QoS Durability)
• Update outdated copyright years in source files
• Merge pull request #51 from finani/nav2-compatible Nav2 compatible
• Update codebase to new clang-format style
• Merge pull request #48 from finani/refactoring-node Refactoring node
• Merge pull request #45 from finani/develop Add tf pub for each robot (support namespace)
• Merge pull request #43 from kr-jschoi/fix-bug Fix namespace switching bug between mvsim.chassis_shape and mvsim.chassis_shape.wheel3 in /chassis_markers
• Contributors: Inhwan Wee, Jose Luis Blanco-Claraco, finani, kr-jschoi

0.9.4 (2024-05-08)

• Better detection of \"in collision\" flag.
• Update to clang-format-14
• Upgrade Joystick API so it works correctly with an arbitrary number of axes
• ROS nodes: add collision state publishers for each vehicle
• remove dead code
• Contributors: Jose Luis Blanco-Claraco

0.9.3 (2024-04-24)

• Fix usage of (new explicit) TPoint3D constructors
• Contributors: Jose Luis Blanco-Claraco

0.9.2 (2024-03-21)

• BUG FIX: 3D lidars should not \'see\' XYZ corners of wheels
• BUG FIX: gridmaps were published at a too high rate in the ROS 2 node
• remove dead code
• update header version
• Contributors: Jose Luis Blanco-Claraco

0.9.1 (2024-03-05)

• Fix use of mrpt bridge to publish XYZIRT point clouds too for ROS 1
• Contributors: Jose Luis Blanco-Claraco

0.9.0 (2024-03-02)

• Do not publish tf world->map
• Expose do_fake_localization as ROS 2 launch file argument
• fix build with older mrpt
• 3D Lidar: also generate \"ring\" ID per point
• Contributors: Jose Luis Blanco-Claraco

0.8.3 (2023-12-05)

• Generate ground truth trajectory files in the TUM format
• ROS nodes: add a timeout for cmd_vel commands, so the robots stop if input messages stop
• Add rviz_plugin_tutorials dependency for ROS1
• Contributors: Jose Luis Blanco-Claraco, Michael Grupp

0.8.2 (2023-10-06)

• 3D LIDARs: Bilinear interpolation (when it makes sense) to obtain much smoother point cloud simulations
• Add missing build dep on python3-pip. This was triggering errors on ROS 1 build farm dev builds.
• Contributors: Jose Luis Blanco-Claraco

0.8.1 (2023-09-07)

• Move the rawlog-generation option to the World global options instead of sensor-wise.
• Create CITATION.cff
• helios 32fov70 sensor.xml: Fix missing MVSIM_CURRENT_FILE_DIRECTORY tag
• Fix crash in edge case with world file path in the current directory
• Contributors: Jose Luis Blanco-Claraco

0.8.0 (2023-09-02)

• Recursive \"include\"s are now possible.
• All vehicle and sensor definitions are now exposed in public directory \'definitions\' and are safe to be included from user worlds
• ROS warehouse demos: fix wrong camera topicn ame in rviz
• Add missing ROS 2 launch demo for greenhouse world
• Add new variable: MVSIM_CURRENT_FILE_DIRECTORY
• BUGFIX: In parseVars() in the XML parser
• Debugging feature: MVSIM_VERBOSE_PARSE now also traces <variable> definitions
• Contributors: Jose Luis Blanco-Claraco

0.7.4 (2023-08-30)

• Add new LIDAR 3D models: Helios 32.
• Removed LIDAR3D fbo_nrows parameter, automatically computed now from geometry solutions.
• More optimal simulation of asymmetric 3D lidars.
• Progress with RTD documentation.
• Add proper bibliography; fix all docs warnings
• ROS 2 warehouse demo: show 2D lidar in RVIZ too; add headless launch argument
• New GUI editor feature: move sensor poses
• Contributors: Jose Luis Blanco-Claraco

0.7.3 (2023-08-23)

• Update python module install method to pip (fixes deprecation)
• Improved docs
• Contributors: Jose Luis Blanco-Claraco

0.7.2 (2023-08-12)

• Joystick driving: added support for direct driving the vehicles with a joystick.
• Fix rviz for ros1 demo
• Better docs and more modern RST style.
• More shadow tuning parameters.
• IMU sensor now reads real vehicle linear acceleration.
• Contributors: Jose Luis Blanco-Claraco

0.7.1 (2023-06-11)

• ROS node: fix potential race condition creating publisher for highrate sensors
• Add IMU sensors
• New property <visual enabled=\'true|false\'>
• lidar2d xml: add option \"sensor_custom_visual\"
• FIX: Crash if launching an empty world
• Trigger an error if using use_sim_time to avoid mistakes
• Add new (fake) controller: twist_ideal
• ROS 1: don\'t enforce /use_sim_time
• Add ROS 2 launch for the 2-robot demo
• Fix cmake leftover
• Contributors: Jose Luis Blanco-Claraco

0.7.0 (2023-04-21)

• Automatic detection of collision shapes
• Add turtlebot world demo
• Rely on custom build of Box2D to increase the maximum polygon vertices count (8 to 12).
• fix inconsistent use_sim_time value for ROS 2 (it should be false)
• Expose shadow rendering parameters in the XML world file
• Abort simulation on exceptions in headless mode too
• ROS 1 and 2 nodes now quit cleanly and quickly with SIGINT
• Add ros2 launch for turtlebot world demo
• Automatic determination of zmin/zmax for blocks if not explicitly set in XML
• Force c++17 for python module
• Exit simulator on exceptions in GUI-related threads
• More automated testing
• Add unit tests in C++ too
• Refactor collision shape determination
• New UI checkbox: show collision shapes
• Allow simply geometry definitions without external 3D model file for \"blocks\"
• Light options are now under <light> XML tag.
• Largest default physics simulation timestep changed from 50ms to 5ms
• GUI: change light direction
• Add GUI checkbox to enable/disable shadows
• Add rplidar A2 sensor model
• Contributors: Jose Luis Blanco-Claraco

0.6.1 (2023-03-04)

• New XML parameters to enable and tune shadowmap generation
• Use finer timestep for prevent wrong simulation of ramp sliding
• Fix code notation
• Temporary workaround to GH CI problem
• Contributors: Jose Luis Blanco-Claraco

0.6.0 (2023-02-26)

• Support for SkyBox rendering (requires MRPT >=2.7.0)
• More camera options in world.xml files (initial azimuth, elevation, etc.)
• Terrain elevation models now support repeated textures (requires MRPT >=2.7.0)
• Faster 3D Lidar rendering (Requires MRPT >=2.7.0)
• Add Ouster OS1 sensor file
• Fix default friction coefficients; draw motor torques too
• More accurate Velodyne simulation based on sensor_rpm parameter
• Clearer code and code style conventions
• Add \"<static>\" XML tag for large, static world objects
• Support for XML tag <if ...>
• Refactor xml parser as a registry of tag->function
• Examples renamed for conciseness: \'mvsim_demo_\' to \'demo_\'
• Added a \"greenhouse\" example world
• Wheels: allow linked-yaw-objects in vehicle viz
• Support several <visual> tags in custom visualization models
• pybind11 sources simplification. Simplify into one single source tree with conditional compilation for different pybind versions.
• Emit clearer warnings and earlier detection of wrong bounding boxes
• Add reference to (preprint) paper
• Controllers: Made threadsafe
• Contributors: Fernando Ca