13.5 Section 13: Celestial & Environmental Data

Viewfinder compass with true north and sun bearing

Live camera heading, true-north correction, sun and moon bearing ticks, their full path arcs, the next event countdown, and a 24-hour time-scrub slider, all on the viewfinder.

Where to find it

Viewfinder top-right corner (badge), Composition grid picker Compass overlay (under Bubble level)

Summary

A floating compass badge in the top-right of the viewfinder shows where the camera is pointing in degrees and cardinal direction. Optional true-north correction uses the active ephemeris location to apply local magnetic declination. A yellow tick marks the sun's compass bearing on the dial, and a silver glyph marks the moon's bearing whenever the moon is above the horizon. An optional colour-segmented arc draws today's full sun trajectory around the rim, with a second silver arc tracing the moon's path across the sky, so the photographer can see where both the light and the moon have been and where they are going. An optional countdown badge under the dial shows the next celestial event. An optional time-scrub slider spans a full 24 hours centred on now, so dragging it walks the sun and moon ticks around the dial through the whole day and night, with a silver moon-altitude line and moonrise and moonset markers running along the timeline. The bearing is stamped onto every logged shot when stamping is on.

Tap to zoom — actual screenshot from the app

More views

How it works

Most director's finders skip the compass and assume you know which way the sun moves. This one builds it into the viewfinder so you can frame a shot, see where the camera is pointing, where the sun is sitting on that arc, and how much room you have before the light direction changes. Useful for location scouting, golden hour planning, and recording shot direction in the shot log so months later you can reconstruct what you shot from where, facing which way.

Turning it on

Open the Composition grid picker from the viewfinder toolbar (the small grid icon). Right under the Bubble level toggle you will find Compass overlay. Flip its master switch to put a small dial in the top-right corner of the viewfinder, then dial in the sub-toggles for true north, sun tick, dial vs pill, and shot-log stamping. Tap the dial on the viewfinder to switch between the full circular face and a compact numeric pill. Long-press the badge to reopen the picker without going through the toolbar.

Reading the dial

The red arrow at the top of the dial is the direction you are aiming. The red arrow at the top of this viewfinder dial points where the back camera is aimed, so as you frame a shot the dial shows the bearing of the shot itself, with the cardinal letters N E S W turning around it. Hold the phone upright the way you would to take a photo and the heading stays steady. (The full-screen Compass under Tools is a plain compass instead, meant to be read flat in your hand, so it follows the top edge of the phone the way an ordinary compass does.) The rotating ring carries the cardinal letters N / E / S / W and tick marks every 30 degrees. The numeric readout in the centre is the bearing in degrees plus the cardinal abbreviation. A small T or M after the cardinal tells you whether the reading is degrees true or degrees magnetic.

True north vs magnetic north

Magnetic north drifts up to 20 degrees away from true north depending on where on the planet you are. Leaving true-north correction on means the app uses your active Sun & Moon location to compute the local magnetic declination via the World Magnetic Model and adds it to the raw magnetometer reading. With no location set, the app silently falls back to magnetic so the badge still works.

The yellow sun tick

When the sun is above the horizon and a location is known, a small yellow dot is drawn on the dial at the sun's compass bearing. As you swing the camera, the dot rotates with the cardinal letters and the sun stays anchored to its true direction. Lining the camera up with the dot puts the sun in front of you, putting it on the opposite side of the dial puts the sun behind you. Toggle this off in Settings if you find it distracting.

Sun and moon path arcs

Turn on Sun and moon path arcs to draw today's full sun trajectory around the outer rim of the dial as small colour-coded dots: cool blue for blue hour, warm orange for golden hour, pale yellow for mid-day. A second arc, in silver, traces the moon's path just inside the sun's, showing only the part of its track that sits above the horizon. Past samples are dimmed; future samples are bright. The yellow live tick sits on the sun path and the silver glyph sits on the moon path. Useful for scouting a location at noon and seeing exactly where the sun will be at 5 pm, or where the moon will rise tonight, without leaving the viewfinder.

The moon

When a Sun and Moon location is known and the moon is above the horizon, a silver glyph marks its compass bearing on the dial, nested just inside the yellow sun tick so the two never blur together even at a new moon when they share a direction. Turn on the path arcs to add the moon's full above-horizon trajectory as a silver arc. The moon position uses a geocentric ephemeris accurate to a fraction of a degree for pointing, far finer than a phone compass can resolve. Scrub the timeline into the night and the silver glyph climbs and sets while the sun tick stays hidden below the horizon.

Next event countdown badge

Turn on Next event countdown to show a small pill under the dial that reads "Golden hour ends in 14:32" or "Sunset in 1:23:04" — the next significant celestial event from the active ephemeris location. The badge ticks the seconds in real time and rolls over to the next event automatically. When all of today's events have passed it falls through to tomorrow's dawn.

Time scrub slider (preview sun and moon)

