XYZ Maps Documentation
    Preparing search index...

    Class TerrainTileLayerStyle

    Configuration style for a 3D terrain tile layer.

    This class controls the visual appearance of terrain tiles, including vertical exaggeration, lighting, material properties, and sky background color. It extends the regular processed layer style so it can be used directly as both the style definition and style manager. Debug wireframes are configured through showWireframe on the individual terrain styles in styleGroups, not on the layer style itself.

    It can be passed to the style field of TerrainTileLayerOptions.

    Index
    constructor
    altitude backgroundColor? lights
    assign setMaterial

    • Creates a new instance of TerrainTileLayerStyle.

      Parameters

      • style: {
            backgroundColor?:
                | Color
                | StyleZoomRange<Color>
                | StyleExpression<Color>
                | ((zoomlevel: number) => Color);
            colorSource?:
                | { type: "material" }
                | { color: Color; type: "solid" }
                | { layerId: string; type: "layerBackground" };
            exaggeration?: number;
            light?: (AmbientLight | DirectionalLight)[];
            material?: Material;
            skyColor?:
                | Color
                | StyleZoomRange<Color>
                | StyleExpression<Color>
                | ((zoomlevel: number) => Color)
                | LinearGradient;
        } = {}

        Optional configuration object for terrain style parameters.

        • OptionalbackgroundColor?:
              | Color
              | StyleZoomRange<Color>
              | StyleExpression<Color>
              | ((zoomlevel: number) => Color)

          Defines the background color of the terrain layer, shown when terrain data is not fully loaded.

        • OptionalcolorSource?:
              | { type: "material" }
              | { color: Color; type: "solid" }
              | { layerId: string; type: "layerBackground" }

          Controls how the terrain surface is colored.

          The color source defines the base color (albedo) of the terrain mesh before lighting is applied.

          This property is independent of backgroundColor, which is only used when terrain data is missing or not yet rendered.

          • { type: 'material' } Uses the diffuse color defined by the terrain material. This is the default behavior.

          • { type: 'solid', color } Uses a single, solid color for the entire terrain surface. Lighting is still applied, but the base color is constant.

          • { type: 'layerBackground', layerId } Uses the background color of another layer as the terrain surface color. Typically used when visual data from another layer is rendered offscreen and projected onto the terrain.

            If the referenced layer is not available or not yet rendered, its backgroundColor is used as a fallback.

          { type: 'material' }

        • Optionalexaggeration?: number

          Elevation scale multiplier applied during rendering. This visually scales the terrain heights (e.g. 1 = real scale, 2 = double vertical exaggeration).

          Also known as "vertical exaggeration". Has no effect on the actual height data.

          1
        • Optionallight?: (AmbientLight | DirectionalLight)[]

          Lights to illuminate the terrain surface.

          Can include ambient and directional lights to control shading effects. If omitted, a default terrain light setup is used, which is just a simple ambient light (no directional lights).

        • Optionalmaterial?: Material

          Material properties applied to the terrain mesh.

          This defines visual attributes such as color, shading, or roughness, depending on the renderer's material model.

        • OptionalskyColor?:
              | Color
              | StyleZoomRange<Color>
              | StyleExpression<Color>
              | ((zoomlevel: number) => Color)
              | LinearGradient

          Defines the sky color of the map LayerStyle.skyColor

      Returns TerrainTileLayerStyle

    altitude: boolean

    Default altitude mode for all styles in this layer. Individual styles can override this setting by specifying their own altitude value.

    Possible values:

    • 'terrain': Styles follow the terrain elevation if available (default).
    • true: Styles use absolute height if provided be feature geometry.
    • false: Styles are rendered at the ground plane
    false
    backgroundColor?:
        | Color
        | StyleZoomRange<Color>
        | StyleExpression<Color>
        | ((zoomlevel: number) => Color)

    Specifies the background color of the layer.

    Only the background color of the layer at index 0 is used as the map background. It takes precedence over the map background color, including subsequent changes using Map.setBackgroundColor(). If the layer at index 0 has no background color, or the map has no layers, the current map background color is used. Background colors of layers at higher indices are not used as a fallback.

    This property can accept different types of values to determine the background color:

    • A fixed Color.
    • A StyleZoomRange<Color> object to define color based on zoom levels.
    • A function (zoomlevel: number) => Color to compute the color dynamically based on the zoom level.
    • A StyleExpression<Color> to compute the color using a style expression.
    lights: { [name: string]: (AmbientLight | DirectionalLight)[] } = {}

    The lights property specifies a collection of light sources that can be used to illuminate features within the layer. It is a map where each key is a unique light group name, and the value is an array of light objects. Lights can be of various types, including AmbientLight and DirectionalLight, and can be used to create different lighting effects.

    The lights property allows you to define and organize multiple light sources that influence the rendering of features in the layer.

    • Key (string): A unique identifier for the light group.
    • Value (array): An array of light objects, which can be of type AmbientLight or DirectionalLight.
    • Style.light: Specifies which single light group to use for illuminating a specific feature. This property must reference a key defined in LayerStyle.lights.
    • Default Light: If a FeatureStyle does not specify a light, the light group associated with the "defaultLight" key in LayerStyle.lights will be used. If "defaultLight" is not defined, a default light will be automatically provided.
    • Only One Light Group: Only one light group is used to illuminate a feature. This is either the group specified in FeatureStyle.light, or if not specified, the "defaultLight" group from LayerStyle.lights.
    • Override Default Light: To override the default light, set it explicitly in LayerStyle.lights under the key "defaultLight".
    {
      lights: {
         // Define a light group named "default" to override the default lighting for the layer
       "defaultLight": [{
           type: 'ambient',
           color: '#fff',
           intensity: 0.3
       }, {
           type: 'directional',
           color: '#fff',
           direction: [0, 0, 1],
           intensity: 1.0
       }, {
           type: 'directional',
           color: '#fff',
           direction: [-1, 0, 0],
           intensity: 0.2
       }],
       // Define a light group named "buildingLights" for specific features
        "buildingLights": [
          { type: "ambient", color: "#fff", intensity: 1.0 } // A simple ambient light source for buildings
        ]
      }
    }

    In the example above:

    • "defaultLight" is a light group that overrides the standard lighting configuration. It includes both an ambient and a directional light source and is used for all illuminated FeatureStyle instances where the light property is not explicitly set.
    • "buildingLights" is a light group containing only an ambient light source. This group will only be used for features where Style.light is set to "buildingLights".
    • Each light source can be customized with properties such as color, intensity, and, for DirectionalLight, a direction vector.

    The lights specified here will be applied to the rendering of features within the layer. However, only one light group will be used for each feature:

    • If Style.light is defined, it will reference a specific light group in LayerStyle.lights.
    • If Style.light is not defined, the "defaultLight" light group (if specified) will be used.
    • If no "defaultLight" light group is set, an automatic default light will be provided.

    • The function returns a key that is defined in the styleGroups map. This function will be called for each feature being rendered by the display. The display expects this method to return the key for the styleGroup of how the feature should be rendered for the respective zoomlevel.

      If assign is not defined, the Style.filter property must be used to determine whether the feature should be rendered.

      Parameters

      • feature: Feature

        the feature to which style is applied

      • Optionallevel: number

      Returns string

      the key/identifier of the styleGroup in the styleGroupMap, or null/undefined if the feature should not be rendered.

    • Updates the terrain material values that can be changed without rebuilding terrain buffers.

      Parameters

      • materialUpdate: Partial<Pick<Material, "specular" | "shininess">>

        The live specular color and/or shininess values.

        Call display.refresh() after changing the material to render the new values.

      Returns void

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods