Docs
`/`

# API elements

No matching results

# Sections and content

No matching results

- `Enter` to go to the highlighted result.
- `↑` and `↓` to change highlight.
- `Tab` to switch between result lists.
- `Esc` to hide the results.

# Elevations layer API

This reference describes the elevations layer API.

The elevations layer serves as the background for the whole visualization and renders the map-like image of "hills" and "valleys", along with elevation contours and light shading:

The point objects you provide in the `points` property, in addition to the `x` and `y` coordinates must define the point's elevation in the `elevation` property.

You can create an example elevations layer using the following code:

    const elevations = DotAtlas.createLayer({
      points: [],
      type: "elevation",
      lightIntensity: 0.15
    });

See the following documentation for all the point and layer properties you can use.

##
Point properties

###
elevation

Defines the elevation (altitude) of the point, required.

Elevation values must be in the `0.0` – `1.0` range, where `0.0` is no elevation and `1.0` is peak elevation. Values outside of this range will be clamped to the required range.

When you mutate the `elevation` property of a specific point object, call the `update()` and then the `redraw()` method to see the changes on the screen.

##
Layer properties

###
colorBands

Determines the colors used to draw the elevation bands and the number of bands.

Values of this property must be an array of JavaScript literal objects. Each object defines one elevation band and must contain the following properties:

end

  The upper bound of the elevation range covered by this band, must fall in the `0.0` – `1.0` range. Note that the lower bound of the range is defined by the upper bound of the previous band or is `0.0` for the first band in the array.

color

  The color in which to draw the band.

shading

  Set to `true` to apply hill shading when rendering this band. If this property is not provided, shading will not be applied. The default dotAtlas color bands don't apply shading to the blue "sea" bands and do apply shading to the "land" bands.

contours

  When `true` or not provided, a contour line will be drawn between this and the next band in the array. The default dotAtlas color bands don't draw contours between the blue "sea" bands and do draw contours between the "land" bands.

The following example defines five green-to-red heatmap-style bands, all with contours and without hill shading.

    const dotatlas = DotAtlas.embed({
      "element": element,
      "layers": [
        {
          "type": "elevation",
          "colorBands": [
            { "end": 0.005, "color": "hsl(90, 70%, 60%)" },
            { "end": 0.050, "color": "hsl(70, 70%, 60%)" },
            { "end": 0.200, "color": "hsl(50, 70%, 60%)" },
            { "end": 0.500, "color": "hsl(30, 70%, 60%)" },
            { "end": 1.000, "color": "hsl(10, 70%, 60%)" }
          ],
          "points": [
            { "x":  0, "y": 0, "elevation": 1.0 }
          ]
        }
      ]
    });

The Theme plugin uses this property to add map colors suitable for dark mode UIs.

###
contourOpacity

Opacity of contour lines between elevation bands on this layer. If set to `0.0`, contours will not be drawn at all.

###
contourWidth

Width of contour lines between elevation bands on this layer, in pixels. A reasonable range of contour widths is `0.5`–`2.5`. If set to `0.0`, contours will not be drawn at all.

###
lightIntensity

Intensity of the hill shading light source. Values in the `0.0` – `1.0` are accepted, where `0.0` means no light and no hill shading.

###
lightAzimuth

The angular direction from which the hill shading light comes.

Values of this property will be treated as an angle in radians. Assuming `lightAltitude` is `0`, mapping between `lightAzimuth` and geographical directions is the following:

`lightAzimuth` | Light direction
`0` | West
`Math.PI / 4` | South-West
`Math.PI / 2` | South
`3 * Math.PI / 4` | South-East
`Math.PI` | East
`5 * Math.PI / 4` | North-East
`3 * Math.PI / 2` | North
`7 * Math.PI / 4` | North-West

###
lightAltitude

Altitude of the hill shading light source above the ground. Values of this property will be treated as an angle in radians, for example:

