Proposal to add support for managing simulation worlds

CMakeLists.txt

@@ -23,15 +23,19 @@ set(msg_files
     "msg/EntityInfo.msg"
     "msg/EntityState.msg"
     "msg/NamedPose.msg"
+    "msg/Resource.msg"
     "msg/Result.msg"
     "msg/SimulationState.msg"
     "msg/SimulatorFeatures.msg"
     "msg/Spawnable.msg"
     "msg/TagsFilter.msg"
+    "msg/WorldResource.msg"
 )
 
 set(srv_files
     "srv/DeleteEntity.srv"
+    "srv/GetAvailableWorlds.srv"
+    "srv/GetCurrentWorld.srv"
     "srv/GetEntities.srv"
     "srv/GetEntitiesStates.srv"
     "srv/GetEntityBounds.srv"
@@ -42,12 +46,14 @@ set(srv_files
     "srv/GetSimulationState.srv"
     "srv/GetSimulatorFeatures.srv"
     "srv/GetSpawnables.srv"
+    "srv/LoadWorld.srv"
     "srv/ResetSimulation.srv"
     "srv/SetEntityInfo.srv"
     "srv/SetEntityState.srv"
     "srv/SetSimulationState.srv"
     "srv/SpawnEntity.srv"
     "srv/StepSimulation.srv"
+    "srv/UnloadWorld.srv"
 )
 
 set(action_files

README.md

@@ -23,3 +23,7 @@ Some interfaces represent optional utility and are considered lower priority:
 - [GetNamedPoses](srv/GetNamedPoses.srv)
 - [GetSpawnables](srv/GetSpawnables.srv)
 - [SetEntityInfo](srv/SetEntityInfo.srv)
+- [GetAvailableWorlds](srv/GetAvailableWorlds.srv)
+- [LoadWorld](srv/LoadWorld.srv)
+- [UnloadWorld](srv/UnloadWorld.srv)
+- [GetCurrentWorld](srv/GetCurrentWorld.srv)

msg/Resource.msg

@@ -0,0 +1,7 @@
+# This message is used to specify a resource, either by a URI or by its string content.
+
+string uri              # If uri field is empty, resource_string must not be empty.
+
+string resource_string  # An entity definition file passed as a string, only used if uri is empty.
+                        # If uri field is not empty, resource_string field will be ignored.
+                        # Simulators may support spawning from a file generated on the fly (e.g. XACRO).

msg/SimulationState.msg

@@ -1,16 +1,24 @@
 # Simulation states used in SetSimulationState and returned in GetSimulationState
 
-uint8 STATE_STOPPED      = 0           # Simulation is stopped, which is equivalent to pausing and resetting with ALL.
-                                       # This is typically the default state when simulator is launched.
-                                       # Stopped simulation can be played. It can also be paused, which means
-                                       # starting simulation in a paused state immediately,
-                                       # without any time steps for physics or simulated clock ticks.
-uint8 STATE_PLAYING      = 1           # Simulation is playing, can be either paused or stopped.
-uint8 STATE_PAUSED       = 2           # Simulation is paused, can be either stopped (which will reset it) or played.
-uint8 STATE_QUITTING     = 3           # Closing the simulator application. Switching from STATE_PLAYING or STATE_PAUSED
-                                       # states is expected to stop the simulation first, and then exit.
-                                       # Simulation interfaces will become unavailable after quitting.
-                                       # Running simulation application is outside of the simulation interfaces as
-                                       # there is no service to handle the call when the simulator is not up.
+uint8 STATE_STOPPED          = 0           # Simulation is stopped, which is equivalent to pausing and resetting with ALL_PAUSED.
+                                           # This is typically the default state when simulator is launched.
+                                           # Stopped simulation can be played. It can also be paused, which means
+                                           # starting simulation in a paused state immediately,
+                                           # without any time steps for physics or simulated clock ticks.
 
+uint8 STATE_PLAYING          = 1           # Simulation is playing, can be either paused or stopped.
+
+uint8 STATE_PAUSED           = 2           # Simulation is paused, can be either stopped (which will reset it) or played.
+
+uint8 STATE_QUITTING         = 3           # Closing the simulator application. Switching from STATE_PLAYING or STATE_PAUSED
+                                           # states is expected to stop the simulation first, and then exit.
+                                           # Simulation interfaces will become unavailable after quitting.
+                                           # Running simulation application is outside of the simulation interfaces as
+                                           # there is no service to handle the call when the simulator is not up.
+
+uint8 STATE_NO_WORLD         = 4           # Simulation world is currently unloaded.
+                                           # The simulation is inactive and cannot be started, stopped, or paused.
+
+uint8 STATE_LOADING_WORLD    = 5           # Simulation world is currently loading.
+                                           # The simulation is inactive while world is loading and cannot be started, stopped, or paused.
 uint8 state

msg/SimulatorFeatures.msg

@@ -31,6 +31,12 @@ uint8 STEP_SIMULATION_MULTIPLE  = 32      # Supports multi-stepping through simu
                                           # service or through SimulateSteps action.
 uint8 STEP_SIMULATION_ACTION    = 33      # Supports SimulateSteps action interface.
 
+uint8 WORLD_LOADING             = 40      # Supports LoadWorld interface
+uint8 WORLD_RESOURCE_STRING     = 41      # Supports LoadWorld resource_string field
+uint8 WORLD_TAGS                = 42      # Supports world tags and tag filtering
+uint8 WORLD_UNLOADING           = 43      # Supports UnloadWorld interface
+uint8 WORLD_INFO_GETTING        = 44      # Supports GetCurrentWorld interface
+uint8 AVAILABLE_WORLDS          = 45      # Supports GetAvailableWorlds interface
 
 uint16[] features                         # A list of simulation features as specified by the list above.
 

msg/Spawnable.msg

@@ -1,5 +1,7 @@
 # Robot or other object which can be spawned in simulation runtime.
 
-string uri                                # URI which will be accepted by SpawnEntity service.
+Resource entity_resource                  # The resource (e.g. URDF, SDF) for the model to be spawned.
+
 string description                        # Optional description for the user, e.g. "robot X with sensors A,B,C".
+
 Bounds spawn_bounds                       # Optional spawn area bounds which fully encompass this object.

msg/WorldResource.msg

@@ -0,0 +1,15 @@
+# World is a virtual environment in which the simulation happens.
+# Worlds are also known as scenes or levels in some simulators.
+# Depending on the world format, loading of a world might be associated with changes
+# in certain parameters, including physics settings such as gravity.
+# World resources may be defined in standard or simulation-specific formats,
+# and, depending on the simulator, loaded from local or remote repositories. 
+
+
+string name                               # World name, which is not necessarily unique.
+
+Resource world_resource                   # The resource for the world to be loaded.
+
+string description                        # Optional custom description of the world
+
+string[] tags                             # Optional tags describing the world (e.g., "indoor", "outdoor", "warehouse")

package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>simulation_interfaces</name>
-  <version>1.0.1</version>
+  <version>2.0.0</version>
   <description>A package containing simulation interfaces including messages, services and actions</description>
   <maintainer email="adam.dabrowski@robotec.ai">Adam Dabrowski</maintainer>
   <license>Apache License 2.0</license>

srv/GetAvailableWorlds.srv

@@ -0,0 +1,23 @@
+# Return a list of available world resources which can be used with LoadWorld.
+# Support for this interface is indicated through the AVAILABLE_WORLDS value in GetSimulatorFeatures.
+# By default, a simulator will search its default local and online sources. If some
+# default sources can't be accessed (e.g. due to connectivity issues), the
+# DEFAULT_SOURCES_FAILED error result code will be returned.
+
+string[] additional_sources             # Optional field for additional sources (local or remote) to search, 
+                                        # specified as standard URIs if possible.
+
+TagsFilter filter                       # Only get worlds with tags matching the filter. The filter is optional and matches everything by default.
+                                        # This feature is supported if WORLD_TAGS feature is included in output of GetSimulatorFeatures.
+
+bool offline_only                       # If true, only offline/local sources should be searched. Defaults to false.
+
+bool continue_on_error                  # If true, the simulator will continue to search sources even if some fail.
+                                        # The service will return success if any source yielded worlds. Defaults to false.
+---
+
+uint8 DEFAULT_SOURCES_FAILED = 101      # Some default sources could not be accessed.
+
+Result result                           # Standard result message. A specific result code should be used if some sources were not accessible.
+
+WorldResource[] worlds                  # Available world resources.

srv/GetCurrentWorld.srv

@@ -0,0 +1,10 @@
+# Get information about the currently loaded world in the simulation.
+# Support for this interface is indicated through the WORLD_INFO_GETTING value in GetSimulatorFeatures.
+
+---
+
+uint8 NO_WORLD_LOADED = 101     # No world is loaded at the moment.
+
+Result result                   # Standard result message
+
+WorldResource world             # Information about the currently loaded world. Only valid if result is RESULT_OK.

srv/LoadWorld.srv

@@ -0,0 +1,29 @@
+# Load a simulation world from a file or resource.
+# This means clearing the current scene (removing all entities), loading the new world and setting the simulation to the stopped state.
+# Support for this interface is indicated through the WORLD_LOADING value in GetSimulatorFeatures.
+# resource_string field support is indicated through the WORLD_RESOURCE_STRING value in GetSimulatorFeatures.
+# Currently loaded worlds will be unloaded before attempting to load a new one.
+# Any previously spawned entities will be removed. Once a world is loaded, simulation will be left in a Stopped state.
+
+string uri                                  # Resource such as SDF, USD, MJCF, or other simulator-native format world file.
+
+string resource_string                      # Simulation world passed as a string. This field is used if the uri field is empty.
+
+bool fail_on_unsupported_element            # Fail on unsupported elements (such as SDFormat sub-tags). By default, such elements are ignored.
+
+
+bool ignore_missing_or_unsupported_assets   # Ignore missing or unsupported assets. By default, missing or unsupported assets result in failure.
+
+---
+
+uint8 UNSUPPORTED_FORMAT = 101              # Format for uri or resource string is unsupported.
+uint8 NO_RESOURCE = 102                     # Both uri and resource string are empty.
+uint8 RESOURCE_PARSE_ERROR = 103            # Resource file or string failed to parse.
+uint8 MISSING_ASSETS = 104                  # At least one of resource assets (such as meshes) was not found.
+uint8 UNSUPPORTED_ASSETS = 105              # At least one of resource assets (such as meshes) is not supported.
+uint8 UNSUPPORTED_ELEMENTS = 106            # At least one of world definition elements such as format tags is unsupported.
+
+
+Result result                               # Standard result message
+
+WorldResource world                         # Information about the loaded world. Only valid if result is RESULT_OK.

srv/SpawnEntity.srv

@@ -11,15 +11,13 @@ string name                             # A name to give to the spawned entity.
 bool allow_renaming                     # Determines whether the spawning succeeds with a non-unique name.
                                         # If it is set to true, the user should always check entity_name response field
                                         # and use it for any further interactions.
-string uri                              # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc.
-                                        # Valid URIs can be determined by calling GetSpawnables first, and you can check
-                                        # the simulator format support by reading SimulatorFeatures spawn_formats field.
-                                        # If uri field is empty, resource_string must not be empty.
-string resource_string                  # An entity definition file passed as a string.
-                                        # Simulators may support spawning from a file generated on the fly (e.g. XACRO).
-                                        # It is supported by your simulator if GetSimulatorFeatures includes
-                                        # SPAWNING_RESOURCE_STRING feature.
-                                        # If uri field is not empty, resource_string field will be ignored.
+
+Resource entity_resource                # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc.
+                                        # Valid URIs can be determined by calling GetSpawnables first. 
+                                        # Check simulator format support via the spawn_formats field in GetSimulatorFeatures.
+                                        # Using resource_string is supported if GetSimulatorFeatures includes
+                                        # the SPAWNING_RESOURCE_STRING feature.
+
 string entity_namespace                 # Spawn the entity with all its interfaces under this namespace.
 geometry_msgs/PoseStamped initial_pose  # Initial entity pose.
                                         # The header contains a reference frame, which defaults to global "world" frame.

srv/UnloadWorld.srv

@@ -0,0 +1,9 @@
+# Unload the current simulation world.
+# Support for this interface is indicated through the WORLD_UNLOADING value in GetSimulatorFeatures.
+# Any previously spawned entities will be removed.
+
+---
+
+uint8 NO_WORLD_LOADED = 101      # No world is loaded at the moment.
+
+Result result # Standard result message