メインコンテンツまでスキップ

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
Required string .

Unique light name.

properties
Optional properties .

Properties of the light.

type
Optional enum . One of "ambient", "directional", "flat".

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 SupportMapbox GL JSAndroid SDKiOS 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
Optional boolean . Defaults to false.

Enable/Disable shadow casting for this light

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.0.0>= 11.0.0>= 11.0.0
color
Optional color . Defaults to "#ffffff". Supports smooth-rampinterpolateexpressions. opacityTransitionable.

Color of the directional light.

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.0.0>= 11.0.0>= 11.0.0
direction
Optional array of numbers [ between 0 and 360 inclusive, between 0 and 90 inclusive ]. Defaults to [210,30]. Supports smooth-rampinterpolateexpressions. opacityTransitionable.

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 SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.0.0>= 11.0.0>= 11.0.0
intensity
Optional number between 0 and 1 inclusive. Defaults to 0.5. Supports smooth-rampinterpolateexpressions. opacityTransitionable.

A multiplier for the color of the directional light.

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.0.0>= 11.0.0>= 11.0.0
shadow-intensity
Optional number between 0 and 1 inclusive. Defaults to 1. Supports smooth-rampinterpolateexpressions. opacityTransitionable.

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 SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.0.0>= 11.0.0>= 11.0.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
Optional color . Defaults to "#ffffff". Supports smooth-rampinterpolateexpressions. opacityTransitionable.

Color of the ambient light.

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.0.0>= 11.0.0>= 11.0.0
intensity
Optional number between 0 and 1 inclusive. Defaults to 0.5. Supports smooth-rampinterpolateexpressions. opacityTransitionable.

A multiplier for the color of the ambient light.

SDK SupportMapbox GL JSAndroid SDKiOS 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.

Deprecated
If your style has a 3D lights property, the root-level light property will be ignored.
Deprecated
Prefer using 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

Optional enum . One of "map", "viewport". Defaults to "viewport".

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 SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.27.0>= 5.1.0>= 3.6.0

color

Optional color . Defaults to "#ffffff". Supports smooth-rampinterpolateexpressions. opacityTransitionable.

Color tint for lighting extruded geometries.

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.27.0>= 5.1.0>= 3.6.0

intensity

Optional number between 0 and 1 inclusive. Defaults to 0.5. Supports smooth-rampinterpolateexpressions. opacityTransitionable.

Intensity of lighting (on a scale from 0 to 1). Higher numbers will present as more extreme contrast.

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.27.0>= 5.1.0>= 3.6.0

position

Optional array of numbers . Defaults to [1.15,210,30]. Supports smooth-rampinterpolateexpressions. opacityTransitionable.

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 SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.27.0>= 5.1.0>= 3.6.0
このpageは役に立ちましたか?