Cosys-AirSim Documentation

Cosys-AirSim is an open-source, cross-platform simulator for drones, cars, and other vehicles, built on Unreal Engine. It is designed for physically and visually realistic simulations and supports hardware-in-the-loop with popular flight controllers like PX4. It is implemented as an Unreal plugin that can be integrated into any Unreal environment.

This specific repository is a fork of the original Microsoft AirSim, modified by Cosys-Lab to support advanced research features such as multi-layer annotation, GPU-accelerated LiDAR, and enhanced sensor models.

Cosys-AirSim provides several dynamic blueprint features to create random but deterministic environmental changes. These features include:

• Dynamic AI humans: Walking between waypoints.
• Dynamic spawning of stacked goods: Such as pallets.
• Dynamic static objects spawning: Can be configured to always spawn the same object or pick from a set of options.
• Small dynamic changes: Such as random open doors.
• Animate objects: Modular conveyor belts and robotic arms.

All randomization is controllable via a seed, ensuring that you can recreate the exact same environmental setup for reproducible simulations.

The MavlinkMoCap application is a VC++ project generated via AppWizard. The project structure consists of the following key components:

• MavlinkMoCap.vcxproj: The main Visual C++ project file containing configuration, platform, and feature settings.
• MavlinkMoCap.vcxproj.filters: Defines how files are grouped within the IDE (e.g., grouping .cpp files under "Source Files").
• MavlinkMoCap.cpp: The primary source file containing the main application logic.
• StdAfx.h & StdAfx.cpp: Precompiled header (PCH) files used to accelerate build times.

Note for Developers: Look for // TODO: comments within the source code to identify areas intended for customization or additional implementation.

PFM (Portable FloatMap) is an image format that stores pixels as floating-point values. Unlike standard image formats (like PNG or JPEG) that are restricted to the 0-255 integer range, PFM allows for values outside this range. This makes it ideal for:

• HDR (High Dynamic Range) images
• Depth maps (where pixel values represent distance rather than color)

Viewing PFM files:

• Recommended: PfmPad
• Not Recommended: Maverick photo viewer (it may not display depth images correctly).

AirSim uses the NED (North-East-Down) coordinate system for all APIs, which differs from the internal Unreal Engine coordinate system.

NED Convention:

• +X: North
• +Y: East
• +Z: Down
• Units: SI units (meters).

Unreal Engine Convention (Internal):

• +Z: Up
• Units: Centimeters.

AirSim handles the conversion between these systems automatically. The vehicle's starting position is always (0, 0, 0) in the NED system. If you need to align the Unreal origin with the AirSim origin, set MoveWorldOrigin to true in your settings.json.

When accessing static meshes in Cosys-AirSim, each mesh is returned as a MeshPositionVertexBuffersResponse struct.

Key characteristics:

• Coordinate System: The position and orientation fields use the Unreal coordinate system. The vertices themselves are stored as global positions in the Unreal coordinate system, meaning they have already been transformed by the mesh's position and orientation.
• Mesh Type: The mesh is a Face-Vertex triangular mesh. Every triplet of indices in the indices vector corresponds to the indices of the vertices that form a single triangle/face.
• Data Layout: The vertices vector is a flat list of $N \times 3$ coordinates (x, y, z).

struct MeshPositionVertexBuffersResponse {
	Vector3r position;
	Quaternionr orientation;

	std::vector<float> vertices;
	std::vector<uint32_t> indices;
	std::string name;
};

simple_flight is AirSim's built-in, default flight controller. It is designed as a dependency-free, header-only C++11 library that can run both in simulation and on real hardware.

Key Characteristics:

• Zero Setup: It is used by default in AirSim; no additional configuration is required to start using it.
• Steppable Clock: By default, it uses a steppable clock that advances only when the simulator advances. This allows for consistent behavior even when the simulation is paused (e.g., during debugging).
• Control Hierarchy: It uses a cascade of PID controllers. The control flow is: Position PID $\rightarrow$ Velocity PID $\rightarrow$ Angle Level PID $\rightarrow$ Angle Rate PID $\rightarrow$ Actuator Signals.
• State Estimation: Currently, it uses ground truth data directly from the simulator for state estimation.

The airsim_ros_pkgs wrapper converts data from AirSim's internal formats to ROS standards.

Important: All coordinates and data are provided in the right-handed coordinate frame of the ROS standard. They are not in NED (North-East-Down), with the exception of geo points.