Layer

Saved visualization over one Provider and an explicit Channel subset.

Raw Markdown

Meaning

A Layer answers how selected data is presented on a map. Data identity and presentation are deliberately separate.

Owns

geometry presentation.

resolved Provider and explicit Channel subset are immutable identity.

Defaults

Catalog defaults are applied only when a new Layer is created. Later changes to Data Product or Channel defaults must not silently restyle existing maps. For provider raster presentation, the Layer also retains the initial scalar palette or theme parameters as an immutable Original snapshot. Choosing and restoring other palettes changes only the active presentation.

Composition

A Layer belongs to one Map. Multiple layers may visualize the same Provider differently without duplicating the underlying data source. Several Layers may also present one Map Connection differently while sharing its saved data selection. Such presentation alternatives retain the identical ordered Channel subset and are valid only in an exclusive connection, so they cannot accidentally duplicate one data selection as simultaneous overlays.

When that Map Connection uses exclusive visibility, its Layers remain separate presentation objects with independent styles, but the group permits at most one visible Layer. The connection remembers the selected Layer; each Layer continues to own its own persisted visibility and presentation. Map readers switch these alternatives through one dropdown; their choice is device-local. In the editor every member remains a separate Layer row and uses the ordinary Layer visibility control.

When an author enables viewer visibility control, each viewer may show or hide the Layer locally. That device-local choice does not rewrite the saved Layer or change authorization to its data. For a non-exclusive connection, a hidden Layer with this control enabled is included in the published reader projection together with its channels and frozen features. Its saved visibility sets the initial unchecked state; hiding it is not a privacy boundary. Hidden Layers without viewer control remain excluded from the reader projection. Exclusive groups retain their selector eligibility rules.

Numeric raster palettes follow the same ownership boundary: the Channel declares how to decode values, while the Layer owns their colors. See Numeric raster encoding and palettes.

Presentation ownership

A Layer remains tied to its selected Channel even when that Channel returns points, lines, polygons, or several semantic rendering parts. Those parts are modeled as Layer-owned presentations, not as new Channels. Each presentation owns a local collection of independently visible visual styles.

Applicability selects the data objects for a conditional style. Fixed visual properties and property-level data-driven encodings determine appearance and must not be conflated with applicability. Encodings stay local to the affected presentation and style rather than forming one global Layer section.

Relative applicability periods are saved as rolling rules, not frozen dates: Last Day/Week use 24 hours/7 days, Month/Quarter/Year subtract 1/3/12 UTC calendar months (clamping month-end dates), and custom periods accept positive whole days or years. Both bounds are inclusive and future values are excluded. Year-only fields offer Year and custom years, comparing the inclusive range from the current UTC year minus the count through the current year. Missing and invalid values do not match. Mapbox expressions and client style resolution use the same period calculation; the map's existing clock refreshes expressions.

Every presentation has a visible unconditional default style. Ordered conditional variants resolve with deterministic priority; no rule, no match, or an invalid target falls back and never silently hides data. Presentation and style identities are local to one Layer and therefore one Map, not catalog entities or shared-library references. An administrator-managed marker and label appearance catalog may be reused by explicitly copying a preset into a Layer. Each label rule owns its own copied appearance snapshot, so labels in one style may use different presets without becoming live catalog references. The copied fixed values are independent snapshots: later preset edits do not restyle the Layer. Label data binding, formatting, placement, and selected-only behavior remain Layer-local rather than entering that catalog. Label rules are ordered and may be reordered in the Layer editor. Rules that share one placement form a visual multiline stack in that order. Placement is strict: collision handling may hide the label, but must not move it to another side of the marker. Marker outline overlap is also Layer-local and is preserved when a shared marker preset is applied. Every saved marker or label preset is available for selection; the point-style catalog has no separate picker-visibility flag. User-visible field names and date or numeric formats are also Layer-local. inspectionFieldOrder stores one shared ordering of stable field keys for hover and details. Their visibility selections remain independent. Unknown or duplicate ordering keys are ignored; newly available fields keep their fallback order after the saved keys. An ordered Title appears as an ordinary field rather than overriding the sequence as a fixed details heading. Fields can be reordered with the shared drag-and-drop list in the Fields editor. Its drag handles also support keyboard sorting. Layer name is an independent heading, disabled by default in both surfaces; explicitly enabling it displays it in the compact tooltip as well as details. Missing flags resolve to disabled. The default migration resets only explicit opt-ins in existing working drafts; immutable published revisions retain their saved settings. Numeric presentation either preserves the unrounded value or uses an explicit fixed precision shared by map labels, hover tooltips, and object details. Filters, conditions, and data-driven encodings continue to evaluate the original typed value. Their editor labels and finite choices come from the normalized Data Product contract, so Layer UI does not branch on a provider or expose internal property keys. Copy/paste follows the same snapshot rule and creates a new independent local identity. Display edits point, line/trajectory, and area families separately. Marker styles also choose whether touching outlines merge into one union shape or remain visible around every individual marker. New vector Layers persist explicit presentation schema v1. Legacy LayerStyle and role-symbolizer snapshots remain readable and can be converted by the pure, idempotent compatibility adapter without deleting rollback fields.

