Client Documentation 

Client 

class projectairsim.ProjectAirSimClient(address='127.0.0.1', port_topics=8989, port_services=8990)

connect(connect_retries=10): Connects to the server

disconnect(): Disconnects from the server

get_task_name(task: Task) → str: Retrieves the name of an asyncio task

get_topic_info(): This is used by World to get the list of topic info on reload scene.

on_topic_info(_, topic_info_msg): Callback function used by get_topic_info

postprocess_response(response): Performs error handling, type checking, casting etc. on a response message

async postprocess_response_async_with_callback(response, callback: callable) → None: Helper function that for asynchronously postprocessing a response

preprocess_request(request): Internal function for processing requests before they are sent

publish(topic, message): Publishes a message to a given server topic

request(request_data) → Any

Makes a synchronous request to the Sim server and returns the response

Parameters:: request_data (Dict) – Request object as per JSON-RPC spec for named parameters with the “jsonrpc” field replaced by “version”. Example: {“method”: “/xyz”, “params”: {“data”: b”123abc”}, “version”: 1.0, “id”: 1} Note: The “params” field should have the “data” member
Raises:: RuntimeError – When a Timeout exception is raised by NNG while processing the request
Returns:: Response for the request
Return type:: Any

async request_async(request_data, callback=None) → Task

Asynchronously send request to the Sim server and return response

Parameters:

request_data (Dict) – Request message dict: {“method”: …, “params”: …, “version”: …}
callback (Callable) – Callback to call when request is complete

Returns:

Returns a awaitable Task that wraps the coroutine for: processing the result of the requested API call.

Return type:

asyncio.Task

static request_id_generator() → int: Static method to generate request IDs

set_authorization_token(token: str) → datetime

Set the client authorization token.

Returns:: datatime when the token expires

set_interactive_feature(feature_name, enabled): Sets the state of an interactive feature

set_task_name(task: Task, task_name: str) → None: Sets the name of an asyncio task

subscribe(topic, callback, reliability=1.0)

Subscribes to a server topic

Parameters:

topic (str) – the name of the topic
callback (callable) – function to call when data is received

try_send(msg, max_retries=5): Attempts to send a message up to max_retries times

unsubscribe(topics)

Unsubscribes from one or more server topics

Parameters:: topics (str or List) – the topics. can be given as a string for one topic or a list for multiple

unsubscribe_all(): Unsubscribes from all server topics

update_subscription_options(topic, reliability)

Updates settings of a server topic

Parameters:: topic (str) – the name of the topic

World 

class projectairsim.World(client: ProjectAirSimClient, scene_config_name: str = '', delay_after_load_sec: int = 0, sim_config_path: str = 'sim_config/', sim_instance_idx: int = -1, actual_load: bool = True)

continue_for_n_steps(n_steps: int, wait_until_complete: bool = True) → int

Continue sim for N steps and then pause

Parameters:

n_steps (int) – the number of steps to continue for
wait_until_complete (bool) – if true, this function will wait until the time has passed before returning

Returns:

the sim time when the function returns

Return type:

int

continue_for_sim_time(delta_time_nanos: int, wait_until_complete: bool = True) → int

Continue sim for delta_time_nanos and then pause

Parameters:

delta_time_nanos (int) – the number of nanoseconds to continue for
wait_until_complete (bool) – if true, this function will wait until the time has passed before returning

Returns:

the sim time when the function returns

Return type:

int

continue_for_single_step(wait_until_complete: bool = True) → int

Continue sim for a single step and then pause

Parameters:: wait_until_complete (bool) – if true, this function will wait until the time has passed before returning
Returns:: the sim time when the function returns
Return type:: int

continue_until_sim_time(target_time_nanos: int, wait_until_complete: bool = True) → int

Continue sim until target_time_nanos and then pause

Parameters:

target_time_nanos (int) – the time in nanoseconds to pause at
wait_until_complete (bool) – if true, this function will wait until the time has passed before returning

Returns:

the sim time when the function returns

Return type:

int

create_voxel_grid(position: Transform, x_size, y_size, z_size, resolution, n_z_resolution=1, use_segmentation: bool = False, actors_to_ignore=[], write_file=False, file_path='./voxel_grid.binvox') → List[int]

Create a voxel grid of the scene

Parameters:

position (Pose) – Pose for the center of the voxel grid
x_size (int) – x-size of the desired grid in m
y_size (int) – y-size of the desired grid in m
z_size (int) – z-size of the desired grid in m
resolution (int) – resolution of the grid in m/voxels
actors_to_ignore (list) – IDs of actors to ignore for occupancy
write_file (bool) – Write voxel grid to a binvox file
file_path (str) – Path to write the binvox file to

Returns:

Occupancy map of the scene.

Return type:

List(bool)

destroy_all_spawned_objects() → str

Destroy all spawned objects in the scene

Returns:: whether the operation was successful
Return type:: bool

destroy_object(object_name: str) → str

Destroy an object in the scene

Parameters:: object_name (str) – the name of the object to destroy
Returns:: whether the object was destroyed
Return type:: bool

disable_weather_visual_effects() → bool

Disable weather visual effects

Returns:: whether the operation was successful
Return type:: bool

enable_weather_visual_effects() → bool

Enable weather visual effects

Returns:: whether the operation was successful
Return type:: bool

flush_persistent_markers() → bool

Clears debug items, including those plotted with ‘is_persistent’ = True

Returns:: True if successful
Return type:: bool

get_3d_bounding_box(object_name: str, box_alignment: BoxAlignment) → Dict

Gets the 3D bounding box of some object in the scene.

Parameters:

object_name (str) – Name of the object to get the bbox for.
box_alignment (BoxAlignment) – whether the bounding box is aligned to the world axes or object axes

Returns:

dict representing a 3D bbox.

Return type:

Dict

get_cloud_shadow_strength() → float

Get cloud shadow strength

Returns:: the cloud shadow strength, from 0.0 to 1.0
Return type:: float

get_configuration() → Dict

Get the current configuration that has been loaded to the sim server

Returns:: the configuration
Return type:: Dict

get_object_pose(object_name: str) → Transform

Get a scene object’s pose

Parameters:: object_name (str) – the object to get information about
Returns:: the object pose
Return type:: Pose

get_object_poses(object_names: List[str]) → List[Transform]

Get multiple scene objects’ poses

Parameters:: object_names (List[str]) – the objects to be read
Returns:: the object poses corresponding to the objects in object_names, in the same order
Return type:: List[Pose]

get_object_rpy_quat_from_config(object: Dict) → List[float]

Processes object and extracts rotation info depending on presence of rpy or rpy-deg

Parameters:: object (Dict) – a Dict with all of the object’s info
Returns:: rotation given as a [w, x, y, z] quaternion
Return type:: List[float]

get_object_scale(object_name: str) → List

Get a scene object’s scale (x, y, z)

Parameters:: object_name (str) – the object to get information about
Returns:: the scale as a 3-item list [x,y,z]
Return type:: List[float]

get_random_free_position_near_path(path: ~typing.List[~typing.List[float]], radius_min: float = 20.0, radius_max: float = 30.0, resolution: float = 2.0, maximum_z: float = 0, max_retries: int = 10, minimum_distance_along_path: float = 10.0) -> (typing.Dict, typing.List[float], <class 'int'>)

Finds a free position near a random point on a path

Parameters:

path (List[List[float]]) – a list of path points, in NED coordinates
radius_min (float) – the minimum distance from the path
radius_max (float) – the maximum distance from the path
resolution (float) – resolution of the voxel grid used to determine if positions are free
maximum_z (float) – the maximum z value of the chosen point. prevents points underground from being picked
max_retries (int) – the maximum number of attempts made to find a valid point
include_start (bool) – whether the first leg of the path is a valid location to choose

