pysphinx API Reference Documentation#

class pysphinx.Sphinx#

This is a class communicating with Sphinx via a stateless JSON-RPC protocol.

Constructor method.

Parameters:
  • ip (str) – IP address used by the JSON-RPC server run by sphinx

  • port (int) – port used by the JSON-RPC server run by sphinx

get_all_actor_components()#

Returns the list pysphinx.Component objects that belong to the actor in the world.

Returns:

a list of actor pysphinx.Component objects

Return type:

list

get_all_params()#

Returns a dictionary of all object parameters.

Returns:

a dictionary object of object parameters or None

Return type:

dict

get_areas(filter_regex='.*')#

Returns a list of areas in the world.

Parameters:

filter_regex (str) – a regex to filter out area names

Returns:

a list of areas

Return type:

list

get_camera(machine_name, camera_name, max_frames=1)#

Returns a pysphinx.cameras.Camera object.

The instance must be released by the caller by destroying it or by calling its release method.

Optional arg max_frames represents the maximum number of frames that can be held at a given time (for libvideo-ipc only)

Parameters:
  • machine_name (str) – the name of the machine

  • camera_name (str) – the name of the camera

  • max_frames (int) – the maximum number of client frames

Returns:

a pysphinx.cameras.Camera object

Return type:

pysphinx.cameras.Camera

get_camera_names(machine_name)#

Returns the list of camera names.

Parameters:

machine_name (str) – the name of the machine

Returns:

a list of camera names

Return type:

list

get_component(machine_name, name, type_)#

Returns a Component object

Parameters:
  • machine_name (str) – the name of the machine

  • name (str) – the name of the component

  • type (str) – the type of the component

Returns:

a pysphinx.Component object if component exists, None otherwise.

Return type:

pysphinx.Component

get_component_info(machine_name, name, type_)#

Returns information on a component.

Parameters:
  • machine_name (str) – the name of the machine

  • name (str) – the name of the component

  • type (str) – the type of the component

Returns:

a dictionary object describing the component or None

Return type:

dict

get_default_machine_name()#

Returns the name of the default machine.

Returns:

the name of the first machine that was found or None

Return type:

str

get_drone_tlm(machine_name, section_name)#

Returns a telemetry.TlmSection object produced by the drone.

Parameters:
  • machine_name (str) – the name of the machine

  • section_name (str) – the name of the telemetry section

Returns:

a telemetry.TlmSection object

Return type:

telemetry.TlmSection

get_info()#

Returns information on the running simulation.

Returns:

a dictionary object of information or None

Return type:

dict

get_machine_names()#

Returns the list of machine names.

Returns:

the list of machine names or None

Return type:

list

get_object_param(machine_name, object_name, param)#

Returns the value of an object parameter.

Parameters:
  • machine_name (str) – the name of the machine

  • object_name (str) – the name of the object

  • param (str) – the name of the parameter

Returns:

the value of the object parameter or None.

Return type:

str

get_simulation_tlm(section_name)#

Returns a :py:class`telemetry.TlmSection` object produced by a sphinx component.

Note that telemetry.TlmSection objects are stored in a cache to limit the number of JSON-RPC requests.

Parameters:

section_name (str) – the name of the telemetry section

Returns:

a :py:class`telemetry.TlmSection` object

Return type:

telemetry.TlmSection

get_sphinx_version()#

Returns sphinx’s version number.

Returns:

sphinx’s version number or __undefined__

Return type:

str

get_surrounding_areas(machine_name, filter_regex='.*')#

Returns a list of areas surrounding a machine in the world.

Parameters:
  • machine_name (str) – the name of the machine

  • filter_regex (str) – a regex to filter out area names

Returns:

a list of areas

Return type:

list

get_world_name()#

Returns the world’s name.

Returns:

the world’s name or __undefined__

Return type:

str

is_position_valid(position, timeout=1, min_collision_radius=0.0, max_height_above_ground=0.0)#

