Aircraft

SWITCH TO API

Description

An Aircraft is a Vehicle that can travel through the full three-dimensional local coordinate frame. Its nose heading is independent of its track and flight-path angle, and its altitude, climb, and turn can be limited. Motion is kinematic. The commanded speed is applied in the vehicle’s local east-north-up frame.

---

Example Use Cases

• Airborne Platforms: Represents aircraft that climb, descend, and turn above a planetary surface.
• Flight-Path Tracking: Simulates a commanded track and flight-path angle that are independent of the nose heading.

---

Module Implementation

The aircraft extends Vehicle and uses the same directed motion and waypoint routes. It adds a flight command, a turn-rate limit, a climb-rate limit, and an altitude floor. By default, Minimum Altitude is 0 m. Max Climb Rate and Max Turn Rate both default to 0, which disables those limits.

Position is integrated in the origin frame, where $X$ is east, $Y$ is north, and $Z$ is up. Latitude, longitude, and altitude are then updated by the parent vehicle.

Travel Direction

Track $\psi$ is the commanded horizontal direction, clockwise from true north. Flight Path Angle $\gamma$ is the commanded angle of the velocity above the local horizontal. Positive $\gamma$ climbs and negative $\gamma$ descends. $\gamma$ is clamped to $[-90^{\circ },90^{\circ }]$, and $\psi$ is wrapped to $[0^{\circ },360^{\circ })$.

Heading is commanded on its own. Setting heading motion is the one case that also sets the flight command: it selects level flight ($\gamma =0$) with $\psi$ equal to the supplied heading, and it clears any waypoint route.

The commanded unit direction and velocity are

$$\hat{\mathbf{u}}=\left[\begin{array}{c}\cos \gamma \sin \psi \\ \cos \gamma \cos \psi \\ \sin \gamma \end{array}\right],\mathbf{v}=V\hat{\mathbf{u}}$$

where $V$ is the commanded Speed [m/s]. The components are east, north, and up.

On a waypoint route, the desired direction points at the next waypoint and is still subject to the limits below. The route leaves Heading, Track, and Flight Path Angle on the last values written to them.

The flown track is the direction of the horizontal velocity. With east and north components $v_E$ and $v_N$,

$$V_g=\sqrt{v_E^2+v_N^2}$$ $${\psi }_{\mathrm{flown}}=atan2(v_E,v_N)$$

wrapped to $[0^{\circ },360^{\circ })$. When the ground speed is negligible, the flown track remains the commanded track.

Turn Rate

Max Turn Rate $\omega$ [deg/s] limits how fast the nose heading and the travel direction can change. A value of 0 disables the limit. Heading commands are then applied immediately, and the travel direction can reach its target in one step.

Otherwise the nose heading slews toward its command by at most $\omega \Delta t$ degrees per step, along the shortest arc in $[-180^{\circ },180^{\circ }]$:

$$\Delta {\psi }_h={\mathrm{wrap}}_{[-180,180]}({\psi }_c-{\psi }_h)$$ $${\psi }_h\leftarrow {\mathrm{wrap}}_{[0,360)}\left({\psi }_h+\mathrm{clamp}(\Delta {\psi }_h,-\omega \Delta t,\omega \Delta t)\right)$$

where ${\psi }_h$ is the current nose heading and ${\psi }_c$ is the commanded heading.

The travel direction rotates toward the desired direction at the same rate, using spherical linear interpolation. If $\theta$ is the angle between the current direction $\hat{\mathbf{c}}$ and the desired direction $\hat{\mathbf{d}}$, and ${\theta }_{\max }=\omega \Delta t$ in radians, then

$$\hat{\mathbf{u}}=\{\begin{array}{ll}\hat{\mathbf{d}}& \text{if }\theta \le {\theta }_{\max }\\ \frac{\sin ((1-s)\theta )}{\sin \theta }\hat{\mathbf{c}}+\frac{\sin (s\theta )}{\sin \theta }\hat{\mathbf{d}}& \text{if }\theta >{\theta }_{\max }\end{array}$$

where $s={\theta }_{\max }/\theta$. While the aircraft is stopped, $\hat{\mathbf{c}}$ is the horizontal direction of the nose heading. While it is moving, $\hat{\mathbf{c}}$ is the current velocity direction.

Climb Rate

When Max Climb Rate $R_c$ is greater than zero, only the vertical speed is limited:

$$v_z\leftarrow \mathrm{clamp}(v_z,-R_c,R_c)$$

The east and north components stay at the values from the commanded direction, $V\cos \gamma$ once the direction has reached the command. A capped climb or descent therefore flies a shallower path than $\gamma$, at a speed below $V$.

Altitude Floor

Minimum Altitude $h_{\min }$ is a hard floor.

Waypoint altitudes below the floor are raised before the leg is flown:

$$z_{\mathrm{target}}\leftarrow \max \left(z_{\mathrm{target}},z+h_{\min }-h\right)$$

where $z$ is the current up coordinate and $h$ is the current geodetic altitude. On a waypoint leg at or below the floor, a downward component of the aim direction is removed and the direction is renormalized. A pure descent stops. A leg that still has a horizontal component continues level.

In every mode, downward speed is removed at the floor. If a step still finishes below $h_{\min }$, the aircraft is placed back on the floor:

$$z\leftarrow z+(h_{\min }-h),v_z\leftarrow \max (v_z,0)$$

---

Assumptions/Limitations

• The model is kinematic. Lift, drag, thrust, stall, wind, and fuel use are outside this model.
• Max Turn Rate is a shared limit on nose heading and velocity direction. Bank angle, load factor, and speed do not enter the turn.
• Max Climb Rate limits vertical speed alone. Horizontal speed is held, so the flown speed falls while the cap is active. There is no maximum altitude.
• The altitude floor is a geometric stop. Terrain, landing gear, and bounce are outside this model.
• A waypoint route steers the velocity. Heading, Track, and Flight Path Angle stay on their own commands.
• While the aircraft is stopped, turn limiting of the velocity direction starts from the nose heading.
• A Max Climb Rate or Max Turn Rate of zero disables that limit.
• Flight-path commands outside $\pm 90^{\circ }$ are clamped to that range.