Environments

Module containing the environment interface for HoloOcean. An environment contains all elements required to communicate with a world binary or HoloOceanCore editor.

It specifies an environment, which contains a number of agents, and the interface for communicating with the agents.

Classes:

HoloOceanEnvironment([agent_definitions, ...])

Proxy for communicating with a HoloOcean world

class holoocean.environments.HoloOceanEnvironment(agent_definitions=None, binary_path=None, window_size=None, start_world=True, uuid='', gl_version=4, verbose=False, pre_start_steps=2, show_viewport=True, ticks_per_sec=None, frames_per_sec=None, copy_state=True, scenario=None)

Proxy for communicating with a HoloOcean world

Instantiate this object using holoocean.holoocean.make().

Parameters:

agent_definitions (list of AgentDefinition) – Which agents are already in the environment
binary_path (str, optional) – The path to the binary to load the world from. Defaults to None.
window_size ((int,:obj:int)) – height, width of the window to open
start_world (bool, optional) – Whether to load a binary or not. Defaults to True.
uuid (str) – A unique identifier, used when running multiple instances of holoocean. Defaults to “”.
gl_version (int, optional) – The version of OpenGL to use for Linux. Defaults to 4.
verbose (bool) – If engine log output should be printed to stdout
pre_start_steps (int) – Number of ticks to call after initializing the world, allows the level to load and settle.
show_viewport (bool, optional) – If the viewport should be shown (Linux only) Defaults to True.
ticks_per_sec (int, optional) – The number of frame ticks per unreal seconds. This will override whatever is in the configuration json. Defaults to 30.
frames_per_sec (int or bool, optional) – The max number of frames ticks per real seconds. This will override whatever is in the configuration json. If True, will match ticks_per_sec. If False, will not be turned on. If an integer, will set to that value. Defaults to true.
copy_state (bool, optional) – If the state should be copied or returned as a reference. Defaults to True.
scenario (dict) – The scenario that is to be loaded. See Scenario File Format for the schema.

Methods:

`act`(agent_name, action)	Supplies an action to a particular agent, but doesn't tick the environment.
`add_agent`(agent_def[, is_main_agent])	Add an agent in the world.
`draw_arrow`(start, end[, color, thickness, ...])	Draws a debug arrow in the world
`draw_box`(center, extent[, color, thickness, ...])	Draws a debug box in the world
`draw_line`(start, end[, color, thickness, ...])	Draws a debug line in the world
`draw_point`(loc[, color, thickness, lifetime])	Draws a debug point in the world
`get_joint_constraints`(agent_name, joint_name)	Returns the corresponding swing1, swing2 and twist limit values for the
`get_ocean_current_fields_count`()	Get the number of ocean current fields.
`get_reward_terminal`()	Returns the reward and terminal state
`info`()	Returns a string with specific information about the environment.
`move_viewport`(location, rotation)	Teleport the camera to the given location
`reset`()	Resets the environment, and returns the state.
`send_acoustic_message`(id_from, id_to, ...)	Send a message from one beacon to another.
`send_optical_message`(id_from, id_to, msg_data)	Sends data between various instances of OpticalModemSensor
`send_world_command`(name[, num_params, ...])	Send a world command.
`set_control_scheme`(agent_name, control_scheme)	Set the control scheme for a specific agent.
`set_ocean_current_field_index`(index)	Set the ocean current field index.
`set_ocean_current_multiplier`(multiplier)	Set the ocean current strength multiplier.
`set_ocean_current_offset`(offset)	Set the ocean current position offset.
`set_render_quality`(render_quality)	Adjusts the rendering quality of HoloOcean.
`set_show_vector_field_name`(state)	Set whether to show the vector field name in the viewport.
`should_render_viewport`(render_viewport)	Controls whether the viewport is rendered or not
`spawn_prop`(prop_type[, location, rotation, ...])	Spawns a basic prop object in the world like a box or sphere.
`step`(action[, ticks, publish])	Supplies an action to the main agent and tells the environment to tick once.
`tick`([num_ticks, publish])	Ticks the environment once.

Attributes:

`action_space`	Gives the action space for the main agent.
`beacons`	Gets all instances of AcousticBeaconSensor in the environment.
`beacons_id`	Gets all ids of AcousticBeaconSensor in the environment.
`beacons_status`	Gets all status of AcousticBeaconSensor in the environment.
`modems`	Gets all instances of OpticalModemSensor in the environment.
`modems_id`	Gets all ids of OpticalModemSensor in the environment.

act(agent_name, action)

Supplies an action to a particular agent, but doesn’t tick the environment.: Primary mode of interaction for multi-agent environments. After all agent commands are supplied, they can be applied with a call to tick.