Returns:

(the chosen position, the point on the path that it is near, the leg of the path the point is on)

Return type:

Tuple

get_random_free_position_near_point(point: Dict, radius_min: float = 20.0, radius_max: float = 30.0, resolution: float = 2.0, maximum_z: float = 0, max_retries: int = 10) → Dict

Finds a free position near a point

Parameters:

point (Dict) – the point to center the search around, in NED coordinates
radius_min (float) – the minimum distance from the center of the chosen point
radius_max (float) – the maximum distance from the center of the chosen point
resolution (float) – resolution of the voxel grid used to determine if positions are free
maximum_z (float) – the maximum z value of the chosen point. prevents points underground from being picked
max_retries (int) – the maximum number of attempts made to find a valid point

Returns:

the located position

Return type:

Dict

get_segmentation_id_by_name(mesh_name: str, use_owner_name: bool) → int

Get the assigned segmentation ID of an object by name

Parameters:

mesh_name (str) – Name of object to get the segmentation ID for (matching is case insensitive, but must match all characters)
use_owner_name (bool) – Flag to match with the mesh component’s owner’s name (usually the actor name) to match with instead of the mesh component’s name

Returns:

The segmentation ID for the object named mesh_name,: or -1 if not found

Return type:

int

get_segmentation_id_map() → Dict

Get the assigned segmentation ID of all objects

Returns:: A map from object name to segmentation ID
Return type:: Dict

get_sim_clock_type() → str

Get sim clock type

Returns:: the sim clock type (“steppable” or “real-time”)
Return type:: string

get_sim_time() → int

Get current sim time in nanoseconds

Returns:: the sim time in nanoseconds
Return type:: int

get_sunlight_intensity() → float

Get sun light intensity

Returns:: the sun light intensity from 0-75000 lux
Return type:: get_light_intensity (float)

get_surface_elevation_at_point(x: float, y: float) → float

Gets the height of the ground at a given point

Parameters:

x (float) – x-coordinate of the point in m
y (float) – y-coordinate of the point in m

Returns: height of the ground at the given point in m

get_time_of_day() → str

Get the time of day

Returns:: a string containing the time of day in the format %Y-%m-%d %H:%M:%S
Return type:: str

get_weather_visual_effects_param() → Dict[int, float]

Get the current weather visual effects parameters

Returns:: the current weather visual effects parameters. The keys are the WeatherParameter enum values, and the values are the intensity of the weather.
Return type:: Dict[int, float]

get_wind_velocity() → tuple

Returns the current global wind velocity as a tuple

Returns:: a tuple (x,y,z) of global wind velocities in m/s
Return type:: tuple

import_geo_trajectory(traj_name: str, time: List[float], latitudes: List[float], longitudes: List[float], altitudes: List[float], roll: List[float] = None, pitch: List[float] = None, yaw: List[float] = None, vel_lin_x: List[float] = None, vel_lin_y: List[float] = None, vel_lin_z: List[float] = None) → None

Imports a geodetic trajectory

Parameters:

traj_name (str) – the name of the trajectory
time (List[float]) – times for each trajectory point, in seconds
latitudes (List[float]) – latitudes for each trajectory point
longitudes (List[float]) – longitudes for each trajectory point
altitudes (List[float]) – altitudes, in meters for each trajectory point
roll (List[float]) – rolls, in radians for each trajectory point
pitch (List[float]) – pitches, in radians for each trajectory point
yaw (List[float]) – yaws, in radians for each trajectory point
vel_lin_x (List[float]) – x-velocities for each trajectory point, in meters per second
vel_lin_y (List[float]) – y-velocities for each trajectory point, in meters per second
vel_lin_z (List[float]) – z-velocities for each trajectory point, in meters per second

import_ned_trajectory(traj_name: str, time: List[float], pose_x: List[float], pose_y: List[float], pose_z: List[float], pose_roll: List[float] = None, pose_pitch: List[float] = None, pose_yaw: List[float] = None, vel_lin_x: List[float] = None, vel_lin_y: List[float] = None, vel_lin_z: List[float] = None) → None

Imports a NED trajectory

Parameters:

traj_name (str) – the name of the trajectory
time (List[float]) – times for each trajectory point, in seconds
pose_x (List[float]) – x poses for each trajectory point, in meters
pose_y (List[float]) – y poses for each trajectory point, in meters
pose_z (List[float]) – z poses for each trajectory point, in meters
pose_roll (List[float]) – rolls for each trajectory point, in radians
pose_pitch (List[float]) – pitches for each trajectory point, in radians
pose_yaw (List[float]) – yaws for each trajectory point, in radians
vel_lin_x (List[float]) – x-velocities for each trajectory point, in meters per second
vel_lin_y (List[float]) – y-velocities for each trajectory point, in meters per second
vel_lin_z (List[float]) – z-velocities for each trajectory point, in meters per second

import_ned_trajectory_from_csv(traj_name: str, filename: str, delimiter_str: str = ',', n_lines_to_skip: int = 1) → None

Imports a NED Trajectory from a CSV file

First row of the file is the header. Numerical data begins from n_lines_to_skip + 1. Each row corresponds to trajectory data at a given time instance, where the column order is 1) time (s) 2) pose_x (m) 3) pose_y (m) 4) pose_z (m) 5) pose_roll (rad) 6) pose_pitch (rad) 7) pose_yaw (rad) 8) vel_lin_x (m/s) 9) vel_lin_y (m/s) 10) vel_lin_z (m/s)

Parameters:

traj_name (str) – the name of the trajectory
filename (str) – the name of the file to read
delimiter_str (str) – the delimiter used in the file
n_lines_to_skip (int) – the number of lines at the top of the file to skip

import_trajectory_from_kml(traj_name: str, time: List[float], filename: str) → None

Imports a kml file as a trajectory

Parameters:

traj_name (str) – name of the trajectory
time (List[float]) – times for each trajectory point, in seconds
filename (str) – name of the kml file

is_paused() → bool

Check if sim is paused

Returns:: true if paused, false otherwise
Return type:: bool

list_actors() → List[str]

List actor names in the scene

Returns:: a list of actor names
Return type:: List[str]

list_assets(name_regex: str = '.*') → List

List available static and blueprint assets matching a regex

Parameters:: {str} (name_regex) – the regex to match asset names against
Returns:: a list of the available asset names
Return type:: {List}

list_objects(name_regex: str) → List

List scene object names matching a regex

Parameters:: name_regex (str) – the regex to match object names against
Returns:: a list of object names
Return type:: List[str]

load_objects_via_file_from_config(objects: List[Dict]) → List[str]

Loads objects under the “from-file” field in the scene config to the scene

Parameters:: objects (List[Dict]) – a List of Dicts containing each object’s info
Returns:: the names of the “from-file” objects loaded from config
Return type:: List[str]

load_packaged_objects_from_config(objects: List[Dict]) → List[str]

Loads sim-packaged objects from the scene config to the scene

Parameters:: objects (List[Dict]) – a List of Dicts containing each object’s info
Returns:: the names of the sim-packaged objects loaded from config
Return type:: List[str]

load_scene(scene_config_dict: Dict, delay_after_load_sec: float = 0, actual_load: bool = True) → str

(Re)loads the sim scene config to the sim server

Parameters:

scene_config_dict (Dict) – a Dict with all scene configuration info
delay_after_load_sec (float) – time to sleep after loading the scene

Returns:

the id of the scene

Return type:

str

load_scene_objects_from_config(scene_objects: List[Dict]) → List[str]

Loads both sim-packaged objects or objects from file from the scene config to the scene

