mvsim cli

The command-line interface (cli) application mvsim is the main entry-point to run, query, or modify a running simulation from a command line terminal. It can be used to launch standalone simulations (without ROS), or to modify, manipulate, or query a running simulation within a ROS system.

Note

The ROS node is a different cli application, named mvsim_node instead. The ROS package mvsim ships both executables: mvsim and mvsim_node. See mvsim ROS node.

Invoking mvsim

Make sure you have compiled or installed MVSim, and that the executable named mvsim is in your PATH. If you installed it as a ROS package, activating the ROS environment (setup.bash) is enough.

If this command works, you can go on with the next commands:

$ mvsim --version

You can get a list of available commands with:

$ mvsim --help
mvsim v0.7.2: A lightweight multivehicle simulation environment.

Available commands:
   mvsim launch <WORLD.xml>  Start a comm. server and simulates a world.
   mvsim server              Start a standalone communication server.
   mvsim node                List connected nodes, etc.
   mvsim topic               Inspect, publish, etc. topics.
   mvsim slice <WORLD.xml>   Export a 2D slice of the world obstacles to a .txt file.
   mvsim --version           Shows program version.
   mvsim --help              Shows this information.

Or use `mvsim <COMMAND> --help` for further options

Command mvsim launch

$ mvsim launch --help
Usage: mvsim launch <WORLD_MODEL.xml> [options]

Available options:
--headless              Launch without GUI (e.g. suitable for dockerized envs.)
-p, --port <23700>      TCP port of the communications server. If not given and the
                        default port is in use, the next free one is used. The
                        environment variable MVSIM_SERVER_PORT also sets it.
--full-profiler         Enable full profiling (generates file with all timings)
--realtime-factor <1.0> Run slower (<1) or faster (>1) than real time if !=1.0,
                        or as fast as possible if <=0
-v, --verbosity         Set verbosity level: DEBUG, INFO (default), WARN, ERROR

This can be used to launch the simulation of a world given the path to its XML definition file. Then you can interact with the robot(s) via keyboard, mouse, or joystick, or via the Python API.

If you want the simulator to communicate via ROS, you must launch the ROS node instead.

The communications server listens at TCP port 23700 by default. If that port is used by another program, mvsim launch picks the next free port (up to 23709) and prints a warning with its number. Set the environment variable MVSIM_SERVER_PORT to that number (or pass --port to mvsim topic and mvsim node) so other tools and the Python clients connect to the right server. If --port or MVSIM_SERVER_PORT is given, that exact port is required and an error is reported if it is not available.

Command mvsim server

$ mvsim server --help
Usage: mvsim server

Available options:
-p 23700, --port 23700   Listen on given TCP port.
-v, --verbosity      Set verbosity level: DEBUG, INFO (default), WARN, ERROR

MVSim uses a communication server, and then the simulation of the world happens in a client called “World”. This command can be used to launch an independent, new server. Normally you will not need to use this command unless you are developing a custom C++-based simulation based on the MVSim libraries.

Command mvsim node

$ mvsim node --help
Usage:

   mvsim node --help     Show this help
   mvsim node list       List all nodes connected to the server.

Request what MVSim network nodes are active and connected to the running server.

Command mvsim topic

$ mvsim topic --help
Usage:

   mvsim topic --help            Show this help
   mvsim topic list [--details]  List all advertised topics in the server
   mvsim topic echo <topicName>  Subscribe and print a topic
   mvsim topic hz <topicName>    Estimate topic publication rate (in Hz)

Can be used to list or inspect the publication of MVSim (not ROS!) topics with sensor and pose data. These topics are accessible via the provided Python API, refer to examples: https://github.com/MRPT/mvsim/tree/develop/examples_python

Command mvsim slice

$ mvsim slice --help
Usage: mvsim slice <WORLD_MODEL.xml> -o <OUTPUT.txt> [options]

Available options:
-o, --output <FILE>          Output .txt file (mandatory).
--slice-z <0.5>              Height of the slice [m].
--slice-z-max <z>            If given, the cells of all geometry between
                             --slice-z and this height [m] are reported.
--slice-resolution <0.05>    Cell size [m].
--slice-static-only          Skip blocks that are not <static> (movable).
-v, --verbosity              Set verbosity level: DEBUG, INFO (default), WARN, ERROR

Loads a world (without simulating it) and writes the occupied cells of a 2D grid where its geometry crosses a given height, or a height band, as 3D sensors would see it at t=0: the actual triangles of 3D models, walls with their doors and windows, primitives, point clouds and occupancy grid elements. Vehicles, actors and animated blocks are skipped, since they move. The output has one x y z line per occupied cell center, e.g. to build a static obstacle map for path planning. For example, as an mp2p_icp metric map:

$ mvsim slice demo_warehouse.world.xml -o obstacles.txt --slice-z 0.1 --slice-z-max 1.5
$ txt2mm -i obstacles.txt -o obstacles.mm -f xyz

Random expressions in the world file (e.g. $f{rand()}) give the same values as in a simulation only if the world fixes the random seed first, e.g. with <random_seed>1</random_seed> or <variable name="dummy" value="$f{randomize(1)}"></variable>.