Skip to content

Commit d109f0d

Browse files
sytelussytelus
committed
updated README
1 parent 0b2db65 commit d109f0d

3 files changed

Lines changed: 176 additions & 13 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,9 @@
1-
## Project AirSim announcement
2-
3-
Microsoft and IAMAI collaborated to advance high-fidelity autonomy simulations through Project AirSim—the evolution of AirSim— released under the MIT license as part of a DARPA-supported initiative. IAMAI is proud to have contributed to these efforts and has published its version of the Project AirSim repository at [github.com/iamaisim/ProjectAirSim](https://github.com/iamaisim/ProjectAirSim).
4-
5-
## AirSim announcement: This repository will be archived in the coming year
6-
7-
In 2017 Microsoft Research created AirSim as a simulation platform for AI research and experimentation. Over the span of five years, this research project has served its purpose—and gained a lot of ground—as a common way to share research code and test new ideas around aerial AI development and simulation. Additionally, time has yielded advancements in the way we apply technology to the real world, particularly through aerial mobility and autonomous systems. For example, drone delivery is no longer a sci-fi storyline—it’s a business reality, which means there are new needs to be met. We’ve learned a lot in the process, and we want to thank this community for your engagement along the way.
8-
9-
In the spirit of forward momentum, we will be releasing a new simulation platform in the coming year and subsequently archiving the original 2017 AirSim. Users will still have access to the original AirSim code beyond that point, but no further updates will be made, effective immediately. Instead, we will focus our efforts on a new product, Microsoft Project AirSim, to meet the growing needs of the aerospace industry. Project AirSim will provide an end-to-end platform for safely developing and testing aerial autonomy through simulation. Users will benefit from the safety, code review, testing, advanced simulation, and AI capabilities that are uniquely available in a commercial product. As we get closer to the release of Project AirSim, there will be learning tools and features available to help you migrate to the new platform and to guide you through the product. To learn more about building aerial autonomy with the new Project AirSim, visit [https://aka.ms/projectairsim](https://aka.ms/projectairsim).
10-
111
# Welcome to AirSim
122

133
AirSim is a simulator for drones, cars and more, built on [Unreal Engine](https://www.unrealengine.com/) (we now also have an experimental [Unity](https://unity3d.com/) release). It is open-source, cross platform, and supports software-in-the-loop simulation with popular flight controllers such as PX4 & ArduPilot and hardware-in-loop with PX4 for physically and visually realistic simulations. It is developed as an Unreal plugin that can simply be dropped into any Unreal environment. Similarly, we have an experimental release for a Unity plugin.
144

5+
AirSim was conceived and created by [Shital Shah](https://shital.com) with PX4 and hardware-in-loop code contributed by [Chris Lovett](https://lovettsoftware.com/).
6+
157
Our goal is to develop AirSim as a platform for AI research to experiment with deep learning, computer vision and reinforcement learning algorithms for autonomous vehicles. For this purpose, AirSim also exposes APIs to retrieve data and control vehicles in a platform independent way.
168

179
**Check out the quick 1.5 minute demo**
@@ -41,7 +33,7 @@ Cars in AirSim
4133
[![Build Status](https://github.com/microsoft/AirSim/actions/workflows/test_macos.yml/badge.svg)](https://github.com/microsoft/AirSim/actions/workflows/test_macos.yml)
4234
* [Build it](https://microsoft.github.io/AirSim/build_macos)
4335

44-
For more details, see the [use precompiled binaries](docs/use_precompiled.md) document.
36+
For more details, see the [use precompiled binaries](docs/use_precompiled.md) document.
4537

4638
## How to Use It
4739

@@ -132,11 +124,12 @@ We are maintaining a [list](https://microsoft.github.io/AirSim/who_is_using) of
132124

133125
Join our [GitHub Discussions group](https://github.com/microsoft/AirSim/discussions) to stay up to date or ask any questions.
134126

135-
We also have an AirSim group on [Facebook](https://www.facebook.com/groups/1225832467530667/).
127+
We also have an AirSim group on [Facebook](https://www.facebook.com/groups/1225832467530667/).
136128

137129

138130
## What's New
139131

132+
* [Project AirmSim](project_airsim.md)
140133
* [Cinematographic Camera](https://github.com/microsoft/AirSim/pull/3949)
141134
* [ROS2 wrapper](https://github.com/microsoft/AirSim/pull/3976)
142135
* [API to list all assets](https://github.com/microsoft/AirSim/pull/3940)
@@ -146,7 +139,7 @@ We also have an AirSim group on [Facebook](https://www.facebook.com/groups/12258
146139
* [Dynamically set object textures from existing UE material or texture PNG](https://github.com/microsoft/AirSim/pull/3992)
147140
* [Ability to spawn/destroy lights and control light parameters](https://github.com/microsoft/AirSim/pull/3991)
148141
* [Support for multiple drones in Unity](https://github.com/microsoft/AirSim/pull/3128)
149-
* [Control manual camera speed through the keyboard](https://github.com/microsoft/AirSim/pulls?page=6&q=is%3Apr+is%3Aclosed+sort%3Aupdated-desc#:~:text=1-,Control%20manual%20camera%20speed%20through%20the%20keyboard,-%233221%20by%20saihv)
142+
* [Control manual camera speed through the keyboard](https://github.com/microsoft/AirSim/pulls?page=6&q=is%3Apr+is%3Aclosed+sort%3Aupdated-desc#:~:text=1-,Control%20manual%20camera%20speed%20through%20the%20keyboard,-%233221%20by%20saihv)
150143

151144
For complete list of changes, view our [Changelog](docs/CHANGELOG.md)
152145

‎ct_airsim.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# AirSim Code Tour
2+
3+
This file is a quick orientation guide for this checkout of AirSim. It focuses on where the main subsystems live, how API calls move through the stack, and which files usually need to change for common work.
4+
5+
## High-Level Shape
6+
7+
AirSim is split into a platform-independent C++ core and simulator-specific front ends.
8+
9+
1. Client code calls the RPC API from Python, C++, C#, or another msgpack-rpc client.
10+
2. `AirLib` receives and models API calls, vehicles, sensors, physics, settings, and data structures.
11+
3. `Unreal/Plugins/AirSim` adapts the core to Unreal Engine actors, pawns, cameras, rendering, weather, and world objects.
12+
4. Vehicle-specific implementations connect the shared API surface to multirotors, cars, Computer Vision mode, PX4, ArduPilot, or SimpleFlight.
13+
14+
The docs that already cover the official architecture are:
15+
16+
- `docs/code_structure.md`
17+
- `docs/design.md`
18+
- `docs/dev_workflow.md`
19+
- `docs/adding_new_apis.md`
20+
21+
## Repository Map
22+
23+
| Path | Purpose |
24+
| --- | --- |
25+
| `AirLib/` | Platform-independent C++ library: APIs, physics, sensors, settings, safety, vehicles, RPC client/server code. |
26+
| `Unreal/Plugins/AirSim/` | Unreal Engine plugin implementation: sim modes, pawns, cameras, rendering, sensors, recording, weather, object control. |
27+
| `PythonClient/` | Python package and sample scripts for AirSim RPC APIs. Main client binding is `PythonClient/airsim/client.py`. |
28+
| `MavLinkCom/` | Standalone MAVLink communication library used by PX4 and ArduPilot integrations. |
29+
| `HelloDrone/`, `HelloCar/`, `DroneShell/`, `DroneServer/` | Native sample and utility programs. |
30+
| `ros/`, `ros2/` | ROS integration packages and wrappers. |
31+
| `Unity/` | Experimental Unity integration. |
32+
| `docs/` | MkDocs documentation source. Navigation is configured by `mkdocs.yml`. |
33+
| `AirLibUnitTests/` | Native unit test project for core AirLib behavior. |
34+
| `azure/`, `docker/`, `pipelines/` | Cloud, container, and CI support. |
35+
36+
## Core AirLib Areas
37+
38+
`AirLib` is the C++ core that should remain independent of Unreal-specific classes.
39+
40+
- API base classes: `AirLib/include/api/`
41+
- RPC server/client implementation: `AirLib/src/api/RpcLibServerBase.cpp`, `AirLib/src/api/RpcLibClientBase.cpp`
42+
- RPC adaptors and shared structs: `AirLib/include/api/RpcLibAdaptorsBase.hpp`, `AirLib/include/common/CommonStructs.hpp`
43+
- Settings parsing: `AirLib/include/common/AirSimSettings.hpp`
44+
- Physics: `AirLib/include/physics/`
45+
- Sensors: `AirLib/include/sensors/`
46+
- Multirotor models and APIs: `AirLib/include/vehicles/multirotor/`, `AirLib/src/vehicles/multirotor/`
47+
- Car APIs and firmware adapters: `AirLib/include/vehicles/car/`, `AirLib/src/vehicles/car/`
48+
- Safety and geofence logic: `AirLib/include/safety/`, `AirLib/src/safety/`
49+
50+
When adding fields to `settings.json`, start at `AirLib/include/common/AirSimSettings.hpp`.
51+
52+
## Unreal Plugin Areas
53+
54+
`Unreal/Plugins/AirSim/Source` is the Unreal-facing layer.
55+
56+
- Plugin module and game mode: `AirSim.cpp`, `AirSim.h`, `AirSimGameMode.cpp`
57+
- Base sim-mode lifecycle: `SimMode/SimModeBase.*`, `SimMode/SimModeWorldBase.*`
58+
- Vehicle modes:
59+
- Multirotor: `Vehicles/Multirotor/`
60+
- Car: `Vehicles/Car/`
61+
- Computer Vision mode: `Vehicles/ComputerVision/`
62+
- Environment and world APIs: `WorldSimApi.*`
63+
- Camera and image capture: `PIPCamera.*`, `UnrealImageCapture.*`, `RenderRequest.*`
64+
- Sensor adapters backed by Unreal scene data: `UnrealSensors/`
65+
- Recording: `Recording/`
66+
- Weather: `Weather/`
67+
- Common Unreal helpers: `AirBlueprintLib.*`, `NedTransform.*`
68+
69+
Most environment-only APIs eventually land in `WorldSimApi.cpp`. Most camera behavior eventually lands in `PIPCamera.cpp`, `UnrealImageCapture.cpp`, or `RenderRequest.cpp`.
70+
71+
## RPC Call Flow
72+
73+
For a typical Python API call:
74+
75+
1. `PythonClient/airsim/client.py` exposes a method and calls `self.client.call(...)`.
76+
2. `AirLib/src/api/RpcLibServerBase.cpp` binds that RPC method name to a C++ lambda.
77+
3. The lambda delegates to a vehicle API or `WorldSimApiBase`.
78+
4. Unreal implementations in `Unreal/Plugins/AirSim/Source` perform the simulator work.
79+
5. Result structs are converted through RPC adaptor types, then returned to the client.
80+
81+
For C++ clients, the public methods are declared in `AirLib/include/api/RpcLibClientBase.hpp` and implemented in `AirLib/src/api/RpcLibClientBase.cpp`.
82+
83+
Vehicle-specific RPC surfaces extend this pattern:
84+
85+
- Multirotor RPC: `AirLib/include/vehicles/multirotor/api/`, `AirLib/src/vehicles/multirotor/api/`
86+
- Car RPC: `AirLib/include/vehicles/car/api/`, `AirLib/src/vehicles/car/api/`
87+
88+
## Adding or Changing an API
89+
90+
Use `docs/adding_new_apis.md` for the full upstream checklist. The usual file set is:
91+
92+
1. Implement core behavior in the relevant AirLib or Unreal class.
93+
2. Add or update an abstract method if the call belongs on `WorldSimApiBase` or a vehicle API base.
94+
3. Bind the RPC method in `RpcLibServerBase.cpp` or the vehicle-specific RPC server.
95+
4. Add the C++ client wrapper in `RpcLibClientBase.hpp` and `RpcLibClientBase.cpp`.
96+
5. Add Python bindings in `PythonClient/airsim/client.py`.
97+
6. Add or update msgpack adaptor structs if the API returns a new structured type.
98+
7. Add docs and an example script when the API is user-facing.
99+
100+
If the API is vehicle-control-specific, check the multirotor or car API base classes first. If it changes the scene, cameras, weather, objects, textures, or levels, check `WorldSimApi.*` first.
101+
102+
## CinemAirSim Notes
103+
104+
This checkout includes CinemAirSim camera extensions marked with `//CinemAirSim`.
105+
106+
Important files:
107+
108+
- `Unreal/Plugins/AirSim/Source/PIPCamera.h`
109+
- `Unreal/Plugins/AirSim/Source/PIPCamera.cpp`
110+
- `Unreal/Plugins/AirSim/Source/WorldSimApi.h`
111+
- `Unreal/Plugins/AirSim/Source/WorldSimApi.cpp`
112+
- `AirLib/include/api/WorldSimApiBase.hpp`
113+
- `AirLib/include/api/RpcLibClientBase.hpp`
114+
- `AirLib/src/api/RpcLibClientBase.cpp`
115+
- `AirLib/src/api/RpcLibServerBase.cpp`
116+
- `PythonClient/airsim/client.py`
117+
118+
The main change is that `APIPCamera` derives from `ACineCameraActor` and uses `UCineCameraComponent` for lens, filmback, focal length, manual focus, focus distance, aperture, focus plane, and current field-of-view controls. If you touch these APIs, keep the declarations, RPC binding names, C++ client methods, Unreal implementation, and Python wrapper in sync.
119+
120+
## Build and Local Workflow
121+
122+
Windows is the most mature development path for this Unreal-based repo.
123+
124+
- Build AirSim plugin from the repo root: `build.cmd`
125+
- Linux build path: `setup.sh`, then `build.sh`
126+
- Clean/rebuild helpers: `clean.cmd`, `clean_rebuild.bat`, `clean.sh`, `clean_rebuild.sh`
127+
- Documentation build helpers: `build_docs.bat`, `build_docs.sh`
128+
129+
For Unreal plugin development, the documented workflow is:
130+
131+
1. Build the plugin from the AirSim repo root.
132+
2. Deploy `Unreal/Plugins` into an Unreal environment such as Blocks.
133+
3. Regenerate project files for the Unreal project.
134+
4. Build and run from Visual Studio.
135+
136+
See `docs/dev_workflow.md` and `docs/unreal_blocks.md` for details.
137+
138+
## Testing Touchpoints
139+
140+
- Native core tests: `AirLibUnitTests/`
141+
- Python smoke examples:
142+
- `PythonClient/multirotor/hello_drone.py`
143+
- `PythonClient/car/hello_car.py`
144+
- `PythonClient/computer_vision/cv_mode.py`
145+
- Camera/image API examples:
146+
- `PythonClient/computer_vision/external_camera.py`
147+
- `PythonClient/computer_vision/fov_change.py`
148+
- `PythonClient/multirotor/gimbal.py`
149+
150+
When testing Python changes from source, scripts usually import local package paths through `setup_path.py` so they use the checkout version instead of an installed PyPI package.
151+
152+
## Good Starting Points
153+
154+
- Understanding settings: `AirLib/include/common/AirSimSettings.hpp`
155+
- Understanding world APIs: `AirLib/include/api/WorldSimApiBase.hpp`, `Unreal/Plugins/AirSim/Source/WorldSimApi.cpp`
156+
- Understanding RPC exposure: `AirLib/src/api/RpcLibServerBase.cpp`
157+
- Understanding client wrappers: `AirLib/src/api/RpcLibClientBase.cpp`, `PythonClient/airsim/client.py`
158+
- Understanding cameras: `Unreal/Plugins/AirSim/Source/PIPCamera.cpp`, `Unreal/Plugins/AirSim/Source/UnrealImageCapture.cpp`
159+
- Understanding simulation modes: `Unreal/Plugins/AirSim/Source/SimMode/`
160+
- Understanding multirotor behavior: `AirLib/include/vehicles/multirotor/`, `Unreal/Plugins/AirSim/Source/Vehicles/Multirotor/`
161+
- Understanding car behavior: `AirLib/include/vehicles/car/`, `Unreal/Plugins/AirSim/Source/Vehicles/Car/`

‎project_airsim.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Project AirSim announcement
2+
3+
Microsoft and IAMAI collaborated to advance high-fidelity autonomy simulations through Project AirSim—the evolution of AirSim— released under the MIT license as part of a DARPA-supported initiative. IAMAI is proud to have contributed to these efforts and has published its version of the Project AirSim repository at [github.com/iamaisim/ProjectAirSim](https://github.com/iamaisim/ProjectAirSim).
4+
5+
## AirSim announcement: This repository will be archived in the coming year
6+
7+
In 2017 Microsoft Research created AirSim as a simulation platform for AI research and experimentation. Over the span of five years, this research project has served its purpose—and gained a lot of ground—as a common way to share research code and test new ideas around aerial AI development and simulation. Additionally, time has yielded advancements in the way we apply technology to the real world, particularly through aerial mobility and autonomous systems. For example, drone delivery is no longer a sci-fi storyline—it’s a business reality, which means there are new needs to be met. We’ve learned a lot in the process, and we want to thank this community for your engagement along the way.
8+
9+
In the spirit of forward momentum, we will be releasing a new simulation platform in the coming year and subsequently archiving the original 2017 AirSim. Users will still have access to the original AirSim code beyond that point, but no further updates will be made, effective immediately. Instead, we will focus our efforts on a new product, Microsoft Project AirSim, to meet the growing needs of the aerospace industry. Project AirSim will provide an end-to-end platform for safely developing and testing aerial autonomy through simulation. Users will benefit from the safety, code review, testing, advanced simulation, and AI capabilities that are uniquely available in a commercial product. As we get closer to the release of Project AirSim, there will be learning tools and features available to help you migrate to the new platform and to guide you through the product. To learn more about building aerial autonomy with the new Project AirSim, visit [https://aka.ms/projectairsim](https://aka.ms/projectairsim).

0 commit comments

Comments
 (0)