Magnetic Heading⚠ unverified
Aerospace / Navigation · Compute the magnetic heading with declination correction
Parameters
| Input | Symbol | Unit | Default | Description |
|---|---|---|---|---|
| mag_x | magx | T | 1.0 | Magnetometer reading along the x-axis, in teslas (T) or any consistent unit |
| mag_y | magy | T | 1.0 | Magnetometer reading along the y-axis, in teslas (T) or any consistent unit |
| declination | declination | — | 0.0 | Magnetic declination correction, in degrees. Default is 0.0 |
| Output | Symbol | Unit | Description |
|---|---|---|---|
| result | heading | — | Heading, in degrees, normalised to [0, 360) |
The science & history
Understanding the Parameters
-
How a magnetic compass finds direction — the Earth is a giant, slightly tilted bar magnet. Its field has a horizontal component that points toward magnetic north everywhere (away from the poles). A magnetometer measures the field's components in the aircraft's own axes; the angle of the horizontal field relative to the nose is the heading. $\operatorname{atan2}(B_y, B_x)$ extracts that angle over the full $360^\circ$.
-
Declination $\delta$ (magnetic variation) — magnetic north and true (geographic) north do not coincide, and their angular difference — the declination — varies with location and slowly drifts over years. It can exceed $20^\circ$ in parts of the world. Adding $\delta$ converts a magnetic heading to a true heading (the one used with charts and great-circle bearings). East declination is positive by convention. This is why aeronautical charts print isogonic (equal-declination) lines and why the value must be updated periodically.
-
Magnetic vs true heading — the naming subtlety — $\operatorname{atan2}(B_y,B_x)$ alone is the magnetic heading; adding $\delta$ makes it true. The calculator is named "magnetic heading" but, with declination applied, returns the true heading. (Pilots more often go the other way — take a desired true track from the chart and subtract declination to get the magnetic heading to fly.)
-
The level-compass limitation — this uses only the two horizontal field components, which is valid only when the magnetometer is level. In a bank or climb, the sensor tilts, the strong vertical component of the Earth's field leaks into the horizontal axes, and the heading swings wildly — the classic "compass turning error." Real attitude-and-heading reference systems (AHRS) add a third magnetometer axis plus pitch/roll from gyros/accelerometers to tilt-compensate; this simple 2-axis formula does not.
-
Deviation vs declination — beyond declination (Earth's field vs true north), a real compass also suffers deviation from the aircraft's own magnetic fields (currents, ferrous structure). This formula corrects only declination; deviation is handled separately by a compass swing / calibration card.
Derivation (Approaching a Proof)
Model the local Earth field, in the aircraft's horizontal body frame, as a horizontal vector of magnitude $B_h$ pointing toward magnetic north. If the aircraft's nose (body x-axis) is rotated by heading $\psi_m$ (measured clockwise from magnetic north) relative to that field, the field's components sensed along the body axes are:
$$B_x = B_h\cos\psi_m, \qquad B_y = -B_h\sin\psi_m$$
(the exact signs depend on the axis convention; the implementation uses $\operatorname{atan2}(B_y,B_x)$ directly). The heading is recovered by taking the four-quadrant arctangent of the two components, which cancels the unknown magnitude $B_h$:
$$\psi_m = \operatorname{atan2}(B_y, B_x).$$
Using $\operatorname{atan2}$ (not $\arctan$) is essential so the heading is correct in all four quadrants and well-defined when a component is zero — a compass must read all $360^\circ$.
Finally, convert magnetic heading to true by adding the local declination and normalising:
$$\psi = \big(\operatorname{atan2}(B_y, B_x) + \delta + 360^\circ\big) \bmod 360^\circ. \qquad\blacksquare$$
The $\bmod 360^\circ$ (with the $+360^\circ$ to avoid negative results) wraps the answer into the standard $[0^\circ,360^\circ)$ compass range.
Dimensional check. $B_x, B_y$ share units (tesla), so their ratio inside $\operatorname{atan2}$ is dimensionless and the result is an angle; adding the declination angle $\delta$ keeps it an angle ✓ — the field magnitude cancels, which is why "any consistent unit" works for $B_x,B_y$.
History and Development
-
The oldest instrument. The magnetic compass (Chinese origin, adopted for European navigation by the 12th century) is the ancestor of this calculation — a freely-pivoting magnet aligning with the horizontal field. The digital magnetometer does the same measurement electronically and computes the angle instead of reading a card.
-
Declination, known for centuries. That the compass does not point to true north was documented by the Middle Ages; Edmond Halley produced the first global declination charts (isogonic lines) around 1701. Modern values come from the World Magnetic Model (WMM), updated every five years because the field drifts — the north magnetic pole has been migrating across the Arctic at tens of km per year.
-
From wet compass to AHRS. Aircraft carried a fluid-damped "whiskey compass" (subject to turning and acceleration errors), then gyro-stabilised directional gyros, and now solid-state AHRS that fuse three-axis magnetometers with gyros and accelerometers for tilt-compensated, drift-free heading. This 2-axis level formula is the conceptual core, before the tilt compensation and sensor fusion that make it usable in manoeuvres.
Related Concepts: Initial Heading, Great-Circle Distance, Cross Track Error, Gps Dilution Of Precision, Time To Go
Notes: $\operatorname{atan2}(B_y,B_x)$ gives the magnetic heading; adding declination $\delta$ makes it
true (so the output, despite the name, is true heading). Declination and output are degrees (both
mislabelled dimensionless); east declination positive. 2-axis / level only — no tilt compensation, so
bank/pitch corrupt it (real AHRS use 3 axes + gyros/accelerometers). Corrects declination, not aircraft
deviation (compass swing handles that). Field magnitude cancels. Defaults ⇒ $45^\circ$.