API Overview

API Notes

  1. Stability: APIs are evolving at this stage and could change based on the feedback. So please do provide feedback.

  2. AirSim Compatibility: It is NOT a goal to maintain strict backward compatibility with GitHub AirSim project APIs. Wherever appropriate, learnings from AirSim project are used to update the APIs in this version. At the same time, a lot of familiar concepts have been carried over to enable smooth transition for users who are familiar with GitHub AirSim.

API Concepts

  1. Entities: The user code interacts with the simulation backend via these 3 objects:

    • Client: provides APIs for connection management between user code (a.k.a. simulation client) and simulation backend.

    • World: provides APIs for simulation environment management (loading of scene, clock management, weather management, etc.)

    • Robot specific entities, e.g. Drone: provides APIs for robot control as well as sensor data.

  2. Controls and Sensor data channels: The user code will typically send the control commands to the simulation backend using request-response model while it would subscribe to sensor data via the publish-subscribe model.

  3. Async APIs: APIs that end with *Async return the control back to the user code immediately after invoking the call. It is expected that the users will use language specific async models to interact with these APIs, e.g., for Python clients, the user code would use asyncio package to interact with the *Async APIs.

  4. Units: Unless specified otherwise, the API inputs and outputs are assumed to be in SI units (meters and radians) and in NED convention.

Client Authorization

The Project AirSim server may optionally enable client authorization verification (to enable this, see the “-clientauthpubkey” command line option). When client authorization verification is enabled, clients must present a valid client authorization token immediately after connecting and before calling other API methods (include creating a World object). If a valid unexpired token is not set or the token expires, API calls return a “client not authorized” error and the client won’t received updates to subscribed topics.

To present a client authorization token, call the set_authorization_token() method. This method returns a datetime object for when the authorization expires (or expired.) The client must present a new token before the current token expires to continue using the client API.

API Example

Python

(please see hello_drone.py for complete code)

    import asyncio
    # Import ProjectAirSim client libraries
    from projectairsim import ProjectAirSimClient, World, Drone

    async def main():
        # Create client object
        client = ProjectAirSimClient()
        client.connect()

        # Create world object and load the scene from its config
        world = World(client, "scene_basic_drone.jsonc", delay_after_load_sec=2)

        # Create drone object
        drone = Drone(client, world, "Drone1")

        # Control drone
        move_up = await drone.move_by_velocity_async(
            v_north=0.0, v_east=0.0, v_down=-1.0, duration=4.0
        )
        await move_up

        client.disconnect()

    if __name__ == "__main__":
        asyncio.run(main())

Client

Client Object

Connection API

Authorization API

Low Level Communication API

World

World Object

Scene Control API

Scene Object API

For Unreal objects, the object_name refers to the object ID which can be found in the Outliner panel in the Unreal Editor. You can toggle visibility of ID Name by right clicking the the Item Label header and selecting it.

Sim Clock API

Weather Visual Effects

Mapping API

The index in the occupancy array for a particular point (needs to be within the bounds determined through the params) in the scene can be calculated as follows:

Center Coords: x_c, y_c, z_c // in m
Desired Point: x, y, z // in m

array-index = x_idx + x_cells * (z_idx + z_cells * y_idx)

Here,
x_cells = x_size/resolution (similar for y_cells)
z_cells = z_size/(resolution * n_z_resolution)
x_idx = x + x_cells/2 - x_c (similar for y_idx and z_idx)

Value of the the array at this index (True or False) determines the occupancy of that cell.

New Feature: Voxel Grid Segmentation (use_segmentation=True)

When use_segmentation is set to True, the voxel grid will store the segmentation ID of objects, rather than a simple binary representation (1 or 0). In this case, the voxel grid array will contain the segmentation ID for each voxel, which corresponds to the object occupying that space.

Key Behavior:

  • Multiple Objects in a Voxel: If more than one object occupies the same voxel grid volume, the object with the largest segmentation ID will be stored in that voxel.

  • Segmentation ID 0: If any object has a segmentation ID of 0, it could be mistaken for an unoccupied space (since the default is often 0 for empty voxels). To resolve this ambiguity, see next section.

Solutions for Segmentation ID 0:

  1. Cross-reference with a Non-Segmented Grid: To accurately interpret voxel data when use_segmentation=True, consider performing an additional check using a voxel grid generated with use_segmentation=False. This will help you differentiate between empty space and an object with ID 0.

  2. Avoid Using Segmentation ID 0: A simpler solution is to avoid setting segmentation ID 0 for objects you want to include in the segmentation. By assigning a non-zero segmentation ID to these objects, you prevent any confusion with unoccupied space.

Visual Debugging Tools

Parameter

Description

color_rgba

List of red, green, blue, alpha values in that specific order (each normalized to 1.0)

duration

(seconds)

is_persistent

If True, ‘duration’ is ignored and markers are displayed until removed by flush_persistent_markers()

names/strings

List of strings

points/points_start/points_end/positions

List of list of floats, list of floats refers to [x, y, z]

poses

List of Pose objects, each pose has a translation and rotation component

scale

Scaling factor for text or transform

size

Scale of the point or arrow

thickness

Thickness of line or transform

Refer to the example user script “hello_debug_utils.py” for more details on how to use this visual debugging API.

Drone

Drone Object

Control API

Prerequisites

Control commands

Manual Controller commands

  • set_control_signals(control_signal_map: Dict) - Manually set the control signal outputs. The parameter control_signal_map dictionary has keys as the target actuator ID string (e.g. "Prop_FR_actuator") and values as the control signal output float value (e.g. 0.3). Multiple control signals can be set in a single call and the values will remain as set until the next call to set them again.

State API

position = Vector3({"x": 0, "y": 0, "z": 0})
orientation = Quaternion({"w": 0, "x": 0, "y": 0, "z": 0})
linear_twist = Vector3({"x": 0, "y": 0, "z": 0})
angular_twist = Vector3({"x": 0, "y": 0, "z": 0})
linear_accn = Vector3({"x": 0, "y": 0, "z": 0})
angular_accn = Vector3({"x": 0, "y": 0, "z": 0})

accn = {"angular": angular_accn, "linear": linear_accn}
pose = {"orientation": orientation, "position": position}
twist = {"angular": angular_twist, "linear": linear_twist}

kinematic = {"time_stamp": 0, "pose": pose, "twist": twist, "accels": accn}

drone.set_ground_truth_kinematics(kinematic)

Note: linear_twist["z"] needs to have a -ve value (upwards direction) for the drone to move with the specified kinematics

Sensors API

Camera API

IMU API

GPS API

Barometer API

Magnetometer API

Airspeed API

Battery API

Copyright (C) Microsoft Corporation. All rights reserved.