Lights
There are two lighting models available:
- 3D lighting is a new lighting mode introduced in Maps SDK v11 for iOS and Android, and Web SDK v3. It is used for illuminating the entire scene, including extruded features, 3D models and all other layers. You should choose this mode if your map uses 3D models, or fill extrusions that should cast shadows, or if you want the global lights to affect the illumination of the entire scene.
- Flat lighting is the traditional lighting mode which is used to illuminate fill extrusions and the hillshade layer. You should choose this mode if your map doesn’t contain models or fill extrusions, and you don’t need complex lighting options.
3D lighting
This mode enables dynamic lighting, enhanced sense of depth and symbolic realism on the whole map. It enables 3D extrusions and models to cast shadows. The root-level lights array takes a list of light source objects.
Light source
Each light has its own properties that can be specified under properties. These, together with the layer properties determine the final color of the layer. The layers are lit uniformly with the ambient light (left image). Directional light shades the parts that face towards it more brightly (middle image). Directional light also casts shadows causing the occluded areas to receive less light and hence appear darker. The combined lighting terms give the full lighting solution (right image).
ambient and directional lights are combined to give the final lighting solution.
id
Unique light name.
properties
Properties of the light.
type
Type of the light to be added
"ambient":An indirect light affecting all objects in the map adding a constant amount of light on them. It has no explicit direction and cannot cast shadows.
"directional":A light that has a direction and is located at infinite distance, so its rays are parallel. It simulates the sun light and can cast shadows.
"flat":A global directional light source which is only applied on 3D and hillshade layers. Using this type disables other light sources.
*-emissive-strength paint property
The *-emissive-strength property of some of the layers provides an additional control mechanism that affects the lighting calculations for those layers.
A value of 0 indicates that the layer does not have any emissive component and its final color is affected by the layer color and the 3D lighting settings described earlier.
A value of 1 indicates that the layer’s final color is determined solely by the layer color. Note that shadows also affect the final color of the layer if shadow-intensity is non-zero.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
measure-light expression
Using the measure-light expression, a layer can change its color based on the light configuration.
Light source types
Directional
A light that has a direction and is located at infinite distance, so its rays are parallel. It simulates the sun light and can cast shadows.
cast-shadows
false. Enable/Disable shadow casting for this light
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
color
Color of the directional light.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
direction
0 and 360 inclusive, between 0 and 90 inclusive ]. Defaults to [210,30]. Supports interpolateexpressions. Transitionable. Direction of the light source specified as [a azimuthal angle, p polar angle] where a indicates the azimuthal angle of the light relative to north (in degrees and proceeding clockwise), and p indicates polar angle of the light (from 0°, directly above, to 180°, directly below).
[
90,
40
]
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
intensity
0 and 1 inclusive. Defaults to 0.5. Supports interpolateexpressions. Transitionable. A multiplier for the color of the directional light.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
shadow-intensity
0 and 1 inclusive. Defaults to 1. Supports interpolateexpressions. Transitionable. Determines the shadow strength, affecting the shadow receiver surfaces final color. Values near 0.0 reduce the shadow contribution to the final color. Values near to 1.0 make occluded surfaces receive almost no directional light. Designed to be used mostly for transitioning between values 0 and 1.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
shadow-quality
Determines the quality of the shadows on the map. A value of 1 ensures the highest quality and is the default value.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | Not yet supported | >= 11.9.0 | >= 11.9.0 |
Ambient
An indirect light affecting all objects in the map adding a constant amount of light on them. It has no explicit direction and cannot cast shadows.
color
Color of the ambient light.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
intensity
0 and 1 inclusive. Defaults to 0.5. Supports interpolateexpressions. Transitionable. A multiplier for the color of the ambient light.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
Flat
A global directional light source which is only applied on 3D and hillshade layers. Using this type disables other light sources. See the following flat lighting for available configuration options. Specifying a light with type flat is equivalent to specifying it as a root-level light property.
Flat lighting
A style’s light property provides a global light source for that style. Since this property is only used to light extruded or terrain features, you will only see visible changes to your map style if you are using extrusions or terrain.
lights property, the root-level light property will be ignored.flat light type instead in the lights API if all your clients support it. It takes the same properties as specified here."light": {
"anchor": "viewport",
"color": "white",
"intensity": 0.4
}
anchor
Whether extruded geometries are lit relative to the map or viewport.
"map":The position of the light source is aligned to the rotation of the map.
"viewport":The position of the light source is aligned to the rotation of the viewport.
"map"
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 |
color
Color tint for lighting extruded geometries.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 |
intensity
0 and 1 inclusive. Defaults to 0.5. Supports interpolateexpressions. Transitionable. Intensity of lighting (on a scale from 0 to 1). Higher numbers will present as more extreme contrast.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 |
position
[1.15,210,30]. Supports interpolateexpressions. Transitionable. Position of the light source relative to lit (extruded) geometries, in [r radial coordinate, a azimuthal angle, p polar angle] where r indicates the distance from the center of the base of an object to its light, a indicates the position of the light relative to 0° (0° when light.anchor is set to viewport corresponds to the top of the viewport, or 0° when light.anchor is set to map corresponds to due north, and degrees proceed clockwise), and p indicates the height of the light (from 0°, directly above, to 180°, directly below).
[
1.5,
90,
80
]
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
|---|---|---|---|
basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 |