Parameters:: scene_objects (List[Dict]) – a List of Dicts containing each object’s info
Returns:: the names of the objects loaded from config
Return type:: List[str]

pause() → str

Pause simulation

Returns:: a human-readable string with the pause state and time
Return type:: string

plot_debug_arrows(points_start: List[List[float]], points_end: List[List[float]], color_rgba: List[float], thickness: float, arrow_size: float, duration: float, is_persistent: bool) → bool

Create debug arrows in the scene

Parameters:

points_start (List[List[float]]) – Vector of x,y,z arrow start points
points_end (List[List[float]]) – Vector of x,y,z arrow end points
color_rgba (List[float]) – [red, green, blue, alpha] values (range: 0.0 - 1.0)
thickness (float) – Thickness of arrow
arrow_size (float) – Size of the arrow
duration (float) – (seconds)
is_persistent (bool) – If True, ‘duration’ is ignored and arrows are displayed until removed by flush_persistent_markers()

Returns:

True if successful

Return type:

bool

plot_debug_dashed_line(points: List[List[float]], color_rgba: List[float], thickness: float, duration: float, is_persistent: bool) → bool

Create a dashed debug line in the scene. There must be an even number of points.

Parameters:

points (Lis(t[List[float]]) – Vector of x,y,z, points. Number of points must be even.
color_rgba (List[float]) – [red, green, blue, alpha] values (range: 0.0 - 1.0)
thickness (float) – Thickness of the line
duration (float) – (seconds)
is_persistent (bool) – If True, ‘duration’ is ignored and the line is displayed until removed by flush_persistent_markers()

Returns:

True if successful

Return type:

bool

plot_debug_points(points: List[List[float]], color_rgba: List[float], size: float, duration: float, is_persistent: bool) → bool

Create debug points in the scene

Parameters:

points (List[List[float]]) – Vector of x,y,z, points
color_rgba (List[float]) – [red, green, blue, alpha] values (range: 0.0 - 1.0)
size (float) – Size of the point
duration (float) – (seconds)
is_persistent (bool) – If True, ‘duration’ is ignored and points are displayed until removed by flush_persistent_markers()

Returns:

True if successful

Return type:

bool

plot_debug_solid_line(points: List[List[float]], color_rgba: List[float], thickness: float, duration: float, is_persistent: bool) → bool

Creates a solid debug line in the scene.

Parameters:

points (List[List[float]]) – Vector of x,y,z, points
color_rgba (List[float]) – [red, green, blue, alpha] values (range: 0.0 - 1.0)
thickness (float) – Thickness of the line
duration (float) – (seconds)
is_persistent (bool) – If True, ‘duration’ is ignored and the line is displayed until removed by flush_persistent_markers()

Returns:

True if successful

Return type:

bool

plot_debug_strings(strings: List[str], positions: List[List[float]], scale: float, color_rgba: List[float], duration: float) → bool

Create debug strings in the scene

Parameters:

srings (List[str]) – Vector of text to display
positions (List[List[float]]) – Vector of corresponding x,y,z locations to display text
scale (float) – Font scale
color_rgba (List[float]) – [red, green, blue, alpha] values (range: 0.0 - 1.0)
duration (float) – (seconds)

Returns:

True if successful

Return type:

bool

plot_debug_transforms(poses: List[Transform], scale: float, thickness: float, duration: float, is_persistent: bool) → bool

Create debug coordinate system indicators in the scene

Parameters:

poses (List[Pose]) – Vector of poses (translation + rotation) to display
scale (float) – Scale of transform
thickness (float) – Thickness of transform
duration (float) – (seconds)
is_persistent (bool) – If True, ‘duration’ is ignored and arrows are displayed until removed by flush_persistent_markers()

Returns:

True if successful

Return type:

bool

plot_debug_transforms_with_names(poses: List[Transform], names: List[str], tf_scale: float, tf_thickness: float, text_scale: float, text_color_rgba: List[float], duration: float) → bool

Create debug coordinate system indicators with text in the scene

Parameters:

poses (List[Pose]) – Vector of poses (translation + rotation) to display
names (List[str]) – Vector of text to display
tf_scale (float) – Scale of transform
tf_thickness (float) – Thickness of transform
text_scale (float) – Scale of text
text_color_rgba (List[float]) – [red, green, blue, alpha] values (range: 0.0 - 1.0)
duration (float) – (seconds)

Returns:

True if successful

Return type:

bool

reset_weather_effects() → bool

Returns all weather visual effects to their default levels

Returns:: whether the operation was successful
Return type:: bool

resume() → str

Resume simulation

Returns:: a human-readable string with the pause state and time
Return type:: string

set_cloud_shadow_strength(strength: float) → bool

Set cloud shadow strength

Parameters:: strength (float) – the cloud shadow strength, from 0.0 to 1.0
Returns:: true if successful, false otherwise
Return type:: bool

set_light_object_color(object_name: str, color_rgb: List[float]) → bool

Set a light object’s color :param object_name: name of the object to set the light intensity of :type object_name: str :param color_rgb: [red, green, blue] values (range: 0.0 - 1.0) :type color_rgb: List[float]

Returns:: whether the operation was successful or not
Return type:: bool

set_light_object_intensity(object_name: str, new_intensity: float) → bool

Set a light object’s intensity :param object_name: name of the object to set the light intensity of :type object_name: str :param new_intensity: light object’s new intesity value :type new_intensity: float :param (lux for directional lights: :type (lux for directional lights: see ue docs) for other light types :param unitless: :type unitless: see ue docs) for other light types

Returns:: whether the operation was successful or not
Return type:: bool

set_light_object_radius(object_name: str, new_radius: float) → bool

Set a light object’s atteniation radius (only affects point and spot lights) :param object_name: name of the object to set the light intensity of :type object_name: str :param new_radius: light object’s attenuation radius in meters :type new_radius: float

Returns:: whether the operation was successful or not
Return type:: bool

set_object_material(object_name: str, material_asset_path: str) → bool

Set a scene object’s material from the material name :param object_name: name of the object to set the material of :type object_name: str :param material_asset_path: path pointing to a packaged material asset :type material_asset_path: str

Returns:: whether the operation was successful or not
Return type:: bool

set_object_pose(object_name: str, object_pose: Transform, teleport: bool) → str

Set a scene object’s pose

Parameters:

object_name (str) – the object to move
object_pose (Pose) – the new pose
teleport (bool) – whether the object is teleported.

Returns:

whether the operation was successful

Return type:

bool

set_object_scale(object_name: str, object_scale: list) → str

Set a scene object’s scale (x, y, z)

Parameters:

object_name (str) – the object to change the scale of
object_scale (list) – the scale (x,y,z)

Returns:

true if successful, false otherwise

Return type:

bool

set_object_texture_from_file(object_name: str, texture_file_path: str) → bool

Set a scene object’s texture from a file (PNG)

Parameters:

object_name (str) – name of the object to change the texture of
texture_file_path (str) – PNG file path

Returns:

whether the operation was successful or not

Return type:

bool

set_object_texture_from_packaged_asset(object_name: str, texture_asset_path: str) → bool

Set a scene object’s material from a texture

Parameters:

object_name (str) – name of the object to set the material of
texture_asset_path (str) – path pointing to a packaged texture asset

Returns:

whether the operation was successful or not

Return type:

bool

set_object_texture_from_url(object_name: str, url: str) → bool

Set a scene object’s texture from a URL

Parameters:

object_name (str) – the object to change the texture of
url (str) – a url pointing to an image texture

Returns:

whether the operation was sucessful

Return type:

bool

set_segmentation_id_by_name(mesh_name: str, segmentation_id: int, is_name_regex: bool, use_owner_name: bool) → bool

Set the segmentation ID of object(s) by name

Parameters:

mesh_name (str) – Name of object(s) to set the segmentation ID. If is_name_regex is True, matching is case insensitive but must be a full regex match (ex: to ignore trailing chars,add ‘.*’ to end of pattern). If is_name_regex is False, matching must be exact including case.
segmentation_id (int) – Segmentation ID (0-255) to assign to the object(s)
is_name_regex (bool) – Flag to use regex matching or exact matching for name
use_owner_name (bool) – Flag to match with the mesh component’s owner’s name (usually the actor name) to match with instead of the mesh component’s name

Returns:

Status flag that’s True if any object was successfully: matched by mesh_name and had its segmentation ID set to the segmentation_id value

Return type:

bool

set_sun_position_from_date_time(date_time: datetime, is_dst: bool = False) → bool

Set the sun position from dateTime

Parameters:

datetime (str) – the time of day. Format must be Year-Month-Day Hour:Minute:Second
is_dst (bool) – whether the time given is a dst time

Returns:

whether the operation was sucessful

Return type:

bool

set_sunlight_intensity(intensity) → bool

Set sun light intensity

Parameters:: intensity (float) – the sun light intensity, from 0 to 75000 lux
Returns:: true if successful, false otherwise
Return type:: bool

set_time_of_day(status: bool, datetime: str, is_dst: bool, clock_speed: float, update_interval: float, move_sun: bool) → bool

Set the time of day

Parameters:

status (bool) – true to enable time of day, false to disable
datetime (str) – the time of day. Format must be Year-Month-Day Hour:Minute:Second
is_dst (bool) – whether the time given is a dst time
clock_speed (float) – the celestial clock speed. 1.0 is real time.
update_interval (float) – the frequency, in seconds, with which time of day should be updated
move_sun (bool) – whether the sun should be moved as the time of day changes

Returns:

whether the operation was sucessful

Return type:

bool

set_trace_line(color_rgba: List[float], thickness: float) → bool

Set trace line parameters.

Parameters:

color_rgba (List[float]) – [red, green, blue, alpha] values (range: 0.0 - 1.0)
thickness (float) – Thickness of line

Returns:

True if request sucessful

Return type:

bool

set_weather_visual_effects_param(param: int, value: float) → bool

Set a parameter for the weather visual effects

Parameters:

param (int) – the kind of weather to set. See WeatherParameter for legal values.
value (float) – the intensity of the weather, from 0.0 to 1.0

Returns:

whether the operation was successful

Return type:

bool

set_wind_velocity(v_x: float, v_y: float, v_z: float) → bool

Set global wind velocity by specifying velocity vector components

Parameters:

v_x (float) – the x-direction wind velocity in m/s
v_y (float) – the y-direction wind velocity in m/s
v_z (float) – the z-direction wind velocity in m/s

Returns:

true if successful, false otherwise

Return type:

bool

spawn_object(object_name: str, asset_path: str, object_pose: Transform, object_scale: List[float], enable_physics: bool) → str

Spawn an object in the scene using an asset packaged into the sim server

Parameters:

object_name (str) – name to be given to the spawned object
asset_path (str) – path to the asset in the sim server
object_pose (Pose) – the initial pose of the spawned object
object_scale (List[float]) – the scale (x,y,z) of the spawned object
enable_physics (bool) – whether the spawned object should be affected by physics

Returns:

the name of the spawned object. The name may have been modified to make it unique

Return type:

str

spawn_object_at_geo(object_name: str, asset_path: str, latitude: float, longitude: float, altitude: float, rotation: List[float], object_scale: List[float], enable_physics: bool) → str

Spawn an object in the scene using an asset packaged into the sim server, at the given geodetic coordinates

Parameters:

object_name (str) – name to be given to the spawned object
asset_path (str) – path to the asset in the sim server
latitude (float) – the latitude to spawn the object at, in degrees
longitude (float) – the longitude to spawn the object at, in degrees
altitude (float) – the altitude to spawn the object at, in meters
rotation (List[float]) – the rotation, as a [w,x,y,z] quaternion
object_scale (List[float]) – the scale (x,y,z) of the spawned object
enable_physics (bool) – whether the spawned object should be affected by physics

Returns:

the name of the spawned object. The name may have been modified to make it unique

Return type:

str

spawn_object_from_file(object_name: str, file_format: str, byte_array: bytes, is_binary: bool, object_pose: Transform, object_scale: List[float], enable_physics: bool) → str

Spawn an object in the scene using a client asset, passing the data to the sim server

Parameters:

object_name (str) – name to be given to the spawned object
file_format (str) – file format. Currently only supports “gltf”
byte_array (bytes) – the raw file data
is_binary (bool) – whether the file data is binary
object_pose (Pose) – the pose of the spawned object
object_scale (List[float]) – the scale of the spawned object, as [x,y,z]
enable_physics (bool) – whether the spawned object should be affected by physics

Returns:

the name of the spawned object. The name may have been modified to make it unique

Return type:

(str)

spawn_object_from_file_at_geo(object_name: str, file_format: str, byte_array: bytes, is_binary: bool, latitude: float, longitude: float, altitude: float, rotation: List[float], object_scale: List[float], enable_physics: bool) → str

Spawn an in the scene using a client asset, passing the data to the sim server, at the given geodetic coordinates

Parameters:

object_name (str) – name to be given to the spawned object
file_format (str) – file format. Currently only supports “gltf”
byte_array (bytes) – the raw file data
is_binary (bool) – whether the file data is binary
latitude (float) – the latitude to spawn the object at, in degrees
longitude (float) – the longitude to spawn the object at, in degrees
altitude (float) – the altitutde to spawn the object at, in meters
rotation (List[float]) – the rotation, as a [w,x,y,z] quaternion
object_scale (List[float]) – the scale of the spawned object, as [x,y,z]
enable_physics (bool) – whether the spawned object should be affected by physics

Returns:

the name of the spawned object. The name may have been modified to make it unique

Return type:

str

swap_object_texture(tag: str, tex_id: int) → List

Swap textures using IDs for all scene objects with specified actor tags (set in Editor’s actor details under the ‘Actor’ section, not the component tags in the ‘Tags’ section

Parameters:

tag (str) – the actor tag
text_id (int) – the texture id

Returns:

a list with the names of all affected objects

Return type:

List

switch_streaming_view() → bool

Switches the main view to the next available camera with “streaming-enabled”=true

Returns:: whether the operation was sucessful
Return type:: bool

toggle_trace() → bool

Toggle displaying the trace of the drone’s path.

Pressing ‘T’ while focused on the server viewport window also toggles displaying the trace.”

Returns:: True if request successful
Return type:: bool

Drone 

class projectairsim.Drone(client: ProjectAirSimClient, world: World, name: str)

arm() → bool

Arms vehicle

Returns:: True if drone is armed
Return type:: bool

camera_draw_frustum(camera_id: str, to_enable: bool, image_type: ImageType = ImageType.SCENE) → bool

Draws view frustum in the scene for the given camera.

Parameters:

camera_id (str) – the id of the camera to display the frustum for
image_type (ImageType) – the image-type for a specific capture setting
to_enable (bool) – True to enable, False to disable drawing

Returns:

True if successful

Return type:

{bool}

camera_look_at_object(camera_id: str, object_name: str, wait_for_pose_update: bool = True) → bool

Focuses camera onto an object of interest. A warning is: logged if the object is not in the scene and the camera pose will not change. To reset the camera pose, call reset_camera_pose().

Parameters:

camera_id (str) – the id of the camera to focus
object_name (str) – the name of the object to focus on
wait_for_pose_update (bool) – if true, the request will not return until the camera renderer has finished moving to the new pose

Returns:

True if successful

Return type:

bool

can_arm() → bool

Checks if the vehicle can be armed

Returns:: True if drone can be armed
Return type:: bool

cancel_last_task() → bool

Cancels vehicle’s last controller task

Returns:: True if task has been cancelled
Return type:: bool

disable_api_control() → bool

Disable drone control using API calls

Returns:: True if ApiControl is disabled
Return type:: bool

disarm() → bool

Disarms vehicle

Returns:: True if drone is disarmed
Return type:: bool

enable_api_control() → bool

Enable drone control using API calls

Returns:: True if ApiControl is enabled
Return type:: bool

get_airspeed_data(sensor_name: str) → Dict

Get latest Airspeed sensor data

Parameters:: sensor_name (str) – the configured name of the sensor
Returns:: (Dict) the Airspeed data as a dict

get_barometer_data(sensor_name: str) → Dict

Get latest Barometer sensor data

Parameters:: sensor_name (str) – the configured sensor name
Returns:: Dict of BarometerData
Return type:: Dict

get_battery_drain_rate(sensor_name: str) → Dict

Get the current battery drain rate

Returns:: the battery drain rate, in the same units as the configuration value
Return type:: float

get_battery_state(sensor_name: str) → Dict

Get latest Battery sensor data

Returns:: BatteryState
Return type:: Dict

get_estimated_geo_location() → Dict

Gets the estimated geo location of the drone

Returns:: the drone’s geo location from the drone’s state estimator, as a dict with keys “latitude”, “longitude”, and “altitude”
Return type:: Dict

get_estimated_kinematics() → Dict

Get estimated kinematics from the flight controller’s state estimator

Returns:: the Kinematics
Return type:: Dict

get_gps_data(sensor_name: str) → Dict

Get latest GPS sensor data

Parameters:: sensor_name (str) – the configured name of the sensor
Returns:: GPSData as a dict
Return type:: Dict

get_ground_truth_geo_location() → Dict

Gets the geo location of the drone

Returns:: the drone’s geo location, as a dict with keys “latitude”, “longitude”, and “altitude”
Return type:: Dict

get_ground_truth_kinematics() → Dict

Get ground truth kinematics

Returns:: the Kinematics
Return type:: Dict

get_ground_truth_pose() → Transform

Gets Pose for Drone

Returns:: the drone pose
Return type:: Pose

get_images(camera_id: str, image_type_ids: List[int]) → Dict

Get a set of images from a camera sensor (server will wait until the next: set of captured images is available with a sim timestamp >= sim time when the request was received)

Parameters:

camera_id (str) – the camera id to retrieve images from
image_type_ids (List[int]) – set of ImageTypes to retrieve

Returns:

dict of image data for the requested images with keys by type IDs

Return type:

Dict

get_imu_data(sensor_name: str) → Dict

Get latest IMU sensor data

Parameters:: sensor_name (str) – the configured name of the sensor
Returns:: ImuData as a dict
Return type:: Dict

get_landed_state() → LandedState

Checks if the vehicle is landed

Returns:: 0 if drone is landed, 1 if flying
Return type:: LandedState

get_magnetometer_data(sensor_name: str) → Dict

Get latest Magnetometer sensor data

Parameters:: sensor_name (str) – the configured sensor name
Returns:: The MagnetometerData
Return type:: Dict

get_ready_state() → Dict

Checks if the vehicle is ready

Returns:: whether the vehicle is ready, and a status message
Return type:: Dict

async go_home_async(timeout_sec=60, velocity=0.5, callback: callable = None) → Task

Return vehicle to Home i.e. Launch location

Parameters:

timeout_sec (int) – Timeout for the vehicle to reach home
velocity (float) – the speed at which to travel (m/s)
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async hover_async(callback: callable = None) → Task

Hovers the vehicle at the current Z

Parameters:: callback (callable) – callback to invoke on command completion or error
Returns:: An awaitable task wrapping the async coroutine
Return type:: asyncio.Task

is_api_control_enabled() → bool

Check if drone control using API calls is enabled

Returns:: True if ApiControl is enabled
Return type:: bool

async land_async(timeout_sec=3e+38, callback: callable = None) → Task

Land the vehicle

Parameters:

timeout_sec (int) – Timeout for the vehicle to land
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

log_topics(): Logs a human-readable list of all topics associated with the drone

async move_by_heading_async(heading: float, speed: float, v_down: float = 0.0, duration: float = 0.001, heading_margin: float = 0.08726646259971647, yaw_rate: float = 0, timeout_sec: float = 3e+38, callback: callable = None) → Task

Move by heading, horizontal speed, and vertical velocity

Parameters:

heading (float) – Heading in world coordinates (radians)
speed (float) – Desired speed in world (NED) X-Y plane (m/s)
v_down (float) – Desired velocity in world (NED) Z axis (m/s)
duration (float) – How long to fly at heading (seconds)
heading_margin (float) – How close to specified heading vehicle must be before starting flight duration countdown, in radians
yaw_rate (float) – Desired yaw rate to heading, <= 0 means as quickly as possible (radians/s)
timeout_sec (float) – Command timeout (seconds)
callback (callable) – Callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async move_by_velocity_async(v_north: float, v_east: float, v_down: float, duration: float = 0.001, yaw_control_mode: YawControlMode = 0, yaw_is_rate: bool = True, yaw: float = 0.0, callback: callable = None) → Task

Move by velocity. Control returns back to the caller immediately.

Parameters:

v_north (float) – desired velocity in world (NED) X axis (m/s)
v_east (float) – desired velocity in world (NED) Y axis (m/s)
v_down (float) – desired velocity in world (NED) Z axis (m/s)
duration (float) – Desired amount of time (seconds), to send this command for
yaw_control_mode (YawControlMode) – the yaw control mode for the command
yaw_is_rate (bool) – whether yaw is absolute or rate, optional
yaw (float) – yaw angle (rad) or rate (rad/s)
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async move_by_velocity_body_frame_async(v_forward: float, v_right: float, v_down: float, duration: float = 0.001, yaw_control_mode: YawControlMode = 0, yaw_is_rate: bool = True, yaw: float = 0.0, callback: callable = None) → Task

Move by velocity. Control returns back to the caller immediately.

Parameters:

v_forward (float) – desired velocity in drone forward (X) axis (m/s)
v_right (float) – desired velocity in drone right (Y) axis (m/s)
v_down (float) – desired velocity in drone Z axis (m/s)
duration (float) – Desired amount of time (seconds), to send this command for
yaw_control_mode (YawControlMode) – the yaw control mode for the command
yaw_is_rate (bool) – whether yaw is absolute or rate, optional
yaw (float) – yaw angle (rad) or rate (rad/s)
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async move_by_velocity_body_frame_z_async(v_forward: float, v_right: float, z: float, duration: float = 0.001, yaw_control_mode: YawControlMode = 0, yaw_is_rate: bool = True, yaw: float = 0.0, callback: callable = None) → Task

Move by velocity at a specific Z. Control returns back to the caller immediately.

Parameters:

v_forward (float) – desired velocity in drone forward (X) axis (m/s)
v_right (float) – desired velocity in drone right (Y) axis (m/s)
z (float) – desired z (m) [in NED]
duration (float) – Desired amount of time (seconds), to send this command for
yaw_control_mode (YawMode) – the yaw control mode for the command
yaw_is_rate (bool) – whether yaw is absolute or rate, optional
yaw (float) – yaw angle (rad) or rate (rad/s)
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async move_by_velocity_z_async(v_north: float, v_east: float, z: float, duration: float = 0.001, yaw_control_mode: YawControlMode = 0, yaw_is_rate: bool = True, yaw: float = 0.0, callback: callable = None) → Task

Move by velocity at a specific Z. Control returns back to the caller immediately.

Parameters:

v_north (float) – desired velocity in world (NED) X axis (m/s)
v_east (float) – desired velocity in world (NED) Y axis (m/s)
z (float) – desired z (m) [in NED]
duration (float) – Desired amount of time (seconds), to send this command for
yaw_control_mode (YawControlMode) – the yaw control mode for the command
yaw_is_rate (bool) – whether the yaw is absolute or a rate
yaw (float) – yaw angle (rad) or rate (rad/s)
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async move_on_geo_path_async(path, velocity: float, timeout_sec: float = 3e+38, yaw_control_mode=0, yaw_is_rate: bool = True, yaw: float = 0.0, lookahead=-1, adaptive_lookahead=1, callback: callable = None) → Task

Move on a path given in geo coordinates. Control returns back to the caller immediately.

Parameters:

{List[List[float]]} (path) – a list of path points, in lat-lon-alt coordinates
{float} (adaptive_lookahead) – the desired velocity, in m/s
{sec} (timeout_sec) – operation timeout
{YawControlMode} (yaw_control_mode) – the yaw control mode for the command
{bool} (yaW_is_rate) – whether the yaw is absolute or a rate
{float} – the desired yaw, in radians, or yaw rate, in radians/second
{float} – the amount of lookahead for the command
{float} – the amount of adaptive lookahead for the command
{callable} (callback) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

{asyncio.Task}

async move_on_path_async(path, velocity: float, timeout_sec: float = 3e+38, yaw_control_mode=0, yaw_is_rate: bool = True, yaw: float = 0.0, lookahead=-1, adaptive_lookahead=1, callback: callable = None) → Task

Move on a path. Control returns back to the caller immediately.

This API uses a carrot following algorithm with lookahead values to control the velocity toward the waypoints ahead. The default values (lookahead=-1, adaptive_lookahead=1) mean that the algorithm will automatically determine the appropriate lookahead.

Parameters:

path (List[List[float]]) – a list of path points, in NED coordinates
velocity (float) – the desired velocity, in m/s
timeout_sec (sec) – operation timeout
yaw_control_mode (YawControlMode) – the yaw control mode for the command
yaW_is_rate (bool) – whether the yaw is absolute or a rate
yaw (float) – the desired yaw, in radians, or yaw rate, in radians/second
lookahead (float) – the amount of lookahead for the command
adaptive_lookahead (float) – the amount of adaptive lookahead for the command
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async move_to_geo_position_async(latitude: float, longitude: float, altitude: float, velocity: float, timeout_sec: float = 3e+38, yaw_control_mode: YawControlMode = 0, yaw_is_rate: bool = True, yaw: float = 0.0, lookahead: float = -1.0, adaptive_lookahead: float = 1.0, callback: callable = None) → Task

Move to position given in lat-lon-alt coordinates. Control returns back to the caller immediately.

Parameters:

{float} (adaptive_lookahead) – the desired position latitude
{float} – the desired position longitude
{float} – the desired altitude (m)
{float} – the desired velocity (m/s)
{float} – timeout for the command
{YawControlMode} (yaw_control_mode) – yaw control mode
{bool} (yaw_is_rate) – whether the yaw is absolute or a rate
{float} – the desired yaw, in radians, or yaw rate, in radians/second
{float} – the amount of lookahead for the command
{float} – the amount of adaptive lookahead for the command
{callable} (callback) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

{asyncio.Task}

async move_to_position_async(north: float, east: float, down: float, velocity: float, timeout_sec: float = 3e+38, yaw_control_mode: YawControlMode = 0, yaw_is_rate: bool = True, yaw: float = 0.0, lookahead: float = -1.0, adaptive_lookahead: float = 1.0, callback: callable = None) → Task

Move to position. Control returns back to the caller immediately.

Parameters:

north (float) – the desired position north-coordinate (m)
east (float) – the desired position east-coordinate (m)
down (float) – the desired position down-coordinate (m)
velocity (float) – the desired velocity (m/s)
timeout_sec (float) – timeout for the command
yaw_control_mode (YawControlMode) – yaw control mode
yaw_is_rate (bool) – whether the yaw is absolute or a rate
yaw (float) – the desired yaw, in radians, or yaw rate, in radians/second
lookahead (float) – the amount of lookahead for the command
adaptive_lookahead (float) – the amount of adaptive lookahead for the command
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async request_control_async(callback: callable = None) → Task

Request the drone exit automatic mode and enable manual mode

Parameters:: callback (callable) – callback to invoke on command completion or error
Returns:: An awaitable task wrapping the async coroutine
Return type:: asyncio.Task

reset_camera_pose(camera_id: str, wait_for_pose_update: bool = True) → bool

Reset camera pose on drone to config setting

Parameters:

camera_id (str) – the id of the camera to reset
wait_for_pose_update (bool) – if true, the request will not return until the camera renderer has finished moving to the new pose

Returns:

True if camera pose is reset successfully

Return type:

bool

async rotate_by_yaw_rate_async(yaw_rate: float, duration: float, callback: callable = None) → Task

Rotate by yaw rate. Control returns back to the caller immediately.

Parameters:

yaw_rate (float) – the desired yaw rate, in radians per second
duration (float) – the duration for which to perform the command, in seconds
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async rotate_to_yaw_async(yaw: float, timeout_sec: float = 3e+38, margin: float = 0.08726646259971647, yaw_rate: float = 0.0, callback: callable = None) → Task

Rotate to a yaw. Control returns back to the caller immediately.

Parameters:

yaw (float) – the desired yaw (radians)
timeout_sec (float) – the operation timeout (seconds)
margin (float) – the acceptable margin of error (radians)
yaw_rate (float) – Desired yaw rate to heading, <= 0 means as quickly as possible (radians/s)
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

set_battery_drain_rate(desired_drain_rate: float) → bool

Set Desired battery drain rate

Parameters:: desired_drain_rate (float) – the desired battery drain rate, in the same units as the configuration value
Returns:: whether the value was set
Return type:: bool

set_battery_health_status(is_desired_state_healthy: bool) → bool

Set battery health status (true = healthy, false = unhealthy)

Parameters:: is_desired_state_healthy (bool) – true for healthy, false for unhealthy
Returns:: whether the value was set
Return type:: bool

set_battery_remaining(desired_battery_remaining: float) → bool

Set Desired battery remaining battery charge level

Parameters:: desired_battery_remaining (float) – the remaining battery, as a percent from 0.0-100.0
Returns:: whether the operation was successful
Return type:: bool

set_camera_pose(camera_id: str, pose: Transform, wait_for_pose_update: bool = True) → bool

Sets the relative pose of a drone camera

Parameters:

camera_id (str) – the name of the camera
pose (Pose) – the desired camera relative pose
wait_for_pose_update (bool) – if true, the request will not return until the camera renderer has finished moving to the new pose

Returns:

true if pose successfully set

Return type:

bool

set_chromatic_aberration_intensity(camera_id: str, image_type_id: int, intensity: float) → bool

Sets the chromatic aberration intensity to simulate camera faults

Parameters:

camera_id (str) – the name of the camera
image_type_id (int) – the ImageType for which to set the focal length
intensity (float) – desired intensity range 0 to 1

Returns:

true if focal length successfully set

Return type:

bool

set_control_signals(control_signal_map: Dict) → bool

set_control_signals for Manual Controller type

Parameters:: control_signal_map (Dict) – Dictionary with keys = actuator ID strings, and values = control signal floats
Returns:: True if all control outputs are set successfully
Return type:: bool

set_depth_of_field_focal_region(camera_id: str, image_type_id: int, max_focal_distance: float) → bool

Sets the focal region, beyond this distance, images are blurry.

Parameters:

camera_id (str) – the name of the camera
image_type_id (int) – the ImageType for which to set the focal length
focal_length (float) – the desired focal region area, in meters

Returns:

true if focal length successfully set

Return type:

bool

set_depth_of_field_transition_threshold(camera_id: str, image_type_id: int, transition_threshold: float) → bool

Sets the transition area around the focal region, where the image is still not entirely blurry

Parameters:

camera_id (str) – the name of the camera
image_type_id (int) – the ImageType for which to set the focal length
transition_threshold (float) – the threshold around the focal region where images still clear in meters.

Returns:

true if focal length successfully set

Return type:

bool

set_external_force(ext_force: List[float]) → bool

Set arbitrary external force on drone, which can be used to model forces arising from the environment.

Parameters:: ext_force (List[float]) – the force [x, y, z] in World frame (NED), in Newtons
Returns:: True if external force is set successfully
Return type:: bool

set_field_of_view(camera_id: str, image_type_id: int, field_of_view: float) → bool

Sets the field of view of a drone camera

Parameters:

camera_id (str) – the name of the camera
image_type_id (int) – the ImageType for which to set the fov
field_of_view (float) – the desired camera fov, in degrees

Returns:

true if fov successfully set

Return type:

bool

set_focal_length(camera_id: str, image_type_id: int, focal_length: float) → bool

Sets the focal length of a drone camera, affecting the image ‘zoom’

Parameters:

camera_id (str) – the name of the camera
image_type_id (int) – the ImageType for which to set the focal length
focal_length (float) – the desired focal length, in mm

Returns:

true if focal length successfully set

Return type:

bool

set_geo_pose(latitude: float, longitude: float, altitude: float, rotation: Quaternion, reset_kinematics=True) → bool

Sets the pose of a Drone using latitude, longitude, and altitude

Parameters:

{float} (altitude) – the desired latitude
{float} – the desired longitude
{float} – the desired altitude, in meters
{bool} (reset_kinematics) – if true, the object’s velocity etc will be reset

Returns:

{bool} true if pose successfully set

set_ground_truth_kinematics(kinematics: Dict) → bool

Set ground truth kinematics

Parameters:: kinematics (Dict) – the kinematics as a dict
Returns:: whether the kinematics were successfully set
Return type:: bool

async set_mission_mode_async(callback: callable = None) → Task

Set drone to execute previously loaded mission profile

Parameters:: callback (callable) – callback to invoke on command completion or error
Returns:: An awaitable task wrapping the async coroutine
Return type:: asyncio.Task

set_pose(pose: Transform, reset_kinematics=True) → bool

Sets Pose for NonPhysics Drone

Parameters:

pose (Pose) – the desired pose
reset_kinematics (bool) – if true, the object’s velocity etc will be reset

Returns:

whether the operation was successful

Return type:

bool

set_robot_info_topics(): Sets up robot info topics for the Drone. Called automatically

set_sensor_topics(world: World)

Sets up sensor topics for the drone. Called automatically.

Parameters:: world (World) – the associated ProjectAirSim World object

set_topics(world: World)

Sets up all topics for the Drone. Called automatically.

Parameters:: world (World) – the associated ProjectAirSim World object

async set_vtol_mode_async(vtol_mode: VTOLMode, callback: callable = None) → Task

Set drone flight mode on VTOL-quad-tailsitter vehicles

Parameters:

vtol_mode (VTOLMode) – VTOLMode class value specifying the flight mode
callback (callback) – Callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

async takeoff_async(timeout_sec=20, callback: callable = None) → Task

Takeoff vehicle to 3m above ground. Vehicle should not be moving when this API is used

Parameters:

timeout_sec (int) – Timeout for the vehicle to reach desired altitude
callback (callable) – callback to invoke on command completion or error

Returns:

An awaitable task wrapping the async coroutine

Return type:

asyncio.Task

update_actuator_fault_state(actuator_id, fault_configured: bool) → bool

update actuator fault state. Helpful for fault testing

Parameters:

actuator_id – actuator id of the targeted actuator
fault_configured – desired state of the fault simulation on actuator

Returns:

True if actuated fault state updated successfully

Return type:

bool

Types 

class projectairsim.types.AttrDict: Base attribute dictionary type to set other types to use Dict as the underlying data type.

class projectairsim.types.BoxAlignment(*values): Bounding box alignment enum values: WORLD_AXIS, OBJECT_ORIENTED

class projectairsim.types.Color(rgb: List)

Class to represent a single RGB color value

Parameters:: rgb (List) – List of initial color values in RGB order as [r, g, b]

class projectairsim.types.FrameType(*values): Message frame type enum values: SUBSCRIBE, UNSUBSCRIBE, MESSAGE, UNSUBSCRIBEALL

class projectairsim.types.ImageType(*values): Image type enum values: SCENE, DEPTH_PLANAR, DEPTH_PERSPECTIVE, SEGMENTATION, DEPTH_VIS, DISPARITY_NORMALIZED, SURFACE_NORMALS

class projectairsim.types.LandedState(*values)

projectairsim.types.Pose: alias of Transform

class projectairsim.types.ProjectAirSimTopic(path: str, topic_type: str, message_type: str, frequency: int)

Pub-sub topic info data.

Parameters:

path (str) – topic path
topic_type (str) – ‘published’ or ‘subscribed’ by the sim server
message_type (str) – message type
frequency (int) – topic frequency in Hz

class projectairsim.types.Quaternion(quat: Dict)

Class to represent a 4-element quaternion as a dict with the following form:: { “w”: 1.0, “x”: 0.0, “y”: 0.0, “z”: 0.0 }

Parameters:: quat (Dict) – Initial dict to construct from.

class projectairsim.types.SerializationType(*values): Message serialization type enum values: MSGPACK_JSON, PURE_JSON

class projectairsim.types.Transform(transform: Dict)

Class to represent a Transform as a dict with the following form:: { “frame_id”: “DEFAULT_FRAME”, “translation”: Vector3 dict, “rotation”: Quaternion dict }

Parameters:: transform (Dict) – Initial dict to construct from.

class projectairsim.types.Vector3(vec: Dict)

Class to represent a 3-element vector as a dict with the following form:: { “x”: 0.0, “y”: 0.0, “z”: 0.0 }

Parameters:: vec (Dict) – Initial dict to construct from.

class projectairsim.types.WeatherParameter(*values): Weather parameter enum values: ENABLED, RAIN, ROAD_WETNESS, SNOW, ROAD_SNOW, MAPLE_LEAF, ROAD_LEAF, DUST, FOG

Utils 

projectairsim.utils.calculate_path_length(path_points)

Calculates the length of a path

Parameters:: path_points (list) – the 3d coordinate values of the path
Returns:: the total length of the path
Return type:: float

projectairsim.utils.calculate_path_time(path_points, speeds)

Calculates the time it will take to traverse a path

Parameters:

path_points (list) – the 3d coordinate values of the path
speeds (list) – the speeds of travel on each leg of the path

Returns:

the total time taken

Return type:

float

projectairsim.utils.convert_string_with_spaces_to_float_list(data: str) → List[float]: Helper function to convert a string input of numbers separated by spaces to a List of floats. Useful for reading in config parameters.

projectairsim.utils.decode(data)

Recursively decode data based on type

Parameters:: data – the data to decode
Returns:: The decoded data

projectairsim.utils.decode_bytes(data: bytes): Helper function for the general decode to decode bytes

projectairsim.utils.decode_dict(data: Dict): Helper function for the general decode to decode Dicts

projectairsim.utils.decode_list(data: list) → List: Helper function for the general decode to decode Lists

projectairsim.utils.generate_perpendicular_unit_vector(direction_vector)

Generates an arbitrary unit vector perpendicular to a given 3d vector

Parameters:: vector (List) – the vector to be perpendicular to
Returns:: the generated vector
Return type:: List

projectairsim.utils.geo_to_ned_coordinates(home_geo_point: Dict, lat_lon_alt_coord: List)

Helper function to convert lat-lon-alt to scene coordinates

Parameters:

home_geo_point (Dict) – the geo point that corresponds to 0,0,0 in NED. Keys should be “latitude”, “longitude”, and “altitude”
lat_lon_alt_coord (List) – a list of [latitude, longitude, altitude]

Returns:

a list of coordinates [n,e,d]

Return type:

(List)

projectairsim.utils.get_heading_between_traj_points(point1, point2)

Computes the heading/yaw angle between two points in NED coordinates (x, y, z)

Parameters:

point1 – the two points
point2 – the two points

Returns:

the yaw angle between the points, in radians

Return type:

float

projectairsim.utils.get_ned_trajectory_from_csv(filename: str, delimiter_str: str = ',', n_lines_to_skip: int = 1) → None

Retrieves a NED trajectory from a CSV file

First row of the file is the header. Numerical data begins from n_lines_to_skip + 1. Each row corresponds to trajectory data at a given time instance, where the column order is 1) time (s) 2) pose_x (m) 3) pose_y (m) 4) pose_z (m) 5) pose_roll (rad) 6) pose_pitch (rad) 7) pose_yaw (rad) 8) vel_lin_x (m/s) 9) vel_lin_y (m/s) 10) vel_lin_z (m/s)

