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
- 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:
- 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:
- 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
- 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
andpose_ref
are 6-tuples that can contain scalar values as well as ExprTk expressions, whereval
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
objectmachine_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.