Engineering Maplight: From Photo Coordinates to Land Coverage

The product question behind Maplight

A visited-country map answers a useful binary question: is a place part of your history? Maplight asks something different. Given years of located photos and other travel evidence, what nearby parts of the land have those moments reached?

That sounds like drawing translucent circles around points. A production feature has to solve harder problems: points overlap, circles cross coastlines and borders, Earth is curved, source data arrives from several systems, old devices may be offline, and a lifetime library must remain fast enough to explore interactively.

Maplight's implementation separates those concerns into a small portable origin model, a deterministic coverage engine, and a rendering layer. The same input should produce the same coverage whether the history was created on one device or merged through iCloud across several.

Generalize the input before persisting it

The raw input can begin as a photo coordinate, an imported trip, a passport stamp, or a manually recorded place. Before a Maplight origin is persisted, Mapsake quantizes its latitude and longitude to a six-character geohash cell. The stored origin contains that geohash, a bit mask describing contributing source types, and the earliest known day.

This provides three useful properties.

First, repeated evidence in the same small geographic cell can merge into one origin. Second, the portable record is compact and deterministic. Third, the Maplight model does not need to preserve every original photo coordinate to reproduce the illumination.

The earliest day powers the History view. Sources without dates still count toward the all-time result but do not pretend to belong to a year the app cannot establish.

Make merging additive

iCloud synchronization is not a single ordered stream. Two devices can work offline, write related records, and later receive duplicates in different orders. A last-writer-wins Maplight blob would make legitimate history disappear.

Instead, origins merge by geohash. Source flags are combined and the earliest valid day wins. Origins are encoded in sorted order inside compact chunks. A logical chunk is identified by profile, generation, and geographic tile, while reconciliation unions duplicate chunk contents.

The generation identifier matters when rebuilding. New output can be prepared without treating stale chunks from the previous generation as current. That keeps a partial sync or interrupted calculation from producing a mixture of old and new coverage.

The merge rule is intentionally boring: union the evidence. Boring, deterministic rules are valuable when the same private history must converge across an iPhone, iPad, and Mac.

Coverage is measured on an equal-area grid

Latitude and longitude degrees do not represent equal distances everywhere. One degree of longitude shrinks toward the poles, so counting ordinary map pixels or degree-sized cells would bias the result by location.

Maplight evaluates land coverage on an approximately two-kilometer equal-area grid. Each row represents comparable physical area, and illuminated spans are stored as intervals across that row. A source radius becomes a range of candidate cells; those cells are then tested and accumulated.

Intervals make overlap inexpensive. If several nearby photos illuminate the same cells, the engine merges the runs instead of counting the land repeatedly. The final number represents the union of illuminated land, not the sum of every circle.

This is also why the coverage number may not match the area of mathematical circles multiplied by the number of sources. Ocean cells are removed, overlaps collapse, and border attribution can divide the result among countries.

Keep ocean out of the total

A flight photo or coastal visit can place a radius over water. Maplight is described as illuminated land, so water cannot quietly inflate the number.

The coverage engine uses bundled boundary geometry to determine whether candidate cells are on land and which country contains them. The same broad source family that supports Mapsake's offline map and gazetteer work makes the calculation available without sending a lifetime coordinate set to a web mapping API.

Coastlines are naturally more complicated than inland points. Islands, narrow peninsulas, enclaves, and disputed boundary conventions all create edge cases. The engine therefore treats coverage as a useful estimate at its grid resolution, not cadastral surveying.

Attribute coverage without double counting

Country totals are derived from the same covered cells as the global total. A cell can be assigned using boundary containment while the global union continues to count it once. This keeps the country breakdown explainable and prevents a border-adjacent source from creating more worldwide land than the map actually covers.

Source breakdowns are separate from area attribution. A geohash origin can remember that both photos and a manual place contributed, but the illuminated cells around that merged origin still belong to one union. This distinction lets the interface explain where evidence came from without turning overlapping evidence into duplicate land.

Build the timeline from cutoff snapshots

History needs to answer “what did Maplight look like by this year?” Recalculating every year from scratch during each slider movement would waste battery and make the animation stutter.

The model records year snapshots associated with the current generation and radius. Each snapshot represents origins whose earliest day is at or before its cutoff. Undated origins remain available for the all-time view without being inserted into a fictional historical year.

The interface can then move through prepared totals and geometry while keeping the map response immediate. Rebuilding still occurs when the underlying origin set, selected radius, or generation changes, but ordinary playback reads a stable sequence.

Rendering fog instead of thousands of circles

The user sees light, not grid cells. The rendering layer translates computed coverage into an overlay that can move and zoom with the atlas. Treating the whole world as one giant high-resolution texture would use too much memory; rendering every origin as an independent live shape would repeat overlap work on every frame.

Maplight therefore keeps the expensive geographic union outside the frame loop and renders prepared coverage in manageable pieces. The overlay can focus on presentation - color, opacity, zoom, and transitions - while the coverage engine owns the geographic answer.

This boundary also helps testing. A coverage snapshot can be checked without a SwiftUI view, and rendering can be tuned without changing merge semantics.

Privacy shaped the architecture

It would be simpler to upload photo coordinates to a server and calculate coverage there. Mapsake deliberately does not require that architecture. Quantization happens before Maplight persistence, coverage can be built on the device with bundled land geometry, and public sharing exports a generalized result rather than the private origin collection.

That choice moves work to the user's hardware and makes synchronization design more demanding. It also means the system can remain useful offline, the website does not become a warehouse of personal photo locations, and removing or exporting data stays connected to the user's Mapsake record.

What we learned

The key lesson was to make each layer answer one precise question:

• Origins answer what generalized evidence exists and when it first appeared.
• Merge rules answer how several devices converge without losing additions.
• Coverage answers which equal-area land cells are illuminated.
• Snapshots answer how that union changes over time.
• Rendering answers how to make the result feel alive.

Maplight looks playful because the machinery underneath is deliberately restrained. Compact inputs, additive synchronization, equal-area measurement, interval unions, bundled boundaries, and prepared snapshots leave the interface free to do the emotional part: let someone watch a life in photos brighten the map.