Parameters:

filename (str) – the filename
delimiter_str (str) – the delimiter separating the data
n_lines_to_skip (int) – the number of lines at the top of the file to ignore

projectairsim.utils.get_pitch_between_traj_points(point1, point2)

Computes the pitch angle between two points in NED coordinates (x, y, z)

Parameters:

point1 – the two points
point2 – the two points

Returns:

the pitch angle between the points, in radians

Return type:

float

projectairsim.utils.get_point_distance_along_path(path: List[List[float]], desired_distance: float)

Given a path and a distance, returns the point at that distance along the path

Parameters:

path (list[list[float]]) – the path coordinates
desired_distance (float) – the distance along the path to find the point

Returns:

the point on the path that is the given distance from the start

Return type:

list

projectairsim.utils.get_point_to_line_segment_distance(point, line_start, line_end)

Computes the minimum distance between a 3d point and the line segment defined by two points

Parameters:

point (List) – the point
line_start (List) – the start and end points of the line segment
line_end (List) – the start and end points of the line segment

Returns:

the distance

Return type:

float

projectairsim.utils.get_schema(file_name) → Dict

Loads a json schema from disk and returns it as a Dict

Parameters:: file_name (str) – the name of the file to load

projectairsim.utils.get_trajectory_from_kml(filename: str) → List[tuple]

