Map

A shareable composition of layers, camera, basemap, and access settings.

Raw Markdown

Meaning

A Map is the user-facing artifact: an ordered composition of Layers, basemap configuration, camera state, metadata, and access settings.

Data relationship

Maps do not own platform data feeds. Their Layers reference stable Provider and Channel identities. Catalog default changes therefore affect new compositions, not already published maps.

Map appearance

Basemap adjustment is map-level presentation. It lightens or darkens the basemap without changing data layers, and must not be stored through an individual Layer editor. Every control in Map settings—including projection and atmosphere—updates a device-local working value and is automatically saved into the Map's shared working draft after a short debounce. Projection and atmosphere become shared map defaults; a viewer may still override them locally. The client serializes saves through one transactional server boundary so rapid control changes cannot arrive out of order.

Draft and published revisions

Each Map has one mutable working draft shared by its owner and editors. Map metadata, settings, starting camera, connections, Layers, Channel bindings, and user-authored objects become immutable together when an editor publishes a revision. Revision numbers are assigned at publication; an unpublished draft does not consume a number. Opening an unchanged working copy does not expose a Draft state in the UI: the Draft badge appears only after the working copy diverges from the latest revision. Reset draft atomically restores that latest revision without creating a new version. A changed user-owned Source shared with another Map is not silently rolled back because that would mutate the other Map's working data.

Viewers never read mutable authoring rows. An unversioned Map link resolves the latest published revision, while ?v=N pins an available historical revision. This also applies to viewer members of private Maps. Owners and editors open the working draft by default and can use a pinned link to inspect an earlier revision without editing it. In Explore and My Maps, an owner/editor likewise sees the current draft title, tags, and preview with the Draft indicator; anonymous users and viewers continue to see the latest published revision.

Platform Sources remain live across Map revisions: a revision freezes the Map's selection and presentation contract, not the external feed's observations. Features from user-owned or imported Sources are copied into the revision so published markers and drawings do not follow later draft edits. A shared-map copy is created from the latest published revision rather than from a newer working draft.

Solar context

The day/night terminator is map-level presentation rather than a catalog Source or user Layer. A Map independently stores whether to show the terminator line and the night fade, plus their opacity. Mapbox projects both native GeoJSON style layers above the composed map data in globe and Mercator. The one-pixel line has no outline and resolves to white on dark basemaps or black on light basemaps.

Without an explicit map time the terminator follows wall-clock time. A fixed map cursor also drives the terminator.

Temporal axis

One device-local map-time cursor controls the map. Null means Now; a fixed selection survives reload, changes of visibility and channel, and manifest refresh. The discrete track edits that cursor. The track is the union of published group timestamps and annual raster periods, with Now and the fixed cursor retained. Group renderers still receive exact published timestamps; compatible fields such as GFS wind and rain share their exact intersection before resolving the nearest frame.

Layers with their timeline disabled still follow the map cursor, but do not contribute dates or history pagination to the selectable track. Temporal group dates and history pagination also follow the layer's effective display zoom interval, including its provider minimum. A group outside that interval does not contribute to the track. Zoom changes preserve the fixed map cursor and the published time domains used to resolve frames.

For a fixed cursor, each Channel resolves the map time with a bounded selection policy. An optional endpoint_config.temporal_selection declares max_offset_seconds or cadence_seconds. Hourly cadence allows one hour; other declared cadences allow half a step. A missing frame never increases that declared tolerance. Legacy observation channels default to 36 hours; forecast channels to one hour, with GFS allowing 90 minutes for its two/three-hour schedule. Declared calendar periods select their containing day, month or year. The compatibility adapter also recognizes Copernicus daily current means, the cadence in declared marine dataset identities, and MODIS historical 16-day composite intervals.

Nearest-frame ties choose the earlier frame. In Now/Latest, observation-only channels select the newest common published frame at or before now, regardless of the historical matching tolerance. Publication latency and freshness do not invalidate the latest available observation. Its real observation timestamp is preserved; it is never relabeled as a current measurement. Forecast channels still require coverage of now, and fixed cursor dates still use bounded matching. Annual raster periods follow the same Latest rule: use the latest year in the Map Connection's configured range that is not later than the current year. A fixed cursor outside that range remains unavailable. Legacy standalone year controls also write the shared map cursor; their displayed selection and the requested period must never be independent states. A layer outside its tolerance or period coverage renders nothing and is excluded from inspection and viewport prefetch, without removing it from the layer list or adding an availability message. The same temporal eligibility also excludes that layer from runtime loading observers and the global loader; an absent renderer is not a pending acquisition. Live positions without a temporal field are absent for a fixed time; untimed static layers remain.