`lightAltitude` | Light position
`0` | On the ground level, "sunrise".
`Math.PI / 4` | Directly above the ground, "noon". Note that hill shading will not be visible in this setting.
`Math.PI / 2` | On the ground level, "sunset". Note that this setting reverses the example light directions provided in the `lightAzimuth` property documentation.

###
lightness

Lightness correction for the whole layer. Correction values must fall in the `-1.0` ... `1.0` range and result in the following corrections:

Value | Correction
--- | ---
`-1.0` | Zero lightness, all colors black.
`-1.0` ... `0.0` | Lowered lightness.
`0.0` | No correction.
`0.0` ... `1.0` | Increased lightness.
`1.0` | Maximum lightness, all colors white.

###
saturation

Saturation correction for the whole layer. Correction values must fall in the `-1.0` ... `1.0` range and result in the following corrections:

Value | Correction
--- | ---
`-1.0` | Zero saturation, greyscale.
`-1.0` ... `0.0` | Lowered saturation.
`0.0` | No correction.
`0.0` ... `1.0` | Increased saturation.
`1.0` | Maximum saturation.

###
maxElevationPoints

The maximum number of points from the `points` to consider when drawing elevations.

The elevations layer can be costly to draw, especially when the number of elevation points is large. In some cases it may be beneficial to allow the users to balance the rendering performance and the amount of detail on their maps.

You can use the `maxElevationPoints` property to render fewer elevation points than provided in the `points` array. If you sort the elevation points in the decreasing order of elevation, lowering `maxElevationPoints` below the length of the points array will discard the least important information.

###
maxRadius

Determines how much of "land" each elevation point generates. The larger the value, the more "land" generated. The smaller the value, the more "islandy" the map.

In most cases, the reasonable range of `maxRadius` values will be `0.1` ... `2.0`. Please note that large `maxRadius` values may slow down rendering of the elevations layer.

###
elevationPow

Determines the sharpness of each elevation peak.

This property is the power to which to raise each point's elevation value before rendering:

    const renderedElevation = Math.pow(point.elevation, elevationPow);

The impact of this property on elevation peaks is the following:

`elevationPow` | Impact on elevations
--- | ---
`0` ... `1.0` | Flattens the peaks
`1.0` | No correction
`1.0` and more | Sharpens the peaks

###
maxElevation

Returns the current maximum elevation value, that is the altitude of the highest peak on the map.

While the range of elevation values for individual points is `0.0` ... `1.0`, the range elevation values across the whole map will be larger than `1.0` because elevations of points in the same area add up.

You can read this property to get the elevation value of the currently highest point on the map. The maximum elevation value may be useful as a normalization factor when, for example, building map legend.

###
elevationAt

Returns the elevation value at the specified element space coordinate of the map:

    dotatlas.on("mouseMove", e => {
      const elevationsLayer = dotatlas.get("layers")[0];
      const elevationAtMouseLocation =
          elevationsLayer.get("elevationAt", e.elementX, e.elementY);
    });

###
elevationAt

Controls pre-filtering of the elevation values before upsampling, enabled by default.

Pre-filtering improves the rendering accuracy of small isolated point islands. However, on small zoom levels, pre-filtering may result in small "fringing" artifacts.

##
Events

###
onMaxElevationChanged

Triggered when the maximum elevation value has changed. The change may be result of some of the elevation layer property changes or a change in point elevations.

The event listener will be called with one parameter equal to the current maximum elevation value:

    elevationsLayer.on("maxElevationChanged", maxElevation => {
      // Use the new maxElevation value
    });

This event may be useful when your code somehow depends on knowing the maximum elevation value, for example to normalize elevation values to the 0...1 range for legend display purposes.

###
onColorBandsChanged

Triggered when new `colorBands` have been set.

This event may be useful when implementing map legend display to follow the changes of the elevations layer color bands.

previous article
Common layer API
next article
Markers layer API