Geometry presentation

Every vector Layer can retain source geometry or present the geographic-bounds center as a point. A versioned Data Product contract may additionally declare bounded derived modes whose inputs are normalized feature attributes. The Layer saves the selected mode and a snapshot of its derivation contract; the Provider does not mutate stored feature geometry merely for display.

Selecting a derived polygon ensures the Layer has an Area presentation while preserving its Marker presentation for a later return to source or center mode. Client GeoJSON and server MVT delivery apply the same saved geometry. Unknown derived modes are rejected server-side, and a feature with missing, invalid, or out-of-bounds inputs is omitted rather than silently falling back to a point. For large MVT-backed layers, an author may keep the map legible at distant zooms by clustering validated object centers through the Layer's saved cluster zoom. Above that threshold the same source returns the true derived polygons; the fallback never enlarges their physical extent. Feature-level filters and time windows disable server aggregation when a cluster could no longer retain their semantics. A fixed operational window may keep clustering when that window is sent to the tile service and applied before aggregation; NASA FIRMS' latest-24-hours view is the first such case.

Cluster appearance remains Layer-owned. The author may cap the marker's screen diameter while its radius still grows with the aggregated object count. Visible counts use a compact label and enforce enough marker space for that label; hiding the count permits a smaller cap.

Primary marker colors, line colors and polygon fills retain their selected or data-driven colors independently of basemap lighting. The primary color picker does not offer adaptation. Marker outlines and explicitly opted-in polygon borders retain separate basemap lighting controls. Legacy primary colorBehavior snapshots remain readable but do not dim semantic colors.

Presentation animation

Point animation is saved independently on each marker style in the Layer and never creates another Provider, Channel, or data copy. A style may own its own effect or no animation at all. A versioned bounded specification separates the trigger (continuous, first appearance, or property change), repeat policy (once, a finite count, or while active), visual actors, normalized keyframe tracks, and optional numeric property modulation. One breathing marker and several staggered ripple outlines therefore use the same contract.

Animation actors are visual clones above the resolved static marker. The base marker remains stable for selection, labels, and collision behavior. One shared map runtime advances every visible animation under the viewer's dynamic-render budget; reduced-motion viewers receive the saved static fallback. Catalog defaults are new-Layer seeds and do not restyle existing maps.

Alongside screen-sized fill and outline actors, a beam actor may bind its reach to a numeric Layer property in nautical miles or kilometres. The renderer projects that reach as a geodesic sector on the map surface, inherits the resolved marker color, and derives angular width from the active fraction of the rotation cycle. Multiple instances with phase staggering model opposed beams without adding another animation loop or provider-specific renderer.

A single Layer-neutral point-effect renderer resolves conditional marker styles and trigger state when source data changes, then draws all active clones through one bounded instanced WebGL2 batch. Outside Mapbox's globe→Mercator morph, a version-pinned custom layer tessellates every local effect on the geographic surface, so rings follow globe curvature and share Mapbox's camera projection. Inside 5 < zoom < 6, the same analytic animation switches to a screen surface whose marker centers are projected by Mapbox; it never attempts an independent globe/Mercator interpolation. The shared frame clock is a small relative time uniform: animation does not mutate paint properties per frame or store transient clocks in Mapbox feature-state. Static markers, selection, labels, and collision remain Mapbox-native.

The shared point-animation catalog owns reusable live visual definitions: duration, bounded actors, tracks, and reduced-motion fallback. A marker style stores the catalog preset ID together with a normalized visual snapshot. Runtime uses the current catalog definition when the ID is available and falls back to the saved snapshot when it is not. Trigger type, trigger property, repeat policy, freshness window, applicability, and numeric data modulation remain Layer-local, so one wave preset can react to different fields on different maps or conditional styles. A local visual edit detaches that animation from the preset and turns it into Custom. Config's large preview compiles the same sampled tracks and renders them with the production point-effect surface; compact catalog thumbnails may use the bounded CSS fallback.

Map-wide zoom guidance

The map aggregates enabled Layers using their effective display zoom intervals, including provider minimum zoom. If any enabled Layer permits the current zoom, there is no global hatching or zoom hint. Hidden Layers and the basemap do not participate. An empty map or a map with all Layers hidden has no zoom hint. Loading, errors and absence of features in the viewport do not imply that zoom is unavailable; their feedback remains in the Layer runtime state.

When every enabled Layer is outside its interval, one shared decision drives both geographic hatching and a zoom-in or zoom-out hint. The action targets the nearest usable interval, landing inside its exclusive upper bound when zooming out. Empty intervals never supply a target. Provider native maximum resolution is not a display maximum: overzoom remains available.