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, set_fps=None, set_tps=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.
`air_fog`(fogDensity[, fogDepth, color_R, ...])	Changes the air fog density, depth, and color.
`change_time_of_day`(TimeOfDay)	Changes the world's time of day.
`change_weather`(weather)	Changes the weather 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_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_fps`(fps)	Sets the frames per second of the environment.
`set_rain_parameters`(vel_x, vel_y, vel_z, ...)	Changes the rain's velocity and spawn rate.
`set_render_quality`(render_quality[, ...])	Adjusts the rendering quality of HoloOcean.
`set_ticks_per_sec`(ticks_per_sec)	Sets the ticks per second of the environment.
`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, tick_clock])	Ticks the environment once.
`tide`(adjustment, bool)	Changes the water level.
`turn_off_flashlight`(flashlight_name)	Turns off the vehicle's flashlight.
`turn_on_flashlight`(flashlight_name[, ...])	Turns on the vehicle's flashlight and sets its visual parameters.
`water_color`(red, green, blue)	Changes the color of the water.
`water_fog`(fogDensity[, fogDepth, color_R, ...])	Changes the water fog density, depth, and color.

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. –

air_fog(fogDensity, fogDepth=3.0, color_R=0.45, color_G=0.5, color_B=0.6): Changes the air fog density, depth, and color. :param fogDensity: The density value for the fog. Range: 0.0 to 10.0. :type fogDensity: float :param fogDepth: The distance at which the fog begins. Range: 0.0 to 10.0. (Default = 3) :type fogDepth: float :param color_R: The red component of the fog’s color. Range: 0.0 to 1.0. (Default = 0.45) :type color_R: float :param color_G: The green component of the fog’s color. Range: 0.0 to 1.0. (Default = 0.5) :type color_G: float :param color_B: The blue component of the fog’s color. Range: 0.0 to 1.0. (Default = 0.6) :type color_B: float

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)

change_time_of_day(TimeOfDay)

Changes the world’s time of day.

Parameters:: TimeOfDay (float) – Time of day desired, a number between 0 and 23 inclusive.

change_weather(weather)

Changes the weather in the world.

Parameters:: weather (int) – The weather wanted (0 - sunny, 1 - cloudy, 2 - rainy).

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_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_fps(fps: int)

Sets the frames per second of the environment.

Parameters:: fps (int) – The desired frames per second. If set to 0, will max what it can do.

set_rain_parameters(vel_x, vel_y, vel_z, spawnRate)

Changes the rain’s velocity and spawn rate.

Parameters:

vel_x (float) – Rain velocity on the x axis.
vel_y (float) – VRain velocity on the y axis.
vel_z (float) – Rain velocity on the z axis. Should be a negative value.
spawnRate (float) – Rain’s spawn rate (number of particles).

set_render_quality(render_quality, should_keep_fps=False)

Adjusts the rendering quality of HoloOcean.

Parameters:

render_quality (int, boolean) – An integer between 0 = Low Quality and 3 = Epic quality.
second (The boolean is a) –
rate. (optional parameter that determines whether or not to maintain the FPS limit at the previously defined) –
true (If false the FPS max rate will be removed. Default behavior is to remove the FPS cap. If) –
maintained. (the previous FPS limit will be) –

set_ticks_per_sec(ticks_per_sec)

Sets the ticks per second of the environment.

Parameters:: ticks_per_sec (int) – The desired ticks per second.

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, tick_clock=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

tide(adjustment, bool)

Changes the water level.

Parameters:

adjustment (float) – Any positive/negative number that you want to adjust/set the water level to.
bool (float) – 0 if you want to adjust water level, and 1 if you want to set a new water level.

turn_off_flashlight(flashlight_name)

Turns off the vehicle’s flashlight.

Parameters:: flashlight_name (str) – The name of the flashlight to turn off. Vehicles have 4 flashlights (flashlight1-flashlight4)

turn_on_flashlight(flashlight_name, intensity=5000, beam_width=45, location_x_offset=0, location_y_offset=0, location_z_offset=0, angle_pitch=- 30, angle_yaw=0, color_R=1, color_G=1, color_B=1)

Turns on the vehicle’s flashlight and sets its visual parameters.

Parameters:

flashlight_name (str) – The name of the flashlight to turn on. (e.g., flashlight1)
intensity (float) – The brightness of the flashlight. Recommended range: 0 to 100000. (Default = 5000)
beam_width (float) – The beam’s spread angle in degrees. Recommended range: 1 to 80. (Default = 45)
location_x_offset (float) – x component of the flashlight location offset. (Default = 0)
location_y_offset (float) – y component of the flashlight location offset. (Default = 0)
location_z_offset (float) – z component of the flashlight location offset. (Default = 0)
angle_pitch (float) – The pitch angle (in degrees) for flashlight direction. Range: -70 to 70. (Default = -30)
angle_yaw (float) – The yaw angle (in degrees) for flashlight direction. Range: -70 to 70. (Default = 0)
color_R (float) – Red component of the flashlight color. Range: 0.0 to 1.0. (Default = 1)
color_G (float) – Green component of the flashlight color. Range: 0.0 to 1.0. (Default = 1)
color_B (float) – Blue component of the flashlight color. Range: 0.0 to 1.0. (Default = 1)

water_color(red, green, blue)

Changes the color of the water.

Parameters:

red (float) – A number between 0 and 1 to set the intensity of the red value.
green (float) – A number between 0 and 1 to set the intensity of the green value.
blue (float) – A number between 0 and 1 to set the intensity of the blue value.

water_fog(fogDensity, fogDepth=3.0, color_R=0.4, color_G=0.6, color_B=1.0): Changes the water fog density, depth, and color. :param fogDensity: The density value for the fog. Range: 0.0 to 10.0. :type fogDensity: float :param fogDepth: The distance at which the fog begins. Range: 0.0 to 10.0. (Default = 3) :type fogDepth: float :param color_R: The red component of the fog’s color. Range: 0.0 to 1.0. (Default = 0.4) :type color_R: float :param color_G: The green component of the fog’s color. Range: 0.0 to 1.0. (Default = 0.6) :type color_G: float :param color_B: The blue component of the fog’s color. Range: 0.0 to 1.0. (Default = 1.0)tt :type color_B: float