Navigation Terminology

This page explains the navigation terms you meet when operating PX4, reading logs or tuning, such as heading, course, track, bearing, cross-track error and drift angle.

PX4 uses the official definitions of these terms from aviation and marine navigation, with one deliberate exception: Course.

For the official definitions quoted with their sources, how conflicting definitions are resolved, ground vehicle terms, and where PX4 represents things differently, see Navigation Terminology (Advanced).

Summary

Heading is the direction the vehicle points, course setpoint is the direction it should move over the ground, course is the direction it actually moves, and bearing is the direction to something, such as the current waypoint. Similarly, desired track and track are the paths the vehicle should follow and actually follows.

Term	Official meaning	Example in PX4
Heading	Direction in which the body x-axis of the vehicle points.	vehicle_local_position.heading
Course	Actual direction of motion over the ground.	sensor_gnss.course
Course setpoint	Intended direction of motion over the ground.	fixed_wing_lateral_setpoint.course
Track	Actual path of the vehicle over the ground.	Path plotted from a log
Desired track	Intended path over the ground, such as between two waypoints.	Line from previous to current waypoint
Bearing	Direction from one point to another.	pure_pursuit_status.bearing_to_waypoint
Cross-track error	Perpendicular distance from the desired track, and side.	pure_pursuit_status.crosstrack_error
Drift angle	Angle between heading and track.	—

Heading, course setpoint, course and bearing can all differ: in wind the vehicle points away from where it moves, and off the desired track it should move back towards the track, not straight at the waypoint. The diagram below shows each term.

Overview figure: vehicle seen from above.

Directions and Frames

All directions on this page are measured clockwise from true north: north is 0°, east is 90°, south is 180° and west is 270°. QGroundControl shows them in degrees from 0° to 360°, and MAVLink navigation fields usually in centidegrees (for example GLOBAL_POSITION_INT.hdg, 0 to 35999). Internally, PX4 uses radians, usually from $-\pi$ to $\pi$ (west is $-\pi /2$), which matters when you read logs.

PX4 uses four main frames (see Frames and Reference Directions for details):

• Global (WGS 84): Latitude, longitude and altitude, for example in vehicle_global_position.
• Local tangent-plane (NED): North, east, down from a fixed origin where the estimator started; the positions in vehicle_local_position.
• Local navigation (NED): North, east, down at the vehicle; velocities and attitude are relative to it.
• Body (FRD): Forward, right, down, fixed to the vehicle; the heading is the direction of its forward axis.

A compass measures magnetic north, which differs from true north by the magnetic declination. The estimator corrects for this automatically, using the World Magnetic Model or EKF2_MAG_DECL depending on EKF2_DECL_TYPE.

Terms

Heading

The heading is where the x-axis (nose, bow or front) of the vehicle points. It says nothing about the direction in which the vehicle moves: a multicopter can fly sideways, a plane angles into a crosswind, and a boat is pushed off by wind and current.

PX4 uses heading and yaw (the yaw angle of the vehicle attitude) as synonyms: vehicle_local_position.heading is the Euler yaw angle, and heading setpoints are named yaw. The yaw angle is the direction of the body x-axis projected onto the horizontal plane, so the two only differ when the x-axis points (nearly) straight up or down, where the heading is undefined. Note that yaw also names the rotation about the vertical axis (yaw rate, yaw moment), which is not a direction.

PX4 represents the heading using:

• vehicle_local_position.heading (estimate).
• trajectory_setpoint.yaw and rover_attitude_setpoint.yaw_setpoint (setpoints).
• MAVLink GLOBAL_POSITION_INT.hdg and VFR_HUD.heading.

Course

The course is the direction the vehicle actually moves over the ground: the direction of its ground velocity. It is also called course over ground (COG) in marine navigation, and it is what a GNSS receiver reports as "course" and what avionics show as TRK (track). It is undefined when the vehicle is stationary, and noisy at low speed. For a rover that drives without wheel slip, the course equals the heading when driving forwards, and the heading plus 180° when reversing.

PX4 represents the course using:

• sensor_gnss.course ("Course over ground, not heading").
• MAVLink GPS_RAW_INT.cog.

Course Setpoint

The course setpoint is the direction the vehicle should move over the ground. PX4's path-following guidance calculates it from the desired track: on the track it points along it, and off the track it points back towards it, so that the vehicle rejoins the track ahead. The actual course almost always differs from the course setpoint, often substantially.

PX4 represents the course setpoint using:

• position_setpoint.course (course to hold, set by the navigator).
• fixed_wing_lateral_setpoint.course (course commanded by the fixed-wing guidance).