Turn on Time scrub to add a horizontal timeline under the dial. It spans a full 24 hours centred on now, so dragging it walks both the yellow sun tick and the silver moon glyph around the dial to where each body will be at any moment from twelve hours ago to twelve hours ahead. A silver line along the lower part of the timeline traces the moon's altitude through the night, with moonrise and moonset marked; the sun's events are marked too, and releasing a drag near any marker snaps onto it. The wall-clock time of the scrubbed instant is shown above the timeline; a Now affordance resets it. Lets you preview a sunset shot at noon, or check where the moon sits at 2 am, without doing arithmetic.

Pitch indicator

A thin horizontal line across the dial shows how tilted the camera is up or down. At horizon level the line sits across the middle; tilt up and the line drops below the centre, tilt down and it rises above. Plus or minus 45 degrees fills the dial vertically. Useful for low and high angle shots when you want the pitch to feel intentional, not accidental.

Accuracy ring and calibration

The outer ring around the dial is colour coded for sensor accuracy: green is high, yellow is medium, orange is low, red is unreliable. If it goes red the badge replaces its face with a 'Calibrate (figure-8)' prompt. Wave the phone in a slow figure-8 motion for a few seconds to re-prime the magnetometer. Driving past large pieces of iron, standing on a steel-framed bridge, or holding the phone near a speaker can all knock the magnetometer out of calibration.

Stamp on shot log

When on, every shot you log carries the camera heading and the applied declination as two extra columns in the shot log database (and the CSV export). Magnetic readings are recorded with declination = 0 so analytics can tell magnetic and true apart later. Off leaves the columns null. Useful for location scouting, multi-day projects, and reconstructing what you shot facing which way long after the trip is over.

Devices without a magnetometer

A small minority of budget Android phones ship without a magnetic field sensor at all. On those devices the system reports no compass capability, the Compass overlay row in the Composition grid picker is greyed out, and the subtitle explains why. The overlay never tries to wake up sensors that aren't there.

Battery cost

Sensors are only registered while the master toggle is on. When you turn the overlay off, the listener is unregistered and the battery cost drops to zero. The sun azimuth recomputation runs every 30 seconds and is cheap. Declination only recomputes when you change ephemeris location.

Implementation notes (for developers)
CompassSensor uses TYPE_ROTATION_VECTOR with an ACCELEROMETER + MAGNETIC_FIELD fusion fallback at SENSOR_DELAY_UI. CompassSensor reports two independent magnetic bearings from one rotation matrix, each a single projection with NO source-switching: the camera heading atan2(-R[2], -R[5]) for this viewfinder badge (and the shot log), and the top-edge heading atan2(R[1], R[4]) for the standalone Compass tool (13.7). The badge uses the camera heading because the phone is held upright to frame, where the lens direction is the bearing of the shot and is the stable axis; the standalone uses the top-edge heading because it is held flat like an ordinary compass, where the top edge is the stable axis. Each surface reads the bearing for its own pose, so nothing ever switches and the heading cannot jump as the phone tilts. This split replaced an earlier single bearing that picked whichever axis was more horizontal and switched between the two; combined with hand roll that jumped the heading by tens of degrees as the phone tilted, and later attempts to force the camera axis everywhere froze the dial when the phone lay flat (the exact pose the standalone tool is used in). On-device logging (pitch -89 = flat, accuracy HIGH, location/declination/sun all correct) confirmed the bug was source selection, not the sensor. Pitch and roll come from the camera direction; both bearings are smoothed in the sin/cos domain. The math is in CompassSensor.computePose, covered by CompassSensorTest. Declination is applied downstream. Declination via android.hardware.GeomagneticField keyed to the active EphemerisLocation. Sun azimuth + sun-path samples + next celestial event come from SunMath.sunPosition / sunPathSamples / sunEvents (all added with this feature) and are recomputed on location change + every 30 s. Countdown badge ticks its own 1 s clock on the UI side. Hardware capability checked via PackageManager.FEATURE_SENSOR_COMPASS so devices without a magnetometer see a clear 'not supported' empty state. State lives in standalone StateFlows on the ViewModel (D8 ceiling on ViewfinderUiState). Persisted in Profile.compass* (DB v63 migration added the path/countdown/scrub toggles on top of the v62 baseline). Moon azimuth and the moon-path samples come from SunMath.moonPosition / moonPathSamples, a geocentric Schlyter lunar ephemeris (about 0.02 degree ecliptic-longitude accuracy, cross-checked against sunPosition at new and full moon), recomputed alongside the sun on the same three triggers. The moon arc and glyph reuse the existing Sun and moon path toggle (Profile.compassShowSunPath) so no schema bump was needed, and the time-scrub range was widened from the old civil dawn to dusk window to a full 24 hours centred on now (moonrise/moonset markers are scanned from the moon samples for horizon crossings).

Search documentation