Add array spawn service.

[michalpelka]

Simulation interfaces can be used to populate scene with assets or props, depending on the scenario.
I would like to propose the way to ask underlying simulator to spawn multiple objects.

Motivation:

• with such API client code can be simpler - one call to a service.
• with such API simulator can optimize spawning process and do it swift.

[ayushgnv]

I think this is a great addition for sim interfaces package and would vote to merge this in. @azeey @peci1 any thoughts on this?

[jhanca-robotecai]

Please bump the version of the package.

[peci1]

Hmm, I don't like this approach of making each field an array. However, given the fact that a service request (IMO) cannot be reused elsewhere, it is probably the best possible solution without going awkward (like specifying a standalone message type for the request part).

Please, see the inline comments.

[peci1]

Please bump the version of the package.

I guess version bumps are done when releasing the package, so I wouldn't expect the bump to be a part of this PR.

[ayushgnv]

Hi @michalpelka, when you get a chance could you review the comments by @peci1? Once we have those resolved I think it would be good to merge this in soon!

[michalpelka]

@ayushgnv @peci1 thanks for review I've updated contribution candidate.

[peci1]

A few style changes and more info, but otherwise it looks good now!

[azeey]

Should these error codes start from a larger number (e.g. 150 or 200) so that there's more room for error codes in

simulation_interfaces/srv/SpawnEntity.srv

Lines 29 to 41 in 5af2e29

	# Additional result.result_code values for this service. Check result.error_message for further details.
	uint8 NAME_NOT_UNIQUE = 101 # Given name is already taken by entity and allow_renaming is false.
	uint8 NAME_INVALID = 102 # Given name is invalid in the simulator (e.g. does not meet naming
	# requirements such as allowed characters). This is also returned if name is
	# empty and allow_renaming is false.
	uint8 UNSUPPORTED_FORMAT = 103 # Format for uri or resource string is unsupported. Check supported formats
	# through GetSimulatorFeatures service, in spawn_formats field.
	uint8 NO_RESOURCE = 104 # Both uri and resource string are empty.
	uint8 NAMESPACE_INVALID = 105 # Namespace does not meet namespace naming standards.
	uint8 RESOURCE_PARSE_ERROR = 106 # Resource file or string failed to parse.
	uint8 MISSING_ASSETS = 107 # At least one of resource assets (such as meshes) was not found.
	uint8 UNSUPPORTED_ASSETS = 108 # At least one of resource assets (such as meshes) is not supported.
	uint8 INVALID_POSE = 109 # initial_pose is invalid, such as when the quaternion is invalid or position

to expand? Also, any reason why the two error codes are incremented by 10?

[azeey]

Is this saying the names array can be empty or that individual elements of the array can be the empty string?

[tfoote]

At a high level I have a few questions. I agree that the parallel construction of arrays in this case doesn't really make sense. It would make more sense to support a single array with all the variables captured in a single message aka make

simulation_interfaces/srv/SpawnEntity.srv

Lines 4 to 25 in 5af2e29

	string name # A name to give to the spawned entity.
	# If empty, a name field in the uri file or resource_string will be used,
	# if supported and not empty (e.g. "name" field in SDFormat, URDF).
	# If the name is still empty or not unique (as determined by the simulator),
	# the service returns a generated name in the entity_name response field if the
	# allow_renaming field is set to true. Otherwise, the service call fails and an
	# error is returned.
	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.
	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.
	# This frame must be known to the simulator, e.g. of an object spawned earlier.
	# The timestamp field in the header is ignored.

into SpawningEntity.msg and then have SpawnEntities contain SpawningEntity [] entities

And if we do that. Is there a reason to support two interfaces one for a single entity and one for batch processing. Can the single entity not just be the redundant case of multiple entities where the iterator is just length 1.

If the message is supporting multiple entities, then you can also group the return type as per entity and return an array of { Results + name } => EntitySpawnResult [] results

With a multiple entity spawning capability defined this way I would then suggest deprecating the singular version of the interface as it will increase the burden for all implementations. And for the deprecation cycle the implementers can provide backwards compatibilty by wrapping the single version into an array and reuse the batch processing interface.

[peci1]

Is there a reason to support two interfaces one for a single entity and one for batch processing.

At least in CLI usage there may be a big difference. Usually tab completion just completes an empty array and that's it.