Parameters:

agent_name (str) – The name of the agent to supply an action for.
action (np.ndarray or list) – The action to apply to the agent. This action will be applied every time tick is called, until a new action is supplied with another call to act.

property action_space

Gives the action space for the main agent.

Returns:: The action space for the main agent.
Return type:: ActionSpace

add_agent(agent_def, is_main_agent=False)

Add an agent in the world.

It will be spawn when tick() or step() is called next.

The agent won’t be able to be used until the next frame.

Parameters:

agent_def (AgentDefinition) – The definition of the agent to
spawn.

property beacons

Gets all instances of AcousticBeaconSensor in the environment.

Returns:: List of all AcousticBeaconSensor in environment
Return type:: (list of AcousticBeaconSensor)

property beacons_id

Gets all ids of AcousticBeaconSensor in the environment.

Returns:: List of all AcousticBeaconSensor ids in environment
Return type:: (list of int)

property beacons_status

Gets all status of AcousticBeaconSensor in the environment.

Returns:: List of all AcousticBeaconSensor status in environment
Return type:: (list of str)

draw_arrow(start, end, color=None, thickness=10.0, lifetime=1.0)

Draws a debug arrow in the world

Parameters:

start (list of float) – The start [x, y, z] location in meters of the line. (see Coordinate System)
end (list of float) – The end [x, y, z] location in meters of the arrow
color (list) – [r, g, b] color value (from 0 to 255). Defaults to [255, 0, 0] (red).
thickness (float) – Thickness of the arrow. Defaults to 10.
lifetime (float) – Number of simulation seconds the object should persist. If 0, makes persistent. Defaults to 1.

draw_box(center, extent, color=None, thickness=10.0, lifetime=1.0)

Draws a debug box in the world

Parameters:

center (list of float) – The start [x, y, z] location in meters of the box. (see Coordinate System)
extent (list of float) – The [x, y, z] extent of the box
color (list) – [r, g, b] color value (from 0 to 255). Defaults to [255, 0, 0] (red).
thickness (float) – Thickness of the lines. Defaults to 10.
lifetime (float) – Number of simulation seconds the object should persist. If 0, makes persistent. Defaults to 1.

draw_line(start, end, color=None, thickness=10.0, lifetime=1.0)

Draws a debug line in the world

Parameters:

start (list of float) – The start [x, y, z] location in meters of the line. (see Coordinate System)
end (list of float) – The end [x, y, z] location in meters of the line
color (list`) – [r, g, b] color value (from 0 to 255). Defaults to [255, 0, 0] (red).
thickness (float) – Thickness of the line. Defaults to 10.
lifetime (float) – Number of simulation seconds the object should persist. If 0, makes persistent. Defaults to 1.

draw_point(loc, color=None, thickness=10.0, lifetime=1.0)

Draws a debug point in the world

Parameters:

loc (list of float) – The [x, y, z] start of the box. (see Coordinate System)
color (list of float) – [r, g, b] color value (from 0 to 255). Defaults to [255, 0, 0] (red).
thickness (float) – Thickness of the point. Defaults to 10.
lifetime (float) – Number of simulation seconds the object should persist. If 0, makes persistent. Defaults to 1.

get_joint_constraints(agent_name, joint_name)

Returns the corresponding swing1, swing2 and twist limit values for the: specified agent and joint. Will return None if the joint does not exist for the agent.

Returns:: np.ndarray

get_ocean_current_fields_count(): Get the number of ocean current fields. :returns: The number of ocean current fields. :rtype: int

get_reward_terminal()

Returns the reward and terminal state

Returns:

A 2tuple:

Reward (float): Reward returned by the environment.
Terminal: The bool terminal signal returned by the environment.

Return type:

(float, bool)

info()

Returns a string with specific information about the environment. This information includes which agents are in the environment and which sensors they have.

Returns:: Information in a string format.
Return type:: str

property modems

Gets all instances of OpticalModemSensor in the environment.

Returns:: List of all OpticalModemSensor in environment
Return type:: (list of OpticalModemSensor)

property modems_id

Gets all ids of OpticalModemSensor in the environment.

Returns:: List of all OpticalModemSensor ids in environment
Return type:: (list of int)

move_viewport(location, rotation)

Teleport the camera to the given location

By the next tick, the camera’s location and rotation will be updated

Parameters:

location (list of float) – The [x, y, z] location to give the camera (see Coordinate System)
rotation (list of float) – The x-axis that the camera should look down. Other 2 axes are formed by a horizontal y-aixs, and then the corresponding z-axis. (see Rotations)

reset()

Resets the environment, and returns the state. If it is a single agent environment, it returns that state for that agent. Otherwise, it returns a dict from agent name to state.

Returns:: Returns the same as tick.
Return type:: tuple or dict

send_acoustic_message(id_from, id_to, msg_type, msg_data)

Send a message from one beacon to another.

Parameters:

id_from (int) – The integer ID of the transmitting modem.
id_to (int) – The integer ID of the receiving modem.
msg_type (str) – The message type. See holoocean.sensors.AcousticBeaconSensor for a list.
msg_data – The message to be transmitted. Currently can be any python object.

send_optical_message(id_from, id_to, msg_data)

Sends data between various instances of OpticalModemSensor

Parameters:

id_from (int) – The integer ID of the transmitting modem.
id_to (int) – The integer ID of the receiving modem.
msg_data – The message to be transmitted. Currently can be any python object.

send_world_command(name, num_params=None, string_params=None)

Send a world command.

A world command sends an abitrary command that may only exist in a specific world or package. It is given a name and any amount of string and number parameters that allow it to alter the state of the world.

If a command is sent that does not exist in the world, the environment will exit.

Parameters:

name (str) – The name of the command, ex “OpenDoor”
(obj (string_params) – list of int): List of arbitrary number parameters
(obj – list of string): List of arbitrary string parameters

set_control_scheme(agent_name, control_scheme)

Set the control scheme for a specific agent.

Parameters:

agent_name (str) – The name of the agent to set the control scheme for.
control_scheme (int) – A control scheme value (see ControlSchemes)

set_ocean_current_field_index(index: int): Set the ocean current field index. :param index: The index of the ocean current field to use. :type index: int

set_ocean_current_multiplier(multiplier)

Set the ocean current strength multiplier.

Parameters:: multiplier (float) – The multiplier to apply to the ocean current.

set_ocean_current_offset(offset): Set the ocean current position offset. :param offset: The offset to apply to the ocean current. :type offset: list of float

set_render_quality(render_quality)

Adjusts the rendering quality of HoloOcean.

Parameters:: render_quality (int) – An integer between 0 = Low Quality and 3 = Epic quality.

set_show_vector_field_name(state)

Set whether to show the vector field name in the viewport.

Parameters:: state (bool) – Whether to show the vector field name in the viewport.

should_render_viewport(render_viewport)

Controls whether the viewport is rendered or not

Parameters:: render_viewport (boolean) – If the viewport should be rendered

spawn_prop(prop_type, location=None, rotation=None, scale=1, sim_physics=False, material='', tag='')

Spawns a basic prop object in the world like a box or sphere.

Prop will not persist after environment reset.

Parameters:

prop_type (string) – The type of prop to spawn. Can be box, sphere, cylinder, or cone.
location (list of float) – The [x, y, z] location of the prop.
rotation (list of float) – The [roll, pitch, yaw] rotation of the prop.
scale (list of float) or (float) – The [x, y, z] scalars to the prop size, where the default size is 1 meter. If given a single float value, then every dimension will be scaled to that value.
sim_physics (boolean) – Whether the object is mobile and is affected by gravity.
material (string) – The type of material (texture) to apply to the prop. Can be white, gold, cobblestone, brick, wood, grass, steel, or black. If left empty, the prop will have the a simple checkered gray material.
tag (string) – The tag to apply to the prop. Useful for task references.

step(action, ticks=1, publish=True)

Supplies an action to the main agent and tells the environment to tick once. Primary mode of interaction for single agent environments.

Parameters:

action (np.ndarray) – An action for the main agent to carry out on the next tick.
ticks (int) – Number of times to step the environment with this action. If ticks > 1, this function returns the last state generated.
publish (bool) – Whether or not to publish as defined by scenario. Defaults to True.

Returns:

A dictionary from agent name to its full state. The full state is another dictionary from holoocean.sensors.Sensors enum to np.ndarray, containing the sensors information for each sensor. The sensors always include the reward and terminal sensors. Reward and terminals can also be gotten through get_reward_terminal().

Will return the state from the last tick executed.

Return type:

dict

tick(num_ticks=1, publish=True)

Ticks the environment once. Normally used for multi-agent environments.

Parameters:

num_ticks (int) – Number of ticks to perform. Defaults to 1.
publish (bool) – Whether or not to publish as defined by scenario. Defaults to True.

Returns:

A dictionary from agent name to its full state. The full state is another dictionary from holoocean.sensors.Sensors enum to np.ndarray, containing the sensors information for each sensor. The sensors always include the reward and terminal sensors. Reward and terminals can also be gotten through get_reward_terminal().

Will return the state from the last tick executed.

Return type:

dict