About Live Compass

The Project

Live Compass began with a simple frustration: most compass apps are bloated, ad-heavy, and phone home with your location data. We wanted a compass that respected your privacy as much as your need for accurate heading information. The result is a fully client-side navigation instrument that runs entirely in your browser — no accounts, no tracking, no servers, no data collection.

The project draws on a rich tradition of navigation instrumentation. From the magnetic compasses that guided explorers across uncharted oceans to the sextants that enabled celestial navigation, humans have always built tools to answer a fundamental question: which way am I going? Live Compass continues that tradition using the sensors already in your pocket.

Celestial Navigation Mathematics

At the heart of Live Compass is the SunCalc library, created by Vladimir Agafonkin and released under the MIT License. SunCalc provides highly accurate calculations of sun and moon positions, phases, and times for any location on Earth and any date. The library implements astronomical algorithms based on the formulas published at aa.quae.nl, which themselves derive from Jean Meeus's authoritative Astronomical Algorithms (Willmann-Bell, 1998).

The core calculations work as follows. First, the Julian Day number is computed from the current date. From this, the solar mean anomaly and ecliptic longitude are derived using standard perturbation series. The sun's right ascension and declination are then calculated from its ecliptic coordinates, accounting for the obliquity of the ecliptic (approximately 23.4397 degrees). The hour angle — the angular distance between the observer's meridian and the sun's position — is computed from the local sidereal time. Finally, the sun's azimuth and altitude are obtained by transforming from equatorial to horizontal coordinates using spherical trigonometry.

For the moon, SunCalc uses a similar approach with additional perturbation terms to account for the moon's more complex orbital mechanics. The library calculates the moon's ecliptic longitude, latitude, and distance, then transforms these to equatorial and horizontal coordinates. Moon rise and set times are found by scanning the moon's altitude at two-hour intervals and fitting a quadratic curve to detect zero crossings.

The distance and bearing between two points on Earth are computed using the Haversine formula and the initial bearing formula. The Haversine formula calculates the great-circle distance between two points on a sphere given their latitudes and longitudes, using the formula: a = sin²(Δφ/2) + cos(φ₁) · cos(φ₂) · sin²(Δλ/2), where φ is latitude, λ is longitude, and the distance is d = 2R · atan2(√a, √(1−a)). The initial bearing is calculated using: θ = atan2(sin(Δλ) · cos(φ₂), cos(φ₁) · sin(φ₂) − sin(φ₁) · cos(φ₂) · cos(Δλ)).

Hardware Sensor API Integration

Live Compass leverages three key web APIs to access device hardware sensors. The Device Orientation API provides compass heading (alpha), pitch (beta), and roll (gamma) data from the device's magnetometer and accelerometer. On iOS 13 and later, the API requires explicit user permission via DeviceOrientationEvent.requestPermission(), which Live Compass handles gracefully with a clear enable button. The DeviceOrientationAbsoluteEvent interface is used when available to obtain absolute orientation relative to the Earth's coordinate frame rather than the device's initial orientation.

The Geolocation API provides the user's position, altitude, accuracy, and speed. Live Compass uses navigator.geolocation.watchPosition() with high accuracy enabled to continuously update the user's location. This position data feeds directly into the SunCalc calculations to provide location-specific celestial information.

The Visual Viewport API is used to detect and correct unwanted zoom behavior on mobile devices, particularly iOS Safari. The application monitors viewport scale changes and resets the zoom level to 1 when the browser attempts to zoom in response to input focus or touch gestures, ensuring the compass dial remains stable and readable.

Privacy by Design

Every calculation in Live Compass runs locally on your device. When you open the page, your browser downloads the HTML, CSS, and JavaScript files. After that, the application has no network dependency. Your GPS coordinates, compass heading, and tilt data are processed in memory and never transmitted anywhere. The only data persisted is your theme preference (dark or light), stored in localStorage under the key livecompass-theme. This data never leaves your device.

The only external requests made by the Site are for Google Fonts (Cormorant Garamond and Inter typefaces) and Google AdSense (if ads are displayed). These requests are subject to Google's privacy policy. No analytics, tracking, or fingerprinting scripts are present on the Site.

Technology Stack

Live Compass is built with vanilla HTML, CSS, and JavaScript — no frameworks, no build tools, no dependencies beyond the vendored SunCalc library. The user interface uses CSS custom properties for theming, with a dark brass-and-cyberpunk aesthetic inspired by vintage nautical instruments. The typography pairs Cormorant Garamond (a serif typeface with historical roots in sixteenth-century French printing) with Inter (a modern sans-serif designed for screen readability). The compass dial, tilt gauge, and celestial markers are rendered as inline SVG, scaled responsively using aspect-ratio and viewBox attributes.

The application is fully offline-capable. Once loaded, it can be added to your home screen as a progressive web app and used without an internet connection. All features degrade gracefully on devices without sensors — the compass falls back to a fixed north-up display, and celestial calculations can be performed with manually entered coordinates.

Open Source

Live Compass is open source. The source code is available on GitHub. We welcome contributions, bug reports, and feature requests. The SunCalc library is used under the MIT License, and the original copyright notice is preserved in the source code.

Contact

Questions, feedback, or bug reports? Visit our contact page or email us at [email protected].