Building worlds at runtime
Robots, obstacles and other world elements can be inserted into a running simulation, and removed later, without reloading the world. For example, to place the obstacles of each trial of an experiment, to add robots as a test requires them, or to build a whole scenario from an external program.
Entities are given as world XML: the same tags as in a *.world.xml file.
They are complete simulation entities: they collide, their sensors (including
cameras and LiDARs) produce data, and they show up in the GUI. When removed,
their sensors, physics bodies, joints and visualization go away too.
For lightweight visual-only objects, such as marks drawn on the ground or debug overlays, see Runtime objects and ground truth instead.
What can be inserted
Any tags valid in a world file, optionally enclosed in a <mvsim_world> root
tag:
Entities:
<vehicle>,<block>and<element>(e.g. ahorizontal_planeor anoccupancy_grid).Helpers:
<include>,<vehicle:class>,<block:class>,<variable>,<for>and<if>.
Rules:
Relative paths (e.g. in
<include>) are resolved with respect to the directory of the world file loaded by the simulator, unless another base directory is given.Names must be unique. Elements have no name in world files: when inserted at runtime, they get a unique
element_<N>name, so they can be removed.Insertion is all or nothing: if anything fails (e.g. an XML error or a name already in use), nothing is inserted.
Removal works by name, for vehicles, blocks, elements, and also runtime objects.
A world with just the ground, to build everything at runtime, is provided as
mvsim_tutorial/demo_empty.world.xml.
From ROS 2
The mvsim_node offers the standard simulator services of the
simulation_interfaces
package (if it was found when building MVSim):
Service |
Description |
|---|---|
|
Inserts entities from MVSim world XML ( |
|
Removes an entity by name. |
|
Names of all entities, optionally filtered by a regular expression. |
|
Pose and velocity of an entity, in the |
|
Moves an entity, and/or sets its velocity. |
|
Lists the supported features. |
The spawn_entity request fields work as follows:
name(optional) andinitial_pose(if it is not the identity) override those in the XML, which must then define exactly one<vehicle>,<block>or<element>. Withinitial_pose,<init_pose>is not required in the XML.allow_renaming: if the name is taken, a suffix_1,_2… is added instead of failing.entity_namespacemust be empty or equal to the name: vehicles inserted at runtime always publish their topics under their name (e.g./bot1/cmd_vel).The response
entity_namelists the names of all inserted entities, separated by commas.
Example: start an empty world, then insert a robot with a 2D LiDAR and a camera, drive it, and remove it:
ros2 launch mvsim launch_world.launch.py \
world_file:=$(ros2 pkg prefix mvsim)/share/mvsim/mvsim_tutorial/demo_empty.world.xml
# In another terminal:
ros2 service call /spawn_entity simulation_interfaces/srv/SpawnEntity \
"{name: bot1, entity_resource: {resource_string: '
<include file=\"../definitions/jackal.vehicle.xml\" default_sensors=\"true\"/>
<vehicle name=\"bot1\" class=\"jackal\"/>'},
initial_pose: {pose: {position: {x: 2.0, y: 1.0}}}}"
ros2 topic pub -r 10 /bot1/cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.5}}"
ros2 service call /get_entity_state simulation_interfaces/srv/GetEntityState \
"{entity: bot1}"
ros2 service call /delete_entity simulation_interfaces/srv/DeleteEntity \
"{entity: bot1}"
Several entities in one call, e.g. a row of boxes made with a <for> loop:
ros2 service call /spawn_entity simulation_interfaces/srv/SpawnEntity \
"{entity_resource: {resource_string: '
<for var=\"i\" from=\"0\" to=\"4\">
<block name=\"box_\${i}\">
<static>true</static> <zmin>0</zmin> <zmax>0.5</zmax> <color>#a06020</color>
<shape><pt>-0.25 -0.25</pt><pt>0.25 -0.25</pt><pt>0.25 0.25</pt><pt>-0.25 0.25</pt></shape>
<init_pose>\$f{2+\${i}} -2 0</init_pose>
</block>
</for>'}}"
ros2 service call /get_entities simulation_interfaces/srv/GetEntities \
"{filters: {filter: '^box_'}}"
From a file (uri with a file path or a file:// URI; relative paths in it
are resolved wrt the file directory):
ros2 service call /spawn_entity simulation_interfaces/srv/SpawnEntity \
"{entity_resource: {uri: '/path/to/my_obstacles.xml'}}"
Move an object:
ros2 service call /set_entity_state simulation_interfaces/srv/SetEntityState \
"{entity: box_0, set_pose: true, state: {pose: {position: {x: -5.0, y: -5.0}}}}"
Note
With
simulation_interfacesolder than 2.0 (ROS 2 Humble and Jazzy), the spawn resource fields are nameduriandresource_string(noentity_resource), andset_entity_statehas noset_pose/set_twistflags: it always sets both.Service names are relative to the node namespace, so they can be remapped.
Robots loaded with the world keep their usual topic names: without a namespace if the world has only one vehicle, unless
force_publish_vehicle_namespaceis set.
From Python or any ZMQ client
Services insert_entities (SrvInsertEntities: the XML, and optionally a
base directory for relative paths; it returns the names of the new entities)
and remove_entities (SrvRemoveEntities, by names).
from mvsim_comms import pymvsim_comms
from mvsim_msgs import SrvInsertEntities_pb2, SrvInsertEntitiesAnswer_pb2
from mvsim_msgs import SrvRemoveEntities_pb2, SrvRemoveEntitiesAnswer_pb2
client = pymvsim_comms.mvsim.Client()
client.setName("my-app")
client.connect()
req = SrvInsertEntities_pb2.SrvInsertEntities()
req.xml = """
<include file="../definitions/jackal.vehicle.xml" default_sensors="false" />
<vehicle name="bot1" class="jackal"> <init_pose>2 2 0</init_pose> </vehicle>
"""
ans = SrvInsertEntitiesAnswer_pb2.SrvInsertEntitiesAnswer()
ans.ParseFromString(client.callService('insert_entities', req.SerializeToString()))
print(ans.success, ans.errorMessage, list(ans.names))
req = SrvRemoveEntities_pb2.SrvRemoveEntities()
req.names.append('bot1')
ans = SrvRemoveEntitiesAnswer_pb2.SrvRemoveEntitiesAnswer()
ans.ParseFromString(client.callService('remove_entities', req.SerializeToString()))
A complete example, which also drives the new robot, is
examples_python/insert-entities-example.py:
mvsim launch mvsim_tutorial/demo_empty.world.xml &
python3 examples_python/insert-entities-example.py
From C++
#include <mvsim/World.h>
// Returns the names of the new entities; throws on errors:
const auto names = world.insertEntitiesFromXML(R"(
<block name="box1">
<static>true</static> <zmin>0</zmin> <zmax>1</zmax>
<shape><pt>-0.5 -0.5</pt><pt>0.5 -0.5</pt><pt>0.5 0.5</pt><pt>-0.5 0.5</pt></shape>
<init_pose>2 0 0</init_pose>
</block>)");
// Overriding the name and pose of a single entity:
mvsim::World::InsertOptions opts;
opts.name = "box2";
opts.pose = mrpt::math::TPose3D(4.0, 1.0, 0, 0, 0, 0);
world.insertEntitiesFromXML(xmlOfOneBlock, opts);
world.removeEntity("box1"); // false if not found
// To react to insertions and removals (e.g. to create ROS publishers):
world.registerCallbackOnEntityChange(
[](const mvsim::World::EntityChange& c)
{ std::cout << (c.added ? "added: " : "removed: ") << c.name << "\n"; });
insertEntitiesFromXML() and removeEntity() must not run at the same time
as run_simulation(): call them from the thread that runs the simulation, or
from any other thread through runInSimulationThread(), which runs them at the
start of the next run_simulation() call:
auto fut = world.runInSimulationThread([&]() { world.removeEntity("box2"); });
fut.get(); // waits for it, and rethrows its exceptions