Reads in a kml file and exports a list of (lat, lon, alt) coordinates

Parameters:: filename (str) – the name of the kml file
Returns:: a list of tuples (lat, lon, alt)
Return type:: List[tuple]

projectairsim.utils.get_voxel_grid_idx(coordinate: list, grid_center: list, edge_lens: tuple, res: float)

For a given coordinate in NED, returns the index of the corresponding voxel in the occupancy map

Parameters:

coordinate (list) – (x, y, z) in NEU
grid_center (list) – the center point of the grid
edge_lens (tuple) – the edge lengths of the grid
res (list) – the resolution of the grid

Returns:

index of the corresponding voxel in the occupancy map

Return type:

int

projectairsim.utils.load_scene_config_as_dict(config_name: str, sim_config_path: str = 'sim_config/', sim_instance_idx: int = -1) → Tuple[Dict, List]

Loads the scene configuration

(Re)loads any specified scene config and returns the complete sim and robot config as a Dict as well as the file paths as a tuple of the scene config, a list of robot configs, and a list of environment actor configs

Parameters:

config_name (str) – the filename of the config
sim_config_path (str) – the folder in which to look for the config
sim_instance_idx (int) – the index of the scene instance (for distributed sim only)

Returns:

a tuple containing the dict and the file paths of all loaded configuration files