Recent-window event layers use the window ending at map time, with a 24-hour default unless the map or layer has an explicit window preference. Historical event timelines retain cumulative hide/dim semantics up to the chosen cutoff. Maps containing only historical events retain their year selector and all-data default, without Now/Latest or a recent-window control. GeoJSON filters and MVT request windows use the same endpoint. Time selection never creates an archive of snapshots or live positions that the provider has not retained.

Portability

GeoLama map recipes serialize presentation and catalog references with stable slugs and provider-local channel export keys. User data and credentials are not implicitly bundled. An administrator can export every current Map recipe in one versioned JSON backup. Restoring that bundle is atomic and creates new private Maps owned by the importing administrator; it never overwrites existing Maps.

Tags

Map tags are user-facing metadata backed by one administrator-managed ordered catalog. Catalog order controls the tag sections in Explore. Renaming, deleting, or merging a tag is one atomic operation across every Map that uses it; merging also deduplicates Maps that already contain the replacement tag. An affected public Map is republished as a new immutable revision so its current Explore group changes without rewriting historical revisions.

Starting camera

Publishing offers three starting cameras: the shared Default, the Map's Saved camera, and the Current view. Publication atomically stores the selected camera for this Map and its immutable version. Only Config changes the shared default; publication never modifies it. New maps receive the current shared default as a snapshot. Changing the shared default does not rewrite existing maps or immutable published revisions. The built-in fallback is the Atlantic-centered view at longitude -35, latitude 20, and zoom 2.36. A viewer's later camera movement remains a local preference. Every open Map also reflects its current camera in the URL as center=longitude,latitude&zoom=value; opening that link uses the URL camera for that visit without changing the Map's shared starting viewport or the viewer's local preference. The debug Viewport actions fly smoothly: Default targets the current shared default, while Reset targets the Map's saved starting viewport and uses that shared default only as a fallback when no saved viewport is available.

Preview camera and capture preferences

The Map opening viewport remains independent of settings.previewCapture. Update preview flies to the saved preview camera and opens confirmation. The author selects the saved preview view or the view from before opening through the same basemap thumbnail cards used by version publication. Cancel restores the previous camera. A successful capture atomically saves the preview camera, excludeMapLabels, and replaceCurrentVersion. Legacy Maps use the current camera and the existing label choice on their first capture.

Label exclusion affects only the captured frame; live labels are restored after copying it. The opening viewport and map composition are not changed.

The replacement checkbox starts enabled and remembers subsequent choices, including an explicit unchecked choice. When no saved version exists it saves the draft preview and preference without creating a version. The remembered replacement checkbox optionally updates the latest saved Map version's gallery image, social image, and gallery contrast metadata. This is a narrow exception to snapshot immutability: it creates no Map version and changes no version composition, opening camera, publication timestamp or other settings. Older versions remain unchanged. Only Map editors can request replacement; stale image revisions and a changed latest version are rejected atomically. Preview bookkeeping does not mark a clean Map draft as edited, while existing content edits remain pending. Without replacement only the draft preview changes.

Explicit preview capture prepares the gallery's final 800×440 WebP before committing the capture. The existing server processor applies a centered cover crop and progressive lower blur. Its Gaussian strength follows a smoothstep curve over the bottom 80 logical pixels, with interpolation between 24 levels. The original capture is retained as original.webp; the prepared image is stored as preview.webp alongside the unchanged branded social image.

The capture stores average colours and black/white foreground choices atomically with its paths and label preference. Metadata is bound to its immutable image path and follows Map revisions through their existing settings snapshots. Gallery cards fetch that final private Storage image directly and lazily; they never request processing, read pixels, create processed blobs, or replace a loaded original. Legacy captures remain directly readable with a white text fallback until explicitly regenerated. Historical objects remain unchanged.

