Environments

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

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

Classes:

HolodeckEnvironment([agent_definitions, …])

Proxy for communicating with a Holodeck world

class holodeck.environments.HolodeckEnvironment(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=30, copy_state=True, scenario=None, max_ticks=9223372036854775807)

Proxy for communicating with a Holodeck world

Instantiate this object using holodeck.holodeck.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 holodeck. 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) – Number of frame ticks per unreal second. Defaults to 30.

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

  • ( (max_ticks) – obj: int, optional): The number of ticks to be run before returning to the terminal and cancels the tick function

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.

check_max_tick()

Increments tick counter ‘_total_ticks’ and throws a HolodeckException if the _max_ticks limit has been met.

clean_up_resources()

Frees up references to mapped memory files.

get_joint_constraints(agent_name, joint_name)

Returns the corresponding swing1, swing2 and twist limit values for the

get_main_agent()

Returns the main agent in the environment

graceful_exit(_signum, _frame)

Signal handler to gracefully exit the script

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_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_render_quality(render_quality)

Adjusts the rendering quality of Holodeck.

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])

Supplies an action to the main agent and tells the environment to tick once.

tick([num_ticks])

Ticks the environment once.

Attributes:

action_space

Gives the action space for the main agent.

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.

check_max_tick()

Increments tick counter ‘_total_ticks’ and throws a HolodeckException if the _max_ticks limit has been met.

clean_up_resources()

Frees up references to mapped memory files.

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

obj )

Return type

(

get_main_agent()

Returns the main agent in the environment

graceful_exit(_signum, _frame)

Signal handler to gracefully exit the script

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

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 [roll, pitch, yaw] rotation to give the camera (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 (tuple or dict):

For single agent environment, returns the same as step.

For multi-agent environment, returns the same as tick.

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

Send a world command.

A world command sends an arbitrary 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

  • (objlist 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_render_quality(render_quality)

Adjusts the rendering quality of Holodeck.

Parameters

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

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, like the Location Task.

step(action, ticks=1)

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.

Returns

A 4tuple:
  • State: Dictionary from sensor enum

    (see HolodeckSensor) to np.ndarray.

  • Reward (float): Reward returned by the environment.

  • Terminal: The bool terminal signal returned by the environment.

  • Info: Any additional info, depending on the world. Defaults to None.

Return type

(dict, float, bool, info)

tick(num_ticks=1)

Ticks the environment once. Normally used for multi-agent environments. :param num_ticks: Number of ticks to perform. Defaults to 1. :type num_ticks: int

Returns

A dictionary from agent name to its full state. The full state is another

dictionary from holodeck.sensors.Sensors enum to np.ndarray, containing the sensors information for each sensor. The sensors always include the reward and terminal sensors.

Will return the state from the last tick executed.

Return type

dict