Return type:

Tuple[Dict, List]

projectairsim.utils.merge_dicts(d1, d2): Recursively merges dict d2 into dict d1

projectairsim.utils.merge_lists(l1, l2): Merges two lists of dictionaries, matching elements by the ‘name’ key if present

projectairsim.utils.norm_rad(angle)

Helper function to normalize angles for comparison

Parameters:: angle (float) – the angle, in radians
Returns:: the angle, normalized to between 0 and 2pi
Return type:: float

projectairsim.utils.point_distance(start, end)

Helper method for calculating distance

Parameters:

start (list) – the quaternion values
end (list) – the quaternion values

Returns:

the euclidean distance between two points

Return type:

float

projectairsim.utils.projectairsim_log(): Returns the Project AirSim logger. Use the logger’s methods to log information.

projectairsim.utils.quaternion_to_rpy(w, x, y, z)

Helper method for converting quaternion to/from roll/pitch/yaw

https:#en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles This conversion returns the Euler angles based on the order of body-fixed frame ZYX (yaw, pitch, then roll), which is equivalent to world-fixed frame XYZ (roll, pitch, then yaw).

Parameters:

w (float) – the quaternion values
x (float) – the quaternion values
y (float) – the quaternion values
z (float) – the quaternion values

Returns:

a (roll, pitch, yaw) tuple, in radians

