From feba1423a555de6475a08fad0577d0f69060ee0c Mon Sep 17 00:00:00 2001 From: Rajat Singhal Date: Sun, 12 Apr 2020 16:11:45 +0530 Subject: [PATCH 1/3] [Pythonclient] Add missing docstrings --- PythonClient/airsim/client.py | 723 +++++++++++++++++++++++++++------- 1 file changed, 587 insertions(+), 136 deletions(-) diff --git a/PythonClient/airsim/client.py b/PythonClient/airsim/client.py index 94b8cd63ed..b4f5d5136b 100644 --- a/PythonClient/airsim/client.py +++ b/PythonClient/airsim/client.py @@ -15,12 +15,23 @@ def __init__(self, ip = "", port = 41451, timeout_value = 3600): if (ip == ""): ip = "127.0.0.1" self.client = msgpackrpc.Client(msgpackrpc.Address(ip, port), timeout = timeout_value, pack_encoding = 'utf-8', unpack_encoding = 'utf-8') - + # ----------------------------------- Common vehicle APIs --------------------------------------------- def reset(self): + """ + Reset the vehicle to its original starting state + + Note that you must call `enableApiControl` and `armDisarm` again after the call to reset + """ self.client.call('reset') def ping(self): + """ + If connection is established then this call will return true otherwise it will be blocked until timeout + + Returns: + bool: + """ return self.client.call('ping') def getClientVersion(self): @@ -37,27 +48,85 @@ def getMinRequiredClientVersion(self): # basic flight control def enableApiControl(self, is_enabled, vehicle_name = ''): + """ + Enables or disables API control for vehicle corresponding to vehicle_name + + Args: + is_enabled (bool): True to enable, False to disable API control + vehicle_name (str, optional): Name of the vehicle to send this command to + """ return self.client.call('enableApiControl', is_enabled, vehicle_name) def isApiControlEnabled(self, vehicle_name = ''): + """ + Returns true if API control is established. + + If false (which is default) then API calls would be ignored. After a successful call to `enableApiControl`, `isApiControlEnabled` should return true. + + Args: + vehicle_name (str, optional): Name of the vehicle + + Returns: + bool: If API control is enabled + """ return self.client.call('isApiControlEnabled', vehicle_name) def armDisarm(self, arm, vehicle_name = ''): + """ + Arms or disarms vehicle + + Args: + arm (bool): True to arm, False to disarm the vehicle + vehicle_name (str, optional): Name of the vehicle to send this command to + + Returns: + bool: Success + """ return self.client.call('armDisarm', arm, vehicle_name) - + def simPause(self, is_paused): + """ + Pauses simulation + + Args: + is_paused (bool): True to pause the simulation, False to release + """ self.client.call('simPause', is_paused) def simIsPause(self): + """ + Returns true if the simulation is paused + + Returns: + bool: If the simulation is paused + """ return self.client.call("simIsPaused") def simContinueForTime(self, seconds): + """ + Continue the simulation for the specified number of seconds + + Args: + seconds (float): Time to run the simulation for + """ self.client.call('simContinueForTime', seconds) def getHomeGeoPoint(self, vehicle_name = ''): + """ + Get the Home location of the vehicle + + Args: + vehicle_name (str, optional): Name of vehicle to get home location of + + Returns: + GeoPoint: Home location of the vehicle + """ return GeoPoint.from_msgpack(self.client.call('getHomeGeoPoint', vehicle_name)) def confirmConnection(self): + """ + Checks state of connection every 1 sec and reports it in Console so user can see the progress for connection. + """ if self.ping(): print("Connected!") else: @@ -66,7 +135,7 @@ def confirmConnection(self): client_ver = self.getClientVersion() server_min_ver = self.getMinRequiredServerVersion() client_min_ver = self.getMinRequiredClientVersion() - + ver_info = "Client Ver:" + str(client_ver) + " (Min Req: " + str(client_min_ver) + \ "), Server Ver:" + str(server_ver) + " (Min Req: " + str(server_min_ver) + ")" @@ -81,23 +150,83 @@ def confirmConnection(self): print('') def simSwapTextures(self, tags, tex_id = 0, component_id = 0, material_id = 0): + """ + Runtime Swap Texture API + + See https://microsoft.github.io/AirSim/retexturing/ for details + + Args: + tags (str): string of "," or ", " delimited tags to identify on which actors to perform the swap + tex_id (int, optional): indexes the array of textures assigned to each actor undergoing a swap + + If out-of-bounds for some object's texture set, it will be taken modulo the number of textures that were available + component_id (int, optional): + material_id (int, optional): + + Returns: + list[str]: List of objects which matched the provided tags and had the texture swap perfomed + """ return self.client.call("simSwapTextures", tags, tex_id, component_id, material_id) # time-of-day control def simSetTimeOfDay(self, is_enabled, start_datetime = "", is_start_datetime_dst = False, celestial_clock_speed = 1, update_interval_secs = 60, move_sun = True): + """ + Control the position of Sun in the environment + + Sun's position is computed using the coordinates specified in `OriginGeopoint` in settings for the date-time specified in the argument, + else if the string is empty, current date & time is used + + Args: + is_enabled (bool): True to enable time-of-day effect, False to reset the position to original + start_datetime (str, optional): Date & Time in %Y-%m-%d %H:%M:%S format, e.g. `2018-02-12 15:20:00` + is_start_datetime_dst (bool, optional): True to adjust for Daylight Savings Time + celestial_clock_speed (float, optional): Run celestial clock faster or slower than simulation clock + E.g. Value 100 means for every 1 second of simulation clock, Sun's position is advanced by 100 seconds + so Sun will move in sky much faster + update_interval_secs (float, optional): Interval to update the Sun's position + move_sun (bool, optional): Whether or not to move the Sun + """ return self.client.call('simSetTimeOfDay', is_enabled, start_datetime, is_start_datetime_dst, celestial_clock_speed, update_interval_secs, move_sun) # weather def simEnableWeather(self, enable): + """ + Enable Weather effects. Needs to be called before using `simSetWeatherParameter` API + + Args: + enable (bool): True to enable, False to disable + """ return self.client.call('simEnableWeather', enable) def simSetWeatherParameter(self, param, val): + """ + Enable various weather effects + + Args: + param (WeatherParameter): Weather effect to be enabled + val (float): Intensity of the effect, Range 0-1 + """ return self.client.call('simSetWeatherParameter', param, val) # camera control # simGetImage returns compressed png in array of bytes # image_type uses one of the ImageType members def simGetImage(self, camera_name, image_type, vehicle_name = ''): + """ + Get a single image + + Returns bytes of png format image which can be dumped into abinary file to create .png image + `string_to_uint8_array()` can be used to convert into Numpy unit8 array + See https://microsoft.github.io/AirSim/image_apis/ for details + + Args: + camera_name (str): Name of the camera, for backwards compatibility, ID numbers such as 0,1,etc. can also be used + image_type (ImageType): Type of image required + vehicle_name (str, optional): Name of the vehicle with the camera + + Returns: + Binary string literal of compressed png image + """ # todo: in future remove below, it's only for compatibility to pre v1.2 camera_name = str(camera_name) @@ -111,47 +240,180 @@ def simGetImage(self, camera_name, image_type, vehicle_name = ''): # simGetImage returns compressed png in array of bytes # image_type uses one of the ImageType members def simGetImages(self, requests, vehicle_name = ''): + """ + Get multiple images + + See https://microsoft.github.io/AirSim/image_apis/ for details and examples + + Args: + requests (list[ImageRequest]): Images required + vehicle_name (str, optional): Name of vehicle associated with the camera + + Returns: + list[ImageResponse]: + """ responses_raw = self.client.call('simGetImages', requests, vehicle_name) return [ImageResponse.from_msgpack(response_raw) for response_raw in responses_raw] # gets the static meshes in the unreal scene def simGetMeshPositionVertexBuffers(self): + """ + Returns the static meshes that make up the scene + + See https://microsoft.github.io/AirSim/meshes/ for details and how to use this + + Returns: + list[MeshPositionVertexBuffersResponse]: + """ responses_raw = self.client.call('simGetMeshPositionVertexBuffers') return [MeshPositionVertexBuffersResponse.from_msgpack(response_raw) for response_raw in responses_raw] def simGetCollisionInfo(self, vehicle_name = ''): + """ + Args: + vehicle_name (str, optional): Name of the Vehicle to get the info of + + Returns: + CollisionInfo: + """ return CollisionInfo.from_msgpack(self.client.call('simGetCollisionInfo', vehicle_name)) def simSetVehiclePose(self, pose, ignore_collison, vehicle_name = ''): + """ + Set the pose of the vehicle + + If you don't want to change position (or orientation) then just set components of position (or orientation) to floating point nan values + + Args: + pose (Pose): Desired Pose pf the vehicle + ignore_collision (bool): Whether to ignore any collision or not + vehicle_name (str, optional): Name of the vehicle to move + """ self.client.call('simSetVehiclePose', pose, ignore_collison, vehicle_name) def simGetVehiclePose(self, vehicle_name = ''): + """ + Args: + vehicle_name (str, optional): Name of the vehicle to get the Pose of + + Returns: + Pose: + """ pose = self.client.call('simGetVehiclePose', vehicle_name) return Pose.from_msgpack(pose) def simSetTraceLine(self, color_rgba, thickness=1.0, vehicle_name = ''): + """ + Modify the color and thickness of the line when Tracing is enabled + + Tracing can be enabled by pressing T in the Editor or setting `EnableTrace` to `True` in the Vehicle Settings + + Args: + color_rgba (list): desired RGBA values from 0.0 to 1.0 + thickness (float, optional): Thickness of the line + vehicle_name (string, optional): Name of the vehicle to set Trace line values for + """ self.client.call('simSetTraceLine', color_rgba, thickness, vehicle_name) def simGetObjectPose(self, object_name): + """ + Args: + object_name (str): Object to get the Pose of + + Returns: + Pose: + """ pose = self.client.call('simGetObjectPose', object_name) return Pose.from_msgpack(pose) def simSetObjectPose(self, object_name, pose, teleport = True): + """ + Set the pose of the object(actor) in the environment + + The specified actor must have Mobility set to movable, otherwise there will be undefined behaviour. + See https://www.unrealengine.com/en-US/blog/moving-physical-objects for details on how to set Mobility and the effect of Teleport parameter + + Args: + object_name (str): Name of the object(actor) to move + pose (Pose): Desired Pose of the object + teleport (bool, optional): Whether to move the object immediately without affecting their velocity + + Returns: + bool: If the move was successful + """ return self.client.call('simSetObjectPose', object_name, pose, teleport) def simListSceneObjects(self, name_regex = '.*'): + """ + Lists the objects present in the environment + + Default behaviour is to list all objects, regex can be used to return smaller list of matching objects or actors + + Args: + name_regex (str, optional): String to match actor names against, e.g. "Cylinder.*" + + Returns: + list[str]: List containing all the names + """ return self.client.call('simListSceneObjects', name_regex) def simSetSegmentationObjectID(self, mesh_name, object_id, is_name_regex = False): + """ + Set segmentation ID for specific objects + + See https://microsoft.github.io/AirSim/image_apis/#segmentation for details + + Args: + mesh_name (str): Name of the mesh to set the ID of (supports regex) + object_id (int): Object ID to be set, range 0-255 + + RBG values for IDs can be seen at https://microsoft.github.io/AirSim/seg_rgbs.txt + is_name_regex (bool, optional): Whether the mesh name is a regex + + Returns: + bool: If the mesh was found + """ return self.client.call('simSetSegmentationObjectID', mesh_name, object_id, is_name_regex) def simGetSegmentationObjectID(self, mesh_name): + """ + Returns Object ID for the given mesh name + + Mapping of Object IDs to RGB values can be seen at https://microsoft.github.io/AirSim/seg_rgbs.txt + + Args: + mesh_name (str): Name of the mesh to get the ID of + """ return self.client.call('simGetSegmentationObjectID', mesh_name) def simPrintLogMessage(self, message, message_param = "", severity = 0): + """ + Prints the specified message in the simulator's window. + + If message_param is supplied, then it's printed next to the message and in that case if this API is called with same message value + but different message_param again then previous line is overwritten with new line (instead of API creating new line on display). + + For example, `simPrintLogMessage("Iteration: ", to_string(i))` keeps updating same line on display when API is called with different values of i. + The valid values of severity parameter is 0 to 3 inclusive that corresponds to different colors. + + Args: + message (str): Message to be printed + message_param (str, optional): Parameter to be printed next to the message + severity (int, optional): Range 0-3, inclusive, corresponding to the severity of the message + """ return self.client.call('simPrintLogMessage', message, message_param, severity) def simGetCameraInfo(self, camera_name, vehicle_name = ''): + """ + Get details about the camera + + Args: + camera_name (str): Name of the camera, for backwards compatibility, ID numbers such as 0,1,etc. can also be used + vehicle_name (str, optional): Vehicle which the camera is associated with + + Returns: + CameraInfo: + """ # TODO: below str() conversion is only needed for legacy reason and should be removed in future return CameraInfo.from_msgpack(self.client.call('simGetCameraInfo', str(camera_name), vehicle_name)) @@ -161,12 +423,12 @@ def simSetCameraOrientation(self, camera_name, orientation, vehicle_name = ''): Args: camera_name (str): Name of the camera to be controlled - orientation (airsim.Quaternion()): Quaternion representing the desired orientation of the camera + orientation (Quaternionr): Quaternion representing the desired orientation of the camera vehicle_name (str, optional): Name of vehicle which the camera corresponds to """ # TODO: below str() conversion is only needed for legacy reason and should be removed in future self.client.call('simSetCameraOrientation', str(camera_name), orientation, vehicle_name) - + def simSetCameraFov(self, camera_name, fov_degrees, vehicle_name = ''): """ - Control the field of view of a selected camera @@ -180,50 +442,126 @@ def simSetCameraFov(self, camera_name, fov_degrees, vehicle_name = ''): return self.client.call('simSetCameraFov', str(camera_name), fov_degrees, vehicle_name) def simGetGroundTruthKinematics(self, vehicle_name = ''): + """ + Get Ground truth kinematics of the vehicle + + Args: + vehicle_name (str, optional): Name of the vehicle + + Returns: + KinematicsState: Ground truth of the vehicle + """ kinematics_state = self.client.call('simGetGroundTruthKinematics', vehicle_name) return KinematicsState.from_msgpack(kinematics_state) simGetGroundTruthKinematics.__annotations__ = {'return': KinematicsState} def simGetGroundTruthEnvironment(self, vehicle_name = ''): + """ + Get ground truth environment state + + Args: + vehicle_name (str, optional): Name of the vehicle + + Returns: + EnvironmentState: Ground truth environment state + """ env_state = self.client.call('simGetGroundTruthEnvironment', vehicle_name) return EnvironmentState.from_msgpack(env_state) simGetGroundTruthEnvironment.__annotations__ = {'return': EnvironmentState} # sensor APIs def getImuData(self, imu_name = '', vehicle_name = ''): + """ + Args: + imu_name (str, optional): Name of IMU to get data from, specified in settings.json + vehicle_name (str, optional): Name of vehicle to which the sensor corresponds to + + Returns: + ImuData: + """ return ImuData.from_msgpack(self.client.call('getImuData', imu_name, vehicle_name)) def getBarometerData(self, barometer_name = '', vehicle_name = ''): + """ + Args: + barometer_name (str, optional): Name of Barometer to get data from, specified in settings.json + vehicle_name (str, optional): Name of vehicle to which the sensor corresponds to + + Returns: + BarometerData: + """ return BarometerData.from_msgpack(self.client.call('getBarometerData', barometer_name, vehicle_name)) def getMagnetometerData(self, magnetometer_name = '', vehicle_name = ''): + """ + Args: + magnetometer_name (str, optional): Name of Magnetometer to get data from, specified in settings.json + vehicle_name (str, optional): Name of vehicle to which the sensor corresponds to + + Returns: + MagnetometerData: + """ return MagnetometerData.from_msgpack(self.client.call('getMagnetometerData', magnetometer_name, vehicle_name)) def getGpsData(self, gps_name = '', vehicle_name = ''): + """ + Args: + gps_name (str, optional): Name of GPS to get data from, specified in settings.json + vehicle_name (str, optional): Name of vehicle to which the sensor corresponds to + + Returns: + GpsData: + """ return GpsData.from_msgpack(self.client.call('getGpsData', gps_name, vehicle_name)) def getDistanceSensorData(self, distance_sensor_name = '', vehicle_name = ''): + """ + Args: + distance_sensor_name (str, optional): Name of Distance Sensor to get data from, specified in settings.json + vehicle_name (str, optional): Name of vehicle to which the sensor corresponds to + + Returns: + DistanceSensorData: + """ return DistanceSensorData.from_msgpack(self.client.call('getDistanceSensorData', distance_sensor_name, vehicle_name)) def getLidarData(self, lidar_name = '', vehicle_name = ''): + """ + Args: + lidar_name (str, optional): Name of Lidar to get data from, specified in settings.json + vehicle_name (str, optional): Name of vehicle to which the sensor corresponds to + + Returns: + LidarData: + """ return LidarData.from_msgpack(self.client.call('getLidarData', lidar_name, vehicle_name)) - + def simGetLidarSegmentation(self, lidar_name = '', vehicle_name = ''): + """ + Returns Segmentation ID of each point's collided object in the last Lidar update + + Args: + lidar_name (str, optional): Name of Lidar sensor + vehicle_name (str, optional): Name of the vehicle wth the sensor + + Returns: + list[int]: Segmentation IDs of the objects + """ return self.client.call('simGetLidarSegmentation', lidar_name, vehicle_name) # Plotting APIs def simFlushPersistentMarkers(self): """ - Clear any persistent markers - those plotted with setting is_persistent=True in the APIs below + Clear any persistent markers - those plotted with setting `is_persistent=True` in the APIs below """ self.client.call('simFlushPersistentMarkers') def simPlotPoints(self, points, color_rgba=[1.0, 0.0, 0.0, 1.0], size = 10.0, duration = -1.0, is_persistent = False): """ Plot a list of 3D points in World NED frame - + Args: - points (list[Vector3r]): List of Vector3r objects + points (list[Vector3r]): List of Vector3r objects color_rgba (list, optional): desired RGBA values from 0.0 to 1.0 size (float, optional): Size of plotted point duration (float, optional): Duration (seconds) to plot for @@ -234,7 +572,7 @@ def simPlotPoints(self, points, color_rgba=[1.0, 0.0, 0.0, 1.0], size = 10.0, du def simPlotLineStrip(self, points, color_rgba=[1.0, 0.0, 0.0, 1.0], thickness = 5.0, duration = -1.0, is_persistent = False): """ Plots a line strip in World NED frame, defined from points[0] to points[1], points[1] to points[2], ... , points[n-2] to points[n-1] - + Args: points (list[Vector3r]): List of 3D locations of line start and end points, specified as Vector3r objects color_rgba (list, optional): desired RGBA values from 0.0 to 1.0 @@ -247,7 +585,7 @@ def simPlotLineStrip(self, points, color_rgba=[1.0, 0.0, 0.0, 1.0], thickness = def simPlotLineList(self, points, color_rgba=[1.0, 0.0, 0.0, 1.0], thickness = 5.0, duration = -1.0, is_persistent = False): """ Plots a line strip in World NED frame, defined from points[0] to points[1], points[2] to points[3], ... , points[n-2] to points[n-1] - + Args: points (list[Vector3r]): List of 3D locations of line start and end points, specified as Vector3r objects. Must be even color_rgba (list, optional): desired RGBA values from 0.0 to 1.0 @@ -275,7 +613,7 @@ def simPlotArrows(self, points_start, points_end, color_rgba=[1.0, 0.0, 0.0, 1.0 def simPlotStrings(self, strings, positions, scale = 5, color_rgba=[1.0, 0.0, 0.0, 1.0], duration = -1.0): """ - Plots a list of strings at desired positions in World NED frame. + Plots a list of strings at desired positions in World NED frame. Args: strings (list[String], optional): List of strings to plot @@ -288,12 +626,12 @@ def simPlotStrings(self, strings, positions, scale = 5, color_rgba=[1.0, 0.0, 0. def simPlotTransforms(self, poses, scale = 5.0, thickness = 5.0, duration = -1.0, is_persistent = False): """ - Plots a list of transforms in World NED frame. + Plots a list of transforms in World NED frame. Args: poses (list[Pose]): List of Pose objects representing the transforms to plot scale (float, optional): Length of transforms' axes - thickness (float, optional): Thickness of transforms' axes + thickness (float, optional): Thickness of transforms' axes duration (float, optional): Duration (seconds) to plot for is_persistent (bool, optional): If set to True, the desired object will be plotted for infinite time. """ @@ -301,13 +639,13 @@ def simPlotTransforms(self, poses, scale = 5.0, thickness = 5.0, duration = -1.0 def simPlotTransformsWithNames(self, poses, names, tf_scale = 5.0, tf_thickness = 5.0, text_scale = 10.0, text_color_rgba = [1.0, 0.0, 0.0, 1.0], duration = -1.0): """ - Plots a list of transforms with their names in World NED frame. - + Plots a list of transforms with their names in World NED frame. + Args: poses (list[Pose]): List of Pose objects representing the transforms to plot names (list[string]): List of strings with one-to-one correspondence to list of poses tf_scale (float, optional): Length of transforms' axes - tf_thickness (float, optional): Thickness of transforms' axes + tf_thickness (float, optional): Thickness of transforms' axes text_scale (float, optional): Font scale of transform name text_color_rgba (list, optional): desired RGBA values from 0.0 to 1.0 for the transform name duration (float, optional): Duration (seconds) to plot for @@ -315,8 +653,26 @@ def simPlotTransformsWithNames(self, poses, names, tf_scale = 5.0, tf_thickness self.client.call('simPlotTransformsWithNames', poses, names, tf_scale, tf_thickness, text_scale, text_color_rgba, duration) def cancelLastTask(self, vehicle_name = ''): + """ + Cancel previous Async task + + Args: + vehicle_name (str, optional): Name of the vehicle + """ self.client.call('cancelLastTask', vehicle_name) + def waitOnLastTask(self, timeout_sec = float('nan')): + """ + Wait for the last Async task to complete + + Args: + timeout_sec (float, optional): Time for the task to complete + + Returns: + bool: Result of the last task + + True if the task completed without cancellation or timeout + """ return self.client.call('waitOnLastTask', timeout_sec) # ----------------------------------- Multirotor APIs --------------------------------------------- @@ -325,12 +681,42 @@ def __init__(self, ip = "", port = 41451, timeout_value = 3600): super(MultirotorClient, self).__init__(ip, port, timeout_value) def takeoffAsync(self, timeout_sec = 20, vehicle_name = ''): - return self.client.call_async('takeoff', timeout_sec, vehicle_name) + """ + Takeoff vehicle to 3m above ground. Vehicle should not be moving when this API is used + + Args: + timeout_sec (int, optional): Timeout for the vehicle to reach desired altitude + vehicle_name (str, optional): Name of the vehicle to send this command to + + Returns: + msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() + """ + return self.client.call_async('takeoff', timeout_sec, vehicle_name) def landAsync(self, timeout_sec = 60, vehicle_name = ''): - return self.client.call_async('land', timeout_sec, vehicle_name) + """ + Land the vehicle + + Args: + timeout_sec (int, optional): Timeout for the vehicle to land + vehicle_name (str, optional): Name of the vehicle to send this command to + + Returns: + msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() + """ + return self.client.call_async('land', timeout_sec, vehicle_name) def goHomeAsync(self, timeout_sec = 3e+38, vehicle_name = ''): + """ + Return vehicle to Home i.e. Launch location + + Args: + timeout_sec (int, optional): Timeout for the vehicle to reach desired altitude + vehicle_name (str, optional): Name of the vehicle to send this command to + + Returns: + msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() + """ return self.client.call_async('goHome', timeout_sec, vehicle_name) # APIs for control @@ -341,16 +727,29 @@ def moveByAngleThrottleAsync(self, pitch, roll, throttle, yaw_rate, duration, ve return self.client.call_async('moveByAngleThrottle', pitch, roll, throttle, yaw_rate, duration, vehicle_name) def moveByVelocityAsync(self, vx, vy, vz, duration, drivetrain = DrivetrainType.MaxDegreeOfFreedom, yaw_mode = YawMode(), vehicle_name = ''): + """ + Args: + vx (float): desired velocity in world (NED) X axis + vy (float): desired velocity in world (NED) Y axis + vz (float): desired velocity in world (NED) Z axis + duration (float): Desired amount of time (seconds), to send this command for + drivetrain (DrivetrainType, optional): + yaw_mode (YawMode, optional): + vehicle_name (str, optional): Name of the multirotor to send this command to + + Returns: + msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() + """ return self.client.call_async('moveByVelocity', vx, vy, vz, duration, drivetrain, yaw_mode, vehicle_name) def moveByVelocityZAsync(self, vx, vy, z, duration, drivetrain = DrivetrainType.MaxDegreeOfFreedom, yaw_mode = YawMode(), vehicle_name = ''): return self.client.call_async('moveByVelocityZ', vx, vy, z, duration, drivetrain, yaw_mode, vehicle_name) - def moveOnPathAsync(self, path, velocity, timeout_sec = 3e+38, drivetrain = DrivetrainType.MaxDegreeOfFreedom, yaw_mode = YawMode(), + def moveOnPathAsync(self, path, velocity, timeout_sec = 3e+38, drivetrain = DrivetrainType.MaxDegreeOfFreedom, yaw_mode = YawMode(), lookahead = -1, adaptive_lookahead = 1, vehicle_name = ''): return self.client.call_async('moveOnPath', path, velocity, timeout_sec, drivetrain, yaw_mode, lookahead, adaptive_lookahead, vehicle_name) - def moveToPositionAsync(self, x, y, z, velocity, timeout_sec = 3e+38, drivetrain = DrivetrainType.MaxDegreeOfFreedom, yaw_mode = YawMode(), + def moveToPositionAsync(self, x, y, z, velocity, timeout_sec = 3e+38, drivetrain = DrivetrainType.MaxDegreeOfFreedom, yaw_mode = YawMode(), lookahead = -1, adaptive_lookahead = 1, vehicle_name = ''): return self.client.call_async('moveToPosition', x, y, z, velocity, timeout_sec, drivetrain, yaw_mode, lookahead, adaptive_lookahead, vehicle_name) @@ -358,18 +757,23 @@ def moveToZAsync(self, z, velocity, timeout_sec = 3e+38, yaw_mode = YawMode(), l return self.client.call_async('moveToZ', z, velocity, timeout_sec, yaw_mode, lookahead, adaptive_lookahead, vehicle_name) def moveByManualAsync(self, vx_max, vy_max, z_min, duration, drivetrain = DrivetrainType.MaxDegreeOfFreedom, yaw_mode = YawMode(), vehicle_name = ''): - """Read current RC state and use it to control the vehicles. + """ + - Read current RC state and use it to control the vehicles. Parameters sets up the constraints on velocity and minimum altitude while flying. If RC state is detected to violate these constraints then that RC state would be ignored. - :param vx_max: max velocity allowed in x direction - :param vy_max: max velocity allowed in y direction - :param vz_max: max velocity allowed in z direction - :param z_min: min z allowed for vehicle position - :param duration: after this duration vehicle would switch back to non-manual mode - :param drivetrain: when ForwardOnly, vehicle rotates itself so that its front is always facing the direction of travel. If MaxDegreeOfFreedom then it doesn't do that (crab-like movement) - :param yaw_mode: Specifies if vehicle should face at given angle (is_rate=False) or should be rotating around its axis at given rate (is_rate=True) + Args: + vx_max (float): max velocity allowed in x direction + vy_max (float): max velocity allowed in y direction + vz_max (float): max velocity allowed in z direction + z_min (float): min z allowed for vehicle position + duration (float): after this duration vehicle would switch back to non-manual mode + drivetrain (DrivetrainType): when ForwardOnly, vehicle rotates itself so that its front is always facing the direction of travel. If MaxDegreeOfFreedom then it doesn't do that (crab-like movement) + yaw_mode (YawMode): Specifies if vehicle should face at given angle (is_rate=False) or should be rotating around its axis at given rate (is_rate=True) + vehicle_name (str, optional): Name of the multirotor to send this command to + Returns: + msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() """ return self.client.call_async('moveByManual', vx_max, vy_max, z_min, duration, drivetrain, yaw_mode, vehicle_name) @@ -389,6 +793,7 @@ def moveByRC(self, rcdata = RCData(), vehicle_name = ''): def moveByMotorPWMsAsync(self, front_right_pwm, rear_left_pwm, front_left_pwm, rear_right_pwm, duration, vehicle_name = ''): """ - Directly control the motors using PWM values + Args: front_right_pwm (float): PWM value for the front right motor (between 0.0 to 1.0) rear_left_pwm (float): PWM value for the rear left motor (between 0.0 to 1.0) @@ -403,31 +808,34 @@ def moveByMotorPWMsAsync(self, front_right_pwm, rear_left_pwm, front_left_pwm, r def moveByRollPitchYawZAsync(self, roll, pitch, yaw, z, duration, vehicle_name = ''): """ - - z is given in local NED frame of the vehicle. - - Roll angle, pitch angle, and yaw angle set points are given in **radians**, in the body frame. - - The body frame follows the Front Left Up (FLU) convention, and right-handedness. + - z is given in local NED frame of the vehicle. + - Roll angle, pitch angle, and yaw angle set points are given in **radians**, in the body frame. + - The body frame follows the Front Left Up (FLU) convention, and right-handedness. - Frame Convention: - - X axis is along the **Front** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **roll** angle. - | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + - X axis is along the **Front** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **roll** angle. + | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. - - Y axis is along the **Left** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **pitch** angle. - | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + - Y axis is along the **Left** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **pitch** angle. + | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + + - Z axis is along the **Up** direction. + + | Clockwise rotation about this axis defines a positive **yaw** angle. + | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - - Z axis is along the **Up** direction. - | Clockwise rotation about this axis defines a positive **yaw** angle. - | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - Args: roll (float): Desired roll angle, in radians. pitch (float): Desired pitch angle, in radians. yaw (float): Desired yaw angle, in radians. z (float): Desired Z value (in local NED frame of the vehicle) duration (float): Desired amount of time (seconds), to send this command for - vehicle_name (str, optional): Name of the multirotor to send this command to - + vehicle_name (str, optional): Name of the multirotor to send this command to + Returns: msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() """ @@ -436,30 +844,33 @@ def moveByRollPitchYawZAsync(self, roll, pitch, yaw, z, duration, vehicle_name = def moveByRollPitchYawThrottleAsync(self, roll, pitch, yaw, throttle, duration, vehicle_name = ''): """ - Desired throttle is between 0.0 to 1.0 - - Roll angle, pitch angle, and yaw angle are given in **radians**, in the body frame. - - The body frame follows the Front Left Up (FLU) convention, and right-handedness. + - Roll angle, pitch angle, and yaw angle are given in **radians**, in the body frame. + - The body frame follows the Front Left Up (FLU) convention, and right-handedness. - Frame Convention: - - X axis is along the **Front** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **roll** angle. - | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + - X axis is along the **Front** direction of the quadrotor. - - Y axis is along the **Left** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **pitch** angle. - | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + | Clockwise rotation about this axis defines a positive **roll** angle. + | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + + - Y axis is along the **Left** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **pitch** angle. + | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + + - Z axis is along the **Up** direction. + + | Clockwise rotation about this axis defines a positive **yaw** angle. + | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - - Z axis is along the **Up** direction. - | Clockwise rotation about this axis defines a positive **yaw** angle. - | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - Args: roll (float): Desired roll angle, in radians. pitch (float): Desired pitch angle, in radians. yaw (float): Desired yaw angle, in radians. throttle (float): Desired throttle (between 0.0 to 1.0) duration (float): Desired amount of time (seconds), to send this command for - vehicle_name (str, optional): Name of the multirotor to send this command to - + vehicle_name (str, optional): Name of the multirotor to send this command to + Returns: msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() """ @@ -468,30 +879,33 @@ def moveByRollPitchYawThrottleAsync(self, roll, pitch, yaw, throttle, duration, def moveByRollPitchYawrateThrottleAsync(self, roll, pitch, yaw_rate, throttle, duration, vehicle_name = ''): """ - Desired throttle is between 0.0 to 1.0 - - Roll angle, pitch angle, and yaw rate set points are given in **radians**, in the body frame. - - The body frame follows the Front Left Up (FLU) convention, and right-handedness. + - Roll angle, pitch angle, and yaw rate set points are given in **radians**, in the body frame. + - The body frame follows the Front Left Up (FLU) convention, and right-handedness. - Frame Convention: - - X axis is along the **Front** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **roll** angle. - | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + - X axis is along the **Front** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **roll** angle. + | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + + - Y axis is along the **Left** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **pitch** angle. + | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + + - Z axis is along the **Up** direction. - - Y axis is along the **Left** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **pitch** angle. - | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + | Clockwise rotation about this axis defines a positive **yaw** angle. + | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - - Z axis is along the **Up** direction. - | Clockwise rotation about this axis defines a positive **yaw** angle. - | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - Args: roll (float): Desired roll angle, in radians. pitch (float): Desired pitch angle, in radians. yaw_rate (float): Desired yaw rate, in radian per second. throttle (float): Desired throttle (between 0.0 to 1.0) duration (float): Desired amount of time (seconds), to send this command for - vehicle_name (str, optional): Name of the multirotor to send this command to - + vehicle_name (str, optional): Name of the multirotor to send this command to + Returns: msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() """ @@ -499,31 +913,34 @@ def moveByRollPitchYawrateThrottleAsync(self, roll, pitch, yaw_rate, throttle, d def moveByRollPitchYawrateZAsync(self, roll, pitch, yaw_rate, z, duration, vehicle_name = ''): """ - - z is given in local NED frame of the vehicle. - - Roll angle, pitch angle, and yaw rate set points are given in **radians**, in the body frame. - - The body frame follows the Front Left Up (FLU) convention, and right-handedness. + - z is given in local NED frame of the vehicle. + - Roll angle, pitch angle, and yaw rate set points are given in **radians**, in the body frame. + - The body frame follows the Front Left Up (FLU) convention, and right-handedness. - Frame Convention: - - X axis is along the **Front** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **roll** angle. - | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + - X axis is along the **Front** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **roll** angle. + | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + + - Y axis is along the **Left** direction of the quadrotor. - - Y axis is along the **Left** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **pitch** angle. - | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + | Clockwise rotation about this axis defines a positive **pitch** angle. + | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + + - Z axis is along the **Up** direction. + + | Clockwise rotation about this axis defines a positive **yaw** angle. + | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - - Z axis is along the **Up** direction. - | Clockwise rotation about this axis defines a positive **yaw** angle. - | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - Args: roll (float): Desired roll angle, in radians. pitch (float): Desired pitch angle, in radians. yaw_rate (float): Desired yaw rate, in radian per second. z (float): Desired Z value (in local NED frame of the vehicle) duration (float): Desired amount of time (seconds), to send this command for - vehicle_name (str, optional): Name of the multirotor to send this command to - + vehicle_name (str, optional): Name of the multirotor to send this command to + Returns: msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() """ @@ -531,31 +948,34 @@ def moveByRollPitchYawrateZAsync(self, roll, pitch, yaw_rate, z, duration, vehic def moveByAngleRatesZAsync(self, roll_rate, pitch_rate, yaw_rate, z, duration, vehicle_name = ''): """ - - z is given in local NED frame of the vehicle. - - Roll rate, pitch rate, and yaw rate set points are given in **radians**, in the body frame. - - The body frame follows the Front Left Up (FLU) convention, and right-handedness. + - z is given in local NED frame of the vehicle. + - Roll rate, pitch rate, and yaw rate set points are given in **radians**, in the body frame. + - The body frame follows the Front Left Up (FLU) convention, and right-handedness. - Frame Convention: - - X axis is along the **Front** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **roll** angle. - | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + - X axis is along the **Front** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **roll** angle. + | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. - - Y axis is along the **Left** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **pitch** angle. - | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + - Y axis is along the **Left** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **pitch** angle. + | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + + - Z axis is along the **Up** direction. + + | Clockwise rotation about this axis defines a positive **yaw** angle. + | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - - Z axis is along the **Up** direction. - | Clockwise rotation about this axis defines a positive **yaw** angle. - | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. - Args: roll_rate (float): Desired roll rate, in radians / second pitch_rate (float): Desired pitch rate, in radians / second yaw_rate (float): Desired yaw rate, in radians / second z (float): Desired Z value (in local NED frame of the vehicle) duration (float): Desired amount of time (seconds), to send this command for - vehicle_name (str, optional): Name of the multirotor to send this command to - + vehicle_name (str, optional): Name of the multirotor to send this command to + Returns: msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() """ @@ -564,21 +984,24 @@ def moveByAngleRatesZAsync(self, roll_rate, pitch_rate, yaw_rate, z, duration, v def moveByAngleRatesThrottleAsync(self, roll_rate, pitch_rate, yaw_rate, throttle, duration, vehicle_name = ''): """ - Desired throttle is between 0.0 to 1.0 - - Roll rate, pitch rate, and yaw rate set points are given in **radians**, in the body frame. - - The body frame follows the Front Left Up (FLU) convention, and right-handedness. + - Roll rate, pitch rate, and yaw rate set points are given in **radians**, in the body frame. + - The body frame follows the Front Left Up (FLU) convention, and right-handedness. - Frame Convention: - - X axis is along the **Front** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **roll** angle. - | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. + - X axis is along the **Front** direction of the quadrotor. - - Y axis is along the **Left** direction of the quadrotor. - | Clockwise rotation about this axis defines a positive **pitch** angle. - | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + | Clockwise rotation about this axis defines a positive **roll** angle. + | Hence, rolling with a positive angle is equivalent to translating in the **right** direction, w.r.t. our FLU body frame. - - Z axis is along the **Up** direction. - | Clockwise rotation about this axis defines a positive **yaw** angle. - | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. + - Y axis is along the **Left** direction of the quadrotor. + + | Clockwise rotation about this axis defines a positive **pitch** angle. + | Hence, pitching with a positive angle is equivalent to translating in the **front** direction, w.r.t. our FLU body frame. + + - Z axis is along the **Up** direction. + + | Clockwise rotation about this axis defines a positive **yaw** angle. + | Hence, yawing with a positive angle is equivalent to rotated towards the **left** direction wrt our FLU body frame. Or in an anticlockwise fashion in the body XY / FL plane. Args: roll_rate (float): Desired roll rate, in radians / second @@ -586,8 +1009,8 @@ def moveByAngleRatesThrottleAsync(self, roll_rate, pitch_rate, yaw_rate, throttl yaw_rate (float): Desired yaw rate, in radians / second throttle (float): Desired throttle (between 0.0 to 1.0) duration (float): Desired amount of time (seconds), to send this command for - vehicle_name (str, optional): Name of the multirotor to send this command to - + vehicle_name (str, optional): Name of the multirotor to send this command to + Returns: msgpackrpc.future.Future: future. call .join() to wait for method to finish. Example: client.METHOD().join() """ @@ -595,32 +1018,32 @@ def moveByAngleRatesThrottleAsync(self, roll_rate, pitch_rate, yaw_rate, throttl def setAngleRateControllerGains(self, angle_rate_gains=AngleRateControllerGains(), vehicle_name = ''): """ - - Modifying these gains will have an affect on *ALL* move*() APIs. - This is because any velocity setpoint is converted to an angle level setpoint which is tracked with an angle level controllers. - That angle level setpoint is itself tracked with and angle rate controller. + - Modifying these gains will have an affect on *ALL* move*() APIs. + This is because any velocity setpoint is converted to an angle level setpoint which is tracked with an angle level controllers. + That angle level setpoint is itself tracked with and angle rate controller. - This function should only be called if the default angle rate control PID gains need to be modified. Args: - angle_rate_gains (AngleRateControllerGains): - - Correspond to the roll, pitch, yaw axes, defined in the body frame. + angle_rate_gains (AngleRateControllerGains): + - Correspond to the roll, pitch, yaw axes, defined in the body frame. - Pass AngleRateControllerGains() to reset gains to default recommended values. - vehicle_name (str, optional): Name of the multirotor to send this command to + vehicle_name (str, optional): Name of the multirotor to send this command to """ self.client.call('setAngleRateControllerGains', *(angle_rate_gains.to_lists()+(vehicle_name,))) def setAngleLevelControllerGains(self, angle_level_gains=AngleLevelControllerGains(), vehicle_name = ''): """ - Sets angle level controller gains (used by any API setting angle references - for ex: moveByRollPitchYawZAsync(), moveByRollPitchYawThrottleAsync(), etc) - - Modifying these gains will also affect the behaviour of moveByVelocityAsync() API. - This is because the AirSim flight controller will track velocity setpoints by converting them to angle set points. + - Modifying these gains will also affect the behaviour of moveByVelocityAsync() API. + This is because the AirSim flight controller will track velocity setpoints by converting them to angle set points. - This function should only be called if the default angle level control PID gains need to be modified. - - Passing AngleLevelControllerGains() sets gains to default airsim values. + - Passing AngleLevelControllerGains() sets gains to default airsim values. Args: - angle_level_gains (AngleLevelControllerGains): - - Correspond to the roll, pitch, yaw axes, defined in the body frame. + angle_level_gains (AngleLevelControllerGains): + - Correspond to the roll, pitch, yaw axes, defined in the body frame. - Pass AngleLevelControllerGains() to reset gains to default recommended values. - vehicle_name (str, optional): Name of the multirotor to send this command to + vehicle_name (str, optional): Name of the multirotor to send this command to """ self.client.call('setAngleLevelControllerGains', *(angle_level_gains.to_lists()+(vehicle_name,))) @@ -628,14 +1051,14 @@ def setVelocityControllerGains(self, velocity_gains=VelocityControllerGains(), v """ - Sets velocity controller gains for moveByVelocityAsync(). - This function should only be called if the default velocity control PID gains need to be modified. - - Passing VelocityControllerGains() sets gains to default airsim values. + - Passing VelocityControllerGains() sets gains to default airsim values. Args: - velocity_gains (VelocityControllerGains): - - Correspond to the world X, Y, Z axes. + velocity_gains (VelocityControllerGains): + - Correspond to the world X, Y, Z axes. - Pass VelocityControllerGains() to reset gains to default recommended values. - - Modifying velocity controller gains will have an affect on the behaviour of moveOnSplineAsync() and moveOnSplineVelConstraintsAsync(), as they both use velocity control to track the trajectory. - vehicle_name (str, optional): Name of the multirotor to send this command to + - Modifying velocity controller gains will have an affect on the behaviour of moveOnSplineAsync() and moveOnSplineVelConstraintsAsync(), as they both use velocity control to track the trajectory. + vehicle_name (str, optional): Name of the multirotor to send this command to """ self.client.call('setVelocityControllerGains', *(velocity_gains.to_lists()+(vehicle_name,))) @@ -646,15 +1069,22 @@ def setPositionControllerGains(self, position_gains=PositionControllerGains(), v This function should only be called if the default position control PID gains need to be modified. Args: - position_gains (PositionControllerGains): - - Correspond to the X, Y, Z axes. + position_gains (PositionControllerGains): + - Correspond to the X, Y, Z axes. - Pass PositionControllerGains() to reset gains to default recommended values. - vehicle_name (str, optional): Name of the multirotor to send this command to + vehicle_name (str, optional): Name of the multirotor to send this command to """ self.client.call('setPositionControllerGains', *(position_gains.to_lists()+(vehicle_name,))) # query vehicle state def getMultirotorState(self, vehicle_name = ''): + """ + Args: + vehicle_name (str, optional): Vehicle to get the state of + + Returns: + MultirotorState: + """ return MultirotorState.from_msgpack(self.client.call('getMultirotorState', vehicle_name)) getMultirotorState.__annotations__ = {'return': MultirotorState} @@ -665,12 +1095,33 @@ def __init__(self, ip = "", port = 41451, timeout_value = 3600): super(CarClient, self).__init__(ip, port, timeout_value) def setCarControls(self, controls, vehicle_name = ''): + """ + Control the car using throttle, steering, brake, etc. + + Args: + controls (CarControls): Struct containing control values + vehicle_name (str, optional): Name of vehicle to be controlled + """ self.client.call('setCarControls', controls, vehicle_name) def getCarState(self, vehicle_name = ''): + """ + Args: + vehicle_name (str, optional): Name of vehicle + + Returns: + CarState: + """ state_raw = self.client.call('getCarState', vehicle_name) return CarState.from_msgpack(state_raw) def getCarControls(self, vehicle_name=''): + """ + Args: + vehicle_name (str, optional): Name of vehicle + + Returns: + CarControls: + """ controls_raw = self.client.call('getCarControls', vehicle_name) - return CarControls.from_msgpack(controls_raw) \ No newline at end of file + return CarControls.from_msgpack(controls_raw) From ffce27d32b47888aa2dff623a99558b3b278e869 Mon Sep 17 00:00:00 2001 From: madratman Date: Tue, 14 Apr 2020 15:05:57 -0700 Subject: [PATCH 2/3] [docs:api] add api doc generator using sphynx --- .gitignore | 3 + PythonClient/build_api_docs.sh | 2 + PythonClient/docs/Makefile | 19 +++ PythonClient/docs/conf.py | 203 +++++++++++++++++++++++++++++++++ PythonClient/docs/index.rst | 28 +++++ PythonClient/docs/make.bat | 35 ++++++ 6 files changed, 290 insertions(+) create mode 100755 PythonClient/build_api_docs.sh create mode 100644 PythonClient/docs/Makefile create mode 100644 PythonClient/docs/conf.py create mode 100644 PythonClient/docs/index.rst create mode 100644 PythonClient/docs/make.bat diff --git a/.gitignore b/.gitignore index adacf36bf3..32a591cec1 100644 --- a/.gitignore +++ b/.gitignore @@ -377,3 +377,6 @@ ros/src/CMakeLists.txt # docs docs/README.md build_docs/ + +# api docs +PythonClient/docs/_build diff --git a/PythonClient/build_api_docs.sh b/PythonClient/build_api_docs.sh new file mode 100755 index 0000000000..548e7d9517 --- /dev/null +++ b/PythonClient/build_api_docs.sh @@ -0,0 +1,2 @@ +cd docs; +make html; diff --git a/PythonClient/docs/Makefile b/PythonClient/docs/Makefile new file mode 100644 index 0000000000..298ea9e213 --- /dev/null +++ b/PythonClient/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/PythonClient/docs/conf.py b/PythonClient/docs/conf.py new file mode 100644 index 0000000000..5a5361e8c9 --- /dev/null +++ b/PythonClient/docs/conf.py @@ -0,0 +1,203 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('..')) + +import sphinx_rtd_theme + +# -- Project information ----------------------------------------------------- + +project = u'airsim' +copyright = u'2020, Shital Shah, Ratnesh Madaan, Sai Vemprala, Nicholas Gyde' +author = u'Shital Shah, Ratnesh Madaan, Sai Vemprala, Nicholas Gyde' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'1.2.8' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.coverage', + 'sphinx.ext.napoleon', + 'sphinx_rtd_theme' +] + +autodoc_default_flags = ['members'] +autosummary_generate = True +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth = 4 + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'airsimdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'airsim.tex', u'airsim Documentation', + u'Ratnesh Madaan, Matthew Brown, Nicholas Gyde', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'airsim', u'airsim Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'airsim', u'airsim Documentation', + author, 'airsim', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/PythonClient/docs/index.rst b/PythonClient/docs/index.rst new file mode 100644 index 0000000000..9aed7a55be --- /dev/null +++ b/PythonClient/docs/index.rst @@ -0,0 +1,28 @@ +.. airsim documentation master file, created by + sphinx-quickstart on Sun Aug 4 14:58:26 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +airsim +========================================= +This page documents `airsim`_, the python package to be used for `Game of Drones: A NeurIPS 2019 Competition`_. + +.. _`airsim`: https://pypi.org/project/airsim/ +.. _`Microsoft AirSim`: https://github.com/microsoft/AirSim + +.. toctree:: + :maxdepth: 3 + +* :ref:`genindex` +* :ref:`modindex` + +.. autoclass:: airsim.client.MultirotorClient + :members: + +.. automodule:: airsim.types + :members: + :show-inheritance: + +.. automodule:: airsim.utils + :members: + :show-inheritance: \ No newline at end of file diff --git a/PythonClient/docs/make.bat b/PythonClient/docs/make.bat new file mode 100644 index 0000000000..27f573b87a --- /dev/null +++ b/PythonClient/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd From a5bd948f6b5ac92a4267f774cd1d4bc2eedd1678 Mon Sep 17 00:00:00 2001 From: Rajat Singhal Date: Wed, 15 Apr 2020 12:54:50 +0530 Subject: [PATCH 3/3] [Pythonclient/docs] Add Vehicle, Car client classes, more fixes List members without docstrings also, add viewcode extension --- PythonClient/docs/conf.py | 1 + PythonClient/docs/index.rst | 18 ++++++++++++++++-- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/PythonClient/docs/conf.py b/PythonClient/docs/conf.py index 5a5361e8c9..e7bfe2273d 100644 --- a/PythonClient/docs/conf.py +++ b/PythonClient/docs/conf.py @@ -49,6 +49,7 @@ 'sphinx.ext.mathjax', 'sphinx.ext.coverage', 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', 'sphinx_rtd_theme' ] diff --git a/PythonClient/docs/index.rst b/PythonClient/docs/index.rst index 9aed7a55be..c256e3fcd4 100644 --- a/PythonClient/docs/index.rst +++ b/PythonClient/docs/index.rst @@ -5,7 +5,7 @@ airsim ========================================= -This page documents `airsim`_, the python package to be used for `Game of Drones: A NeurIPS 2019 Competition`_. +This page documents `airsim`_, the python package to be used for `Microsoft AirSim`_. .. _`airsim`: https://pypi.org/project/airsim/ .. _`Microsoft AirSim`: https://github.com/microsoft/AirSim @@ -16,13 +16,27 @@ This page documents `airsim`_, the python package to be used for `Game of Drones * :ref:`genindex` * :ref:`modindex` +.. autoclass:: airsim.client.VehicleClient + :members: + :undoc-members: + :show-inheritance: + .. autoclass:: airsim.client.MultirotorClient :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: airsim.client.CarClient + :members: + :undoc-members: + :show-inheritance: .. automodule:: airsim.types :members: + :undoc-members: :show-inheritance: .. automodule:: airsim.utils - :members: + :members: + :undoc-members: :show-inheritance: \ No newline at end of file