diff --git a/README.md b/README.md index 2fe2bbd..a8f6338 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,14 @@ Note: If you use this repository in your research, please cite our pre-print, [A } ``` -### Using AirSim Drone Racing Lab Binaries +## Getting Binaries - [Linux](docs/using_binaries.md#linux) - [Windows](docs/using_binaries.md#windows) - [Docker on Linux](docs/docker.md) -## Using ADRL -- [Overview](docs/api_overview.md) +## Using AirSim Drone Racing Lab +- [AirSim Drone Racing Lab Overview](docs/adrl_overview.md) +- [API Overview](docs/api_overview.md) - [Baselines](docs/baselines.md) - [Race Monitoring](docs/race_monitoring.md) - [Documentation](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html) diff --git a/docs/adrl_overview.md b/docs/adrl_overview.md new file mode 100644 index 0000000..ee769d1 --- /dev/null +++ b/docs/adrl_overview.md @@ -0,0 +1,25 @@ +## AirSim Drone Racing Lab: Overview + + +ADRL is a framework for drone racing research, built on [Microsoft AirSim](https://github.com/Microsoft/Airsim). +We used our framework to host a simulation-based drone racing competition at NeurIPS 2019, [Game of Drones](https://github.com/microsoft/AirSim-NeurIPS2019-Drone-Racing). + +Currently, ADRL allows you to focus on three core research directions pertinent to autonomous drone racing - perception, trajectory planning and control, and head-tp-head competition with a single competitor drone. + +## Race Tiers + + + +### Tier I: Planning Only +The participant’s drone races tête-à-tête with an opponent racer. +Ground truth for state estimation and environment is provided via our APIs, in the form of the odometry (position and velocity) of the participant and the opponent drones, and the poses of all the gates. +The opponent racer follows a minimum jerk trajectory via `moveOnSpline`, and goes through randomized waypoints selected in each gate's cross section. +Hence, the opponent's trajectory varies at every run. + +### Tier II: Perception Only +In this tier, the gate poses returned by the API are corrupted with noise as shown in the GIF on the right side above, and there is no opponent drone. +The ground truth state estimate of the participant drone is still available. +The next gate is not always in view, but the noisy pose returned by our API help steer the participants roughly in the right direction, after which vision-based control would be necessary. + +### Tier III: Planning and Perception +This tier has both noisy gate poses and an opponent racer, and is essentially a combination of Tier 1 and 2. diff --git a/docs/api_overview.md b/docs/api_overview.md index 3a994f2..978227b 100644 --- a/docs/api_overview.md +++ b/docs/api_overview.md @@ -1,92 +1,100 @@ ## API overview We added some new APIs (marked with 💚) to [AirSim](https://github.com/Microsoft/Airsim) for the NeurIPS competition binaries. -#### Loading Unreal Engine environments -- [`simLoadLevel(level_name)`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simLoadLevel) 💚 +#### Loading Unreal Engine environments +- [`simLoadLevel(level_name)`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simLoadLevel) 💚 Possible values for `level_name` are: - - `"Soccer_Field_Easy"`, `"Soccer_Field_Medium"`, `"ZhangJiaJie_Medium"`, `"Building99_Hard"` in the training binaries (`v0.3`). - - `"Qualification_Tier_1"`, `"Qualification_Tier_2"`, `"Qualification_Tier_3"` in the qualification binaries (`v1.0`). - - `"Final_Tier_1"`, `"Final_Tier_2"`, `"Final_Tier_3"` in the final round binaries (`v1.1`). -Before trying this, please ensure you've downloaded the corresponding training (`v0.3`) / qualifier (`v1.0`) / final round (`v1.0`) binaries, [as described above](https://github.com/microsoft/AirSim-NeurIPS2019-Drone-Racing#downloading-airsimexe-and-unreal-environments) + - `Soccer_Field_Easy` + - `Soccer_Field_Medium` + - `ZhangJiaJie_Medium` + - `Building99_Hard` + - `Qualification_Tier_1` + - `Qualification_Tier_2` + - `Qualification_Tier_3` + - `Final_Tier_1` + - `Final_Tier_2` + - `Final_Tier_3` + +Note that any race tier can be run for any level, irrespective of the `Tier_N` suffix. (Historic note: The names along with their suffixes are ported from [Game of Drones](https://github.com/microsoft/AirSim-NeurIPS2019-Drone-Racing)) - UI Menu - Press `F10` to toggle the level menu - - Click your desired level. (Note: the UI lists all the pakfiles in the `AirSim/AirSimExe/Content/Paks` directory. Ensure you downloaded the pakfile, if you are not able to see a particular environment) + - Click your desired level. (Note: the UI lists all the pakfiles in the `ADRL/ADRL/Content/Paks` directory.) #### Race APIs: - Start a race: - [`simStartRace(tier=1/2/3)`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simStartRace) 💚 + [`simStartRace(tier=1/2/3)`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simStartRace) 💚 - Reset race: - [`simResetRace()`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simResetRace) 💚 + [`simResetRace()`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simResetRace) 💚 - Check if racer is disqualified: - [`simIsRacerDisqualified()`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simIsRacerDisqualified) 💚 + [`simIsRacerDisqualified()`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simIsRacerDisqualified) 💚 - Get index of last gate passed: - [`simGetLastGatePassed()`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simGetLastGatePassed) 💚 + [`simGetLastGatePassed()`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simGetLastGatePassed) 💚 - Disable generation of logfiles by race APIs: - [`simDisableRaceLog`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simDisableRaceLog) 💚 + [`simDisableRaceLog`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simDisableRaceLog) 💚 #### Lower level control APIs: - FPV like Angle rate setpoint APIs: - - [`moveByAngleRatesThrottleAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByAngleRatesThrottleAsync) 💚 - - [`moveByAngleRatesZAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByAngleRatesZAsync) 💚 (stabilizes altitude) + - [`moveByAngleRatesThrottleAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByAngleRatesThrottleAsync) 💚 + - [`moveByAngleRatesZAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByAngleRatesZAsync) 💚 (stabilizes altitude) - Angle setpoint APIs: - - [`moveByRollPitchYawThrottleAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByRollPitchYawThrottleAsync) 💚 - - [`moveByRollPitchYawZAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByRollPitchYawZAsync) 💚 (stabilizes altitude) + - [`moveByRollPitchYawThrottleAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByRollPitchYawThrottleAsync) 💚 + - [`moveByRollPitchYawZAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByRollPitchYawZAsync) 💚 (stabilizes altitude) - RollPitchYawrate setpoint APIs: - - [`moveByRollPitchYawrateThrottleAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByRollPitchYawrateThrottleAsync) 💚 - - [`moveByRollPitchYawrateZAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByRollPitchYawrateZAsync) 💚 (stabilizes altitude) + - [`moveByRollPitchYawrateThrottleAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByRollPitchYawrateThrottleAsync) 💚 + - [`moveByRollPitchYawrateZAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByRollPitchYawrateZAsync) 💚 (stabilizes altitude) #### Medium level control APIs: - Velocity setpoints - - [`moveByVelocityAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByVelocityAsync) - - [`moveByVelocityZAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveByVelocityZAsync) (stabilizes altitude) + - [`moveByVelocityAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByVelocityAsync) + - [`moveByVelocityZAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveByVelocityZAsync) (stabilizes altitude) - Position setpoints - - [`moveToPosition`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveToPositionAsync) - - [`moveOnPath`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveOnPathAsync) - - [`moveToZAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveToZAsync) + - [`moveToPosition`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveToPositionAsync) + - [`moveOnPath`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveOnPathAsync) + - [`moveToZAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveToZAsync) #### High level control APIs: - Minimum jerk trajectory planning (using [ethz-asl/mav_trajectory_generation](https://github.com/ethz-asl/mav_trajectory_generation)), and trajectory tracking (using a pure pursuit like controller minimizing position and velocity errors), with position setpoints. Optionally use the `*lookahead*` parameters to start new trajectory from a point sampled `n` seconds ahead for trajectory being tracked currently. - - [`moveOnSplineAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveOnSplineAsync) 💚 + - [`moveOnSplineAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveOnSplineAsync) 💚 - Minimum jerk trajectory planning (using [ethz-asl/mav_trajectory_generation](https://github.com/ethz-asl/mav_trajectory_generation)), and trajectory tracking (using a pure pursuit like controller minimizing position and velocity errors), with position setpoints and corresponding velocity constraints. Useful for making a drone go through a gate waypoint, while obeying speed and direction constraints. Optionally use the `*lookahead*` parameters to start new trajectory from a point sampled `n` seconds ahead for trajectory being tracked currently. - - [`moveOnSplineVelConstraintsAsync`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.moveOnSplineVelConstraintsAsync) 💚 + - [`moveOnSplineVelConstraintsAsync`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.moveOnSplineVelConstraintsAsync) 💚 - Clear and stop following current trajectory. - - [`clearTrajectory`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.clearTrajectory) 💚 + - [`clearTrajectory`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.clearTrajectory) 💚 #### Gain setter APIs: -- [`setAngleRateControllerGains`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.setAngleRateControllerGains) 💚 -- [`setAngleLevelControllerGains`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.setAngleLevelControllerGains) 💚 -- [`setVelocityControllerGains`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.setVelocityControllerGains) 💚 -- [`setPositionControllerGains`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.setPositionControllerGains) 💚 -- [`setTrajectoryTrackerGains`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.setTrajectoryTrackerGains) 💚 +- [`setAngleRateControllerGains`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.setAngleRateControllerGains) 💚 +- [`setAngleLevelControllerGains`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.setAngleLevelControllerGains) 💚 +- [`setVelocityControllerGains`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.setVelocityControllerGains) 💚 +- [`setPositionControllerGains`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.setPositionControllerGains) 💚 +- [`setTrajectoryTrackerGains`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.setTrajectoryTrackerGains) 💚 #### APIs to help generate gate detection datasets: - Object pose setter and getter: - - [`simSetObjectPose`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simSetObjectPose) - - [`simGetObjectPose`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simGetObjectPose) + - [`simSetObjectPose`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simSetObjectPose) + - [`simGetObjectPose`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simGetObjectPose) - Object scale setter and getter: - - [`simSetObjectScale`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simSetObjectScale) 💚 - - [`simGetObjectScale`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simGetObjectScale) 💚 + - [`simSetObjectScale`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simSetObjectScale) 💚 + - [`simGetObjectScale`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simGetObjectScale) 💚 - Object segmentation ID setter and getter: - - [`simGetSegmentationObjectID`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simGetSegmentationObjectID) - - [`simSetSegmentationObjectID`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simSetSegmentationObjectID) + - [`simGetSegmentationObjectID`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simGetSegmentationObjectID) + - [`simSetSegmentationObjectID`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simSetSegmentationObjectID) - Listing all the objects in the scene: - - [`simListSceneObjects`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simListSceneObjects) 💚 + - [`simListSceneObjects`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simListSceneObjects) 💚 - Gate specific APIs: - - [`simGetNominalGateInnerDimensions`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simGetNominalGateInnerDimensions) 💚 - - [`simGetNominalGateOuterDimensions`](https://microsoft.github.io/AirSim-NeurIPS2019-Drone-Racing/api.html#airsimneurips.client.MultirotorClient.simGetNominalGateOuterDimensions) 💚 + - [`simGetNominalGateInnerDimensions`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simGetNominalGateInnerDimensions) 💚 + - [`simGetNominalGateOuterDimensions`](https://microsoft.github.io/AirSim-Drone-Racing-Lab/api.html#airsimdroneracinglab.client.MultirotorClient.simGetNominalGateOuterDimensions) 💚