As of v2.9.0, fog is the preferred method for sky styling instead of using sky layers. See the latest documentation.

‍

As part of the launch of Mapbox 3D, the new Camera API allows developers to increase map pitch from 60 to 85 degrees. This increased map pitch exposes the horizon and sky, which can now be styled using new properties. The Sky API can be used to achieve a broad range of design effects including realistic atmospheres, arbitrary gradients, or simulating the sun’s position based on geographic location and time of day.

The properties for the sky layer type in the Mapbox GL style specification are:

sky-opacity:  The opacity of the entire sky layer. Can be interpolated across zoom levels.

sky-type: One of the following:

• gradient: Renders the sky with a gradient that can be configured with sky-gradient-radius and sky-gradient.
• atmosphere: Renders the sky with a simulated atmospheric scattering algorithm. The sun direction can be attached to the light position or explicitly set through sky-atmosphere-sun.
  

sky-atmosphere-color: Color coefficients used to determine how color channels scatter throughout the atmosphere. Using white will apply the default coefficients, giving a blue color to the atmosphere. Changing a color channel will affect how heavily this particular channel is affected by scattering. The alpha channel describes how strongly the atmosphere color is represented in the sky layer.

sky-atmosphere-sun: Position of the sun center [a: azimuthal angle, p: polar angle]. The azimuthal angle indicates the position of the sun relative to 0° north, where degrees proceed clockwise. The polar angle indicates the height of the sun, where 0° is directly above, at zenith, and 90° at the horizon. When this property is omitted, the sun center is directly inherited from the light position.

sky-atmosphere-halo-color: A color applied to the sun halo. The alpha channel describes how strongly the sun halo is represented in an atmosphere sky layer.

sky-gradient: Defines a color gradient with which to color the sky. The color values can be interpolated with an expression using sky-radial-progress. Can be interpolated by sky-radial-progress in a color-ramp.

sky-gradient-radius: The radius angle for a gradient. A value of 180 will make the gradient wrap around.

sky-gradient-center: Position of the gradient center [a: azimuthal angle, p: polar angle]. The azimuthal angle indicates the position of the gradient center relative to 0° north, where degrees proceed clockwise. The polar angle indicates the height of the gradient center, where 0° is directly above, at zenith, and 90° at the horizon.

The generated sky in Mapbox 3D uses an atmospheric scattering algorithm taking the sun direction, geolocation and time of the day as input, along more specific controls (haziness, luminance, etc.). These allow for both time of day configuration and minor artistic control. The gradient enables smooth interpolation of multiple colors between the horizon and zenith angles, or radial gradient centered around the sun direction, combined with the use of theme colors from base map styles.

Atmospheric scattering shaders are computationally expensive. We use a bake-once-reuse-multiple-times concept. This broadens the support to lower-end devices, where the skybox generation is invoked sparingly. This means the sky would be regenerated at cyclic events if dynamic, or once if static. When a skybox is regenerated, a smooth interpolation between the previous and new result is applied over a few frames to prevent abrupt visual changes. Due to its nature, procedural generation will inevitably show signs of color banding. To solve this, a slight temporal dithering is applied in the shader.

Sunrise, Morning, Afternoon, Evening, Sunset using SunCalc

Using the new sky layer properties, designers can use a JS library like suncalc to compute sun position and sky colors to change the experience based on time of day and location.

The gradient and atmospheric sky layers both use spherical coordinates to describe the center of the gradient and the sun. This follows the already existing light specification--, and here is how the XY plane matches the map at sea level.

Incorporate the new Sky layer  into your maps directly in code or through a streamlined interface in Mapbox Studio. Get started today and share your 3D maps with us on Twitter with #BuiltWithMapbox.