Checks if a position is valid in the world.

By default, a position is valid if it is located above the ground. Optional parameters can be set to test other conditions.

Parameters:
  • position (list) – a position [x, y, z] to be tested

  • timeout (int) – timeout for the task to complete in seconds

  • min_collision_radius (float) – the radius of a sphere positioned at the coordinates provided by position. If this value is greater than zero, a collision test is performed with the sphere shape. If a collision is detected with a surrounding object, the position is invalid

  • max_height_above_ground (float) – the maximum height above the ground that the position can be at. If this value is greater than zero and the condition is not met, the position is invalid.

Returns:

True if the position is valid, False otherwise

Return type:

bool

is_world_reset_running()#

Checks to see if a world reset is currently running.

Returns:

True if reset is running, False otherwise.

Return type:

bool

set_object_param(machine_name, object_name, param, value)#

Sets the value of an object parameter.

Parameters:
  • machine_name (str) – the name of the machine

  • object_name (str) – the name of the object

  • param (str) – the name of the parameter

  • value (str) – the value of the parameter

Returns:

True if setting the value was successful, False otherwise

Return type:

bool

trig_object_action(machine_name, object_name, action)#

Triggers an object action.

Parameters:
  • machine_name (str) – the name of the machine

  • component (str) – the name of the component

  • param (str) – the name of the action

Returns:

True if the action was triggered, False otherwise

Return type:

bool

class pysphinx.Component#

This is a class representation of a component object in Sphinx.

It uses a Sphinx object to communicate with Sphinx.

Constructor method.

Parameters:
  • sphinx – a Sphinx object

  • machine_name – the name of the machine

  • component_name – the name of the component

  • component_type – the type of the component

  • port – the port used by the JSON-RPC server run by sphinx

get_object_name()#

Returns the object name of this component.

Returns:

the object name of this component

Return type:

str

get_param(param)#

Returns the value of a component’s parameter.

Parameters:

param (str) – the name of the parameter

Returns:

the value of the parameter or None

Return type:

str

get_tlm()#

Returns the TlmSection object for this component.

Returns:

a TlmSection object

Return type:

TlmSection

get_tlm_section_name()#

Returns the name of the telemetry section produced by this component.

Returns:

the name of the telemetry section

Return type:

str

set_param(param, value)#

Sets the value of a component’s parameter.

Parameters:
  • param (str) – the name of the parameter

  • value (str) – the value of the parameter

Returns:

True if setting the value was successful, False otherwise

Return type:

bool

trig_action(action)#

Triggers an action on the component.

Parameters:

action (str) – the name of the action

Returns:

True if the action was triggered, False otherwise

Return type:

bool

class pysphinx.cameras.Camera#

This is a class representation of a camera object in Sphinx.

read(timeout=None)#

Gets a reference to a frame.

The reference must be released by the caller by destroying it or by calling its release method.

if timeout is None: block until a frame is received if timeout is 0: try to get a frame, do not block. otherwise: block until the given number of seconds is spent

Parameters:

timeout (int) – timeout value in seconds

Returns:

a pysphinx.cameras.Frame object if no timeout, None otherwise.

Return type:

pysphinx.cameras.Frame

release()#

Releases the camera.

Release all frames and disconnect from the server.

class pysphinx.cameras.Frame#

This is a class representation of a frame generated by a Camera object.

imshow(window_name, text_desc=None)#

Displays the image in the specified window.

Parameters:
  • window_name (str) – the name of the window in which the image will be displayed

  • text_desc (str) – tuple describing text overlay (None if not used)

imwrite(outdir, label, outformat=None)#

Saves the image to a specified file.

Parameters:
  • outdir (str) – the path to the directory where the image will be saved

  • label (str) – the label to use when saving the frame on disk

  • outformat (str) – the file format

Returns:

the path of the created image in case of success. None otherwise.

Return type:

str

release()#

Releases the frame.

All resources associated with the frame in the client will be freed as well.