The capture processor accepts only signed map-previews URLs from the configured Supabase instance and bounded Mapbox static-image requests. It downloads using the supplied capability, without service-role credentials, and checks that capability before every cache hit. Image bytes and render concurrency are bounded; redirects are rejected. A failed processing or upload leaves the previous capture unchanged and removes only uploaded objects of the failed new capture. The capture metadata RPC uses existing RLS and does not change map publication state.

Each explicit preview update publishes one immutable revision containing a gallery WebP and a 1200×630 branded social JPEG. Link metadata and the social image are exposed anonymously only while the Map is public; the same RLS-backed access boundary continues to protect private Maps. Preview publication does not save the starting camera or basemap; it saves only capture preferences. Earlier preview objects are retained when a new capture succeeds because published historical Map revisions may still reference them.

An active private Map version link is a narrow capability exception to anonymous access. Its server gateway first returns only the Map title, description, and current immutable gallery preview through a five-minute signed URL. It then exchanges the fragment token through POST for a signed, Map-scoped anonymous session. The database rechecks the capability row on every read, so expiry, revocation, and ownership transfer take effect immediately. The gateway returns the same not-found response for malformed and inactive tokens and disables caching.

Access

Authorization is enforced by database RLS. Client-side visibility checks are user experience controls, not a security boundary. See Authorization and secrets.

For a private Map, its owner may create multiple independent private version links and explicitly revoke all active links. Creating or copying a new link never invalidates an earlier unexpired link. Every link grants anonymous, read-only access to the saved immutable revision without authentication. It does not create a membership, subscription, or public-catalog entry. Its 256-bit capability token stays in the URL fragment, is stored only as a SHA-256 digest, and expires after seven days. Links created by a former owner are no longer accepted after ownership transfer.

Copying a private link is also the explicit versioning gesture for link sharing. If the current draft differs from the latest revision, the operation atomically creates a new immutable private revision before issuing the link. It never changes is_public or adds the Map to Explore; there is no separate private-version action in the UI.

An owner-facing public Map menu separates Copy Public Link, which follows the latest revision, from Copy Version Link, which pins the current immutable revision, and Publish New Version, which advances latest only when the draft has changed. These version actions are grouped between Edit/Duplicate and Delete. For a private Map, the owner menu is Edit, Duplicate, a divider, Copy Version Link, Publish Map, a divider, and Delete. Copying the version link creates a new independent capability; every earlier unexpired link remains valid. The collaboration dialog reports that active links exist and can revoke all of them together; raw tokens remain non-recoverable after their one-time issue. An active link opens a landing card and then the immutable Map revision directly, without a login step. Explicit collaborator membership remains a separate owner-managed access mechanism.

Unified data controls

Data choices and numeric presentation parameters share the controls surface next to Layers. Exclusive choices use the same menu as layer selection; numeric parameters use a compact popup with a slider, decimal text field, and reset to the author's default. Author settings reuse the same numeric field. The time cursor remains in the existing timeline dock. Controls follow the visible, zoom-active layers used by rendering and do not duplicate linked selections.

For daily MODIS snow, a Layer can define rasterScalarThreshold.minimum in [0, 1]. The threshold appears only in the Layer editor as a slider with a value label. There is no map-side control or viewer-adjustment permission. The saved threshold applies to every viewer; legacy viewerAdjustable flags and stored device-local threshold choices are ignored. The unfiltered positive NDSI Channel is required so lowering the shared threshold can reveal weaker signals. Values below the minimum become transparent and are excluded from inspection; provider no-data remains transparent. This changes presentation, not the scientific encoding or palette scale.

Object search follows the Map's selected visible Layers and Channels independently of camera bounds and zoom. Objects already delivered to the client use its local index; tiled vector Layers additionally request bounded server search results. The database intersects every request with authorized draft or immutable revision bindings. User-owned published data remains frozen, while platform Sources use active observations. Search does not grant access to hidden author-only Layers or private Maps. Selection reuses the normal inspector, camera focus and object URL.

Search result secondary text is selected independently in the Layer Fields table's Search column. Selected fields replace the Layer name and follow the shared field order, display labels, date/number formats and units. An absent selection retains the Layer name for existing Maps; an explicitly empty selection hides secondary text. Missing selected values are shown as an em dash.