PX4 differs from aviation and marine navigation

In aviation and marine navigation, bare course means the intended direction, and the actual direction is the course over ground or track angle. PX4 instead uses course for the measured or estimated direction and course setpoint for the intended one, like heading and heading setpoint. Keep this in mind when you read aviation or marine sources, for example the FAA wind correction angle, which applies to the course setpoint in PX4 terms. See Course Is the Actual Direction for the reasoning.

Track and Desired Track

• Track: The actual path the vehicle traced over the ground, such as the path plotted from a log. Its direction at any point is the course.
• Desired track: The intended path over the ground, which the vehicle tries to follow. This is usually the line between two waypoints, but it can also be a line along a course setpoint the vehicle holds.

INFO

In marine navigation, bare "track" means the intended path. To avoid confusion, PX4 always writes desired track for the intended path.

Bearing

A bearing is the direction from one point to another, for example from the vehicle to the current waypoint. It depends only on the two positions, not on where the vehicle points or moves.

PX4 represents the bearing using:

• pure_pursuit_status.bearing_to_waypoint.

Cross-Track Error

The cross-track error (XTE) is how far the vehicle is off the desired track, measured perpendicular to it, and on which side.

In PX4, the cross-track error is positive when the vehicle is to the right of the desired track, and negative when it is to the left, looking in the direction of travel.

PX4 represents the cross-track error using:

• pure_pursuit_status.crosstrack_error (rovers).
• fixed_wing_lateral_guidance_status.signed_track_error (fixed-wing).

Drift Angle

The drift angle is the difference between where the vehicle points (heading) and where it moves (course). Wind causes it for aircraft, wind and current for boats, and wheel slip for rovers. Multicopters and mecanum rovers can also move sideways on purpose.

Rover and vehicle dynamics material calls this angle the vehicle sideslip angle, while for aircraft the sideslip angle is measured against the airflow, not the ground. In marine navigation, bare drift is the speed of the current, which is why PX4 always writes drift angle.

Airspeed and Ground Speed

Ground speed (called speed over ground, SOG, in marine navigation) is the speed over the ground, in the direction of the course. Airspeed is the speed through the air (see Airspeed in PX4 for indicated, calibrated and true airspeed). The two differ by the wind.

Wind Direction

Weather reports, aviation and marine navigation give the wind direction as the direction it blows from: a wind "from 90°" blows from the east towards the west.

PX4 does not use this convention. PX4 wind estimates and the wind fields it sends over MAVLink are velocity vectors of the air relative to the ground, which point where the air moves to. A wind from the north therefore has a negative windspeed_north in PX4.

PX4 represents the wind using:

• wind.windspeed_north and wind.windspeed_east (estimate, NED).
• MAVLink WIND_COV.wind_x and WIND_COV.wind_y (same sign convention as wind).

Wind Triangle

Heading and course differ because the vehicle moves through air (or water) that itself moves over the ground:

$${\mathbf{v}}_{ground}={\mathbf{v}}_{air}+{\mathbf{v}}_{wind}$$

• The direction of ${\mathbf{v}}_{ground}$ is the course, and its magnitude is the ground speed.
• For a fixed-wing aircraft, ${\mathbf{v}}_{air}$ points along the heading, and its magnitude is the airspeed.
• The angle between the heading and ${\mathbf{v}}_{ground}$ is the drift angle.

Names That Don't Mean What They Say

Some names you see when tuning, flying or reading logs predate this terminology and don't match it:

• "Bearing" in Rover Velocity Tuning and Rover Position Tuning means the course setpoint.
• MAVLink NAV_CONTROLLER_OUTPUT.nav_bearing and NAV_CONTROLLER_OUTPUT.xtrack_error are always 0 in current PX4.
• The ADS-B traffic "heading" (transponder_report.heading, MAVLink ADSB_VEHICLE.heading) is the other aircraft's course.

The code-level names that deviate are listed in Field Names That Deviate.

Further Information

Navigation Terminology (Advanced) covers:

• The official definitions of each term, quoted from the aviation, marine and ground vehicle sources, and the rule PX4 uses when they disagree.
• The reference frames in detail (ECEF/WGS 84, local tangent-plane and local navigation NED, FRD, along-track/cross-track), north references and z-up conventions such as ROS and ISO 8855.
• Why PX4 uses course for the actual direction, unlike aviation and marine navigation.
• Ground vehicle terms (yaw, course and sideslip angle), and why sideslip means different things for planes and rovers.
• Where PX4 represents things differently from the official definitions, and existing field names that deviate.
• Guidelines for contributors, and terms PX4 does not use yet.