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.

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 }
      ]
    }
  ]
});

TODO: a note on the theme.js plugin that overrides colorBands. The plugin could expose the lightColorBands and darkColorBands or something.

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:

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:

lightness

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

saturation

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

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:

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.