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
logger – a logging module logger

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 and tags
Returns:: a list of areas
Return type:: list

get_async_camera(machine_name, camera_name, loop, callbacks, max_frames=1)#

Returns a pysphinx.cameras.VipcCameraAsync object. Works only with cameras using VIPC protocol.

The instance must be released by the caller by destroying it.

Optional arg max_frames represents the maximum number of frames that can be held at a given time

Parameters:

machine_name (str) – the name of the machine
camera_name (str) – the name of the camera
loop (ctypes libpomp loop) – libpomp loop object
callbacks (dict) –
dict of callbacks as follows.

{
‘status_cb’: lambda status, cam_name: True,

’configure_cb’: lambda config, cam_name: True,

’connection_cb’: lambda connected, cam_name: True,

’frame_cb’: lambda frame, cam_name: True,

’eos_cb’: lambda reason, cam_name: True

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

Returns:

a pysphinx.cameras.VipcCameraAsync object

Return type:

pysphinx.cameras.VipcCameraAsync

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_component_pose(machine_name, component_name, timestamp=None)#

Returns the pose of a component.

Parameters:

machine_name (str) – the name of the machine
machine_name – the name of the component
timestamp (float) – the timestamp of query (latest if None)

Returns:

the pose of the component or None

Return type:

(float, float, float, float, float, float)

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_pose(machine_name, timestamp=None)#

Returns the pose of a drone.

Parameters:

machine_name (str) – the name of the machine
timestamp (float) – the timestamp of query (latest if None)

Returns:

the pose of the drone or None

Return type:

(float, float, float, float, float, float)

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_encountered_objects(start_position, end_position, show_debug=False, timeout=1, keep_alive=False)#

Checks if there are obstacles between two given points.

Parameters:

start_position (list) – a position [x, y, z] where the detection starts.
end_position (list) – a position [x, y, z] where the detection ends.
show_debug (bool) – a flag to whether or not show line traces inside the Unreal Engine’s application.
timeout (int) – timeout for the task to complete in seconds
keep_alive (bool) – if True, the connection with Sphinx is preserved. That way, the next calls are faster. This requires to call the stop method when the program terminates.

Returns:

a dictionary with the following format. “obstacle_name –> thickness”. The thickness is zero if the object is NOT double-sided.

Return type:

dict

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_action_description(machine_name, object_name, action)#

Returns the description of an object action.

Action machine_name:: the name of the machine
Action object_name:: the name of the object
Action action:: the name of the action
Returns:: the description of the action
Return type:: str

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_object_param_description(machine_name, object_name, param)#

Returns the description 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 description of the parameter

Return type:

str

get_object_param_possible_values(machine_name, object_name, param)#

Returns the possible values 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 possible values of the object parameter or None.

Return type:

list

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_spherical_coordinates_converter()#

Returns the spherical coordinates converter.

Returns:: a :py:class`pysphinx.SphericalCoordinatesConverter` object on success, None otherwise
Return type:: pysphinx.SphericalCoordinatesConverter

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 and tags

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, keep_alive=False)#

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.
keep_alive (bool) – if True, the connection with Sphinx is preserved. That way, the next calls are faster. This requires to call the stop method when the program terminates.

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

move_drone(machine_name, pose_offset, pose_ref=None, start_condition='true', pose_duration=0.1, timeout=None)#

Moves the drone at a pose relative to a reference pose according to the given offset.

Note that pose_offset and pose_ref are 6-tuples that can contain scalar values as well as ExprTk expressions, where val represents the current value.

If no reference pose is provided, the world origin is used.

Parameters:

machine_name (str) – the name of the machine
pose_offset ((any, any, any, any, any, any)) – the pose offset as a tuple
pose_ref ((any, any, any, any, any, any)) – the reference pose
pose_duration (float) – the amount of time the drone will remain in this pose in seconds
start_condition (str) – an ExprTk expression which determines when the drone will be moved (by default, the drone is moved immediately)
timeout (float) – timeout for the task to complete in seconds (ignored if pose_offset or pose_ref contain string values)

Returns:

True if setting the pose was successful, 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
logger – a logging module logger

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.

destroy()#

Destroys the camera.

Release all frames and disconnect from the server.

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:

True if getting the frame was successful, False otherwise
a pysphinx.cameras.Frame object if no timeout, the reason why stream is stopping when the stream is finished, None otherwise.

Return type:

bool, pysphinx.cameras.Frame

release()#

Releases the camera. DEPRECATED API (use destroy).

Release all frames and disconnect from the server.

started()#

Returns the camera state.

Returns:: True if stream is started, False otherwise
Return type:: bool

class pysphinx.cameras.Frame#

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

imshow(window_name, text_desc=None, maxdepth_meters=15)#

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, maxdepth_meters=15)#

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.