Return type:

tuple

projectairsim.utils.rotate_vector_about_axis(vector, axis, angle)

Rotates a vector about an axis

Parameters:

vector (List) – the vector to be rotated
axis (List) – the axis to rotate about
angle (float) – the rotation angle, in radians

Returns:

the rotated vector

Return type:

List

projectairsim.utils.rpy_to_quaternion(roll, pitch, yaw)

Helper method for converting quaternion to/from roll/pitch/yaw

https:#en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles The Euler angles given should be based on the order of body-fixed frame ZYX (yaw, pitch, then roll), which is equivalent to world-fixed frame XYZ (roll, pitch, then yaw). Pitch must be within -89.9 to +89.9 degrees due to gimbal lock restrictions.

Parameters:

roll (float) – the rpy, in radians
pitch (float) – the rpy, in radians
yaw (float) – the rpy, in radians

Returns:

a (w,x,y,z) tuple, representing a Quaternion

Return type:

tuple

projectairsim.utils.unpack_image(image)

Takes a Project AirSim image message and converts it into a format usable by openCV

Parameters:: image – the image message
Returns:: The image in openCV decoded form

projectairsim.utils.validate_json(json_data, file_name) → None

Validates a JSON according to a given schema

Parameters:

json_data (object) – the json to validate
file_name (str) – the name of the schema file

projectairsim.utils.validate_trajectory(params) → None

Internal function for validating an imported trajectory

Parameters:: params (List) – a list of trajectory parameters

projectairsim.utils.validate_trajectory_json(env_actor_script: <module 'commentjson' from '/opt/hostedtoolcache/Python/3.12.10/x64/lib/python3.12/site-packages/commentjson/__init__.py'>) → None

Validates a json trajectory

Parameters:: env_actor_script (commentjson) – the json to validate

Client Documentation

Client

World

Drone

Types

Utils

Indices and tables

Client Documentation 

Client 

World 

Drone 

Types 

Utils 

Indices and tables 