/

Defining layers

dotAtlas displays sets of points organized into layers. This article shows how to define a layer and describes all the layer types you can use.

Layer definition

A dotAtlas layer is defined by a literal object containing a number of common and layer-specific properties, for example: 

const elevationLayerDefinition = {
  "type": "elevation",
  "points": [
    { "x":  0, "y": 0, "elevation": 1.0 },
    { "x": -1, "y": 0, "elevation": 0.8 },
    { "x":  0, "y": 1, "elevation": 0.5 }
  ],
  "visible": true,
  "opacity": 0.7,
  "lightIntensity": 0.2,
  "contourWidth": 1.0,
  "onPointClick": e => {
    // do something
  }
};

Two mandatory properties are type and points. The type property determines the layer type, such as elevation, marker or label. The points property is an array of objects defining the 2d points to display. Each point object must contain the x and y properties defining the coordinates. Additional properties, such as elevation, label or markerColor, will be layer-specific.

See the Common layer API and specific layer API references, such as Elevations layer API, for a complete list of available properties.

Layer creation

To display your layers, pass the layer definition objects to dotAtlas in the layers option. You can pass the option during embedding and also later on using the set() method: 

const points = [
  { x:  0, y: 0,  elevation: 1.0, label: "Central peak" },
  { x: -1, y: 0,  elevation: 0.6, label: "West peak" },
  { x:  1, y: 0,  elevation: 0.6, label: "East peak" },
  { x:  0, y: -1, elevation: 0.4, label: "North peak" },
  { x:  0, y: 1,  elevation: 0.4, label: "South peak" },
];

const dotatlas = DotAtlas.embed({
  "element": element,
  "layers": [
    { "points": points, "type": "elevation" },
    { "points": points, "type": "marker", "markerColor": "rgb(255, 0, 0)" },
    { "points": points, "type": "label" }
  ]
});

The layers you provided in the layers property will be stacked in the order they appear in the array, bottom-up. In the above example, the elevations layer will come at the bottom, the markers layer will come in the middle and the labels layer will be at the top.

Note that if different layers share points of the same coordinates, for example when elevations, markers and labels need to be drawn for each point, layers can share one array of points like in the above example. In many cases a convenient way to organize input data is to have a single array of points, and for each layer supply a filtered version of the array narrowed down to the specific point types.

Once connected to dotAtlas, each layer is converted to an API-bearing object you can use to modify layer properties or event listeners at runtime. When you get() the layers property, instead of the input definitions, you'll get an array of layer implementation objects. They define the common API methods to modify layer properties or manage event listeners: 

const elevationsLayer = dotatlas.get("layers")[0];
elevationsLayer.set("lightIntensity", 0.3);
dotatlas.redraw();

elevationsLayer.once("maxElevationChanged", e => {
  // do something
});

You can also create layer implementation objects directly using the DotAtlas.createLayer() method: 

const elevations = DotAtlas.createLayer({
  "type": "elevation",
  "points": [
    { "x":  0, "y": 0, "elevation": 1.0 },
    { "x": -1, "y": 0, "elevation": 0.8 },
    { "x":  0, "y": 1, "elevation": 0.5 }
  ],
  "lightIntensity": 0.2,
  "contourWidth": 1.0
});
elevations.on("click", e => {
  // do something
});

const dotatlas = DotAtlas.embed({
  "element": element,
  "layers": [
    elevations
  ]
});

Both layer creation styles are equivalent, choose the one that better suits your specific code or preference.

Layer types

dotAtlas currently offers layers of 4 types: elevations, markers, labels and outlines. This section describes the layers in more details.

Elevations

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:

dotAtlas elevation layer.

To create an elevations layer, set the type property to elevation, provide coordinates at which elevation "peaks" should be created and define the height of each peak in the elevation property: 

const elevations = {
  "type": "elevation",
  "points": [
    { "x":  0, "y": 0, "elevation": 1.0 },
    { "x": -1, "y": 0, "elevation": 0.8 },
    { "x":  0, "y": 1, "elevation": 0.5 }
  ],
  "contourWidth": 1.0
}

Notes:

  • dotAtlas will allow at maximum one elevation layer, it must come at index 0 of the array passed in the layers property, which will put it at the bottom of the layer stack.

  • Elevation values must be in the 0...1 range, other values will be clamped to that range.

See the Elevation layer API for a list of all properties and events of this layer type.

For the curious: how dotAtlas creates the "hills" and "valleys"

dotAtlas generates the map like this: each point rises the elevation at a certain circle around the point's coordinates:

Heightmap created around a single elevation point.

The radius of the circle depends on the elevation value you define in the data, the larger the elevation, the larger the radius. Additionally, to avoid "sharp edges", the elevation around the point falls of along a Bezier curve rather than, for example, linearly. When there are multiple elevation points in the input data, their elevation circles add up. When the number of points is large enough, a visually-pleasing map emerges.

Note that elevation values computed in this way are only a very rough approximation of the elevation point density around the area in question.

Markers

The markers layer draws small shapes at the coordinates of the points you provide. You can define the size, color, shape and opacity of each individual marker:

dotAtlas markers layer.

The simplest use case of the markers layer is to show the locations of points on your map. You can use various marker properties, such as color, opacity or size, to represent specific properties of the object the point represents. For example, when visualizing a set of textual documents, color may represent the document's category and size may be proportional to the relevance to the user's query.

Since dotAtlas can display multiple marker layers, another common use case is to have an extra makers layer for highlighting selected or hovered markers.

To create a markers layer, set the type property to marker and provide coordinates at which to display markers. Optionally, you can provide extra per-point properties, such as color or size: 

const markers = {
  "type": "marker",
  "points": [
    { "x":  0, "y": 0, "size": 1.0, "color": "rgb(255, 0, 0)" },
    { "x": -1, "y": 0, "size": 0.8, "color": "rgb(0, 255, 0)" },
    { "x":  0, "y": 1, "size": 0.6, "color": "rgb(0, 0, 255)" }
  ],
  "markerSizeMultiplier": 20
}

Notes:

  • By default, the maximum size of a single point is about one pixel. Use the markerSizeMultiplier layer property to provide the scaling factor. For example, when the multiplier is set to 20, markers of size 1.0 will be about 20 pixels large.

  • A single visualization can display multiple markers layers.

See the Marker layer API for a list of all properties and events of this layer type.

Labels

The labels layer draws short fragments of text at the specified 2d coordinates:

dotAtlas labels layer.

The primary use case for this layer type is to describe specific areas of the map. The textual labels will usually be relevant to a group of nearby markers or elevation points.

To create a markers layer, set the type property to label and provide coordinates and labels to display: 

const labels = {
  "type": "label",
  "points": [
    { "x":  0, "y": 0, "label": "Center", "labelBoxOpacity": 1.0 },
    { "x": -1, "y": 0, "label": "Left" },
    { "x":  0, "y": 1, "label": "Right" }
  ]
}

Notes:

  • The pre-release versions are limited to a maximum of five words per single point label. The production release will lift this limitation.

  • You can set the labelBoxOpacity property for a point to a non-zero value to draw a box around the label. You can customize the color of the box using the labelBoxColor point property.

See the Label layer API for a list of all properties and events of this layer type.

For the curious: how dotAtlas determines which labels to show

dotAtlas draws only those labels that do not overlap any other labels. This means that at a certain zoom level only a limited number of labels will be revealed. As the zoom level increases, more labels located in the zoomed area will show.

To control which labels show first, you can set the labelPriority of the point. If label priorities are provided, dotAtlas will place labels in the decreasing order of priority.

Outlines

The outline layer draws circular highlights around groups of points:

dotAtlas outline layer.

The primary use case of this type of layer is to temporarily highlight a set of points, for example to show that the points are selected. An extra temporary markers layer can be drawn on top of the outline to further emphasize the points.

To create a markers layer, set the type property to outline and provide coordinates which should be outlined. Optionally, you can provide the relative outline size to create for specific points. 

const outline = {
  "type": "outline",
  "points": [
    { "x":  0, "y": 0, "size": 1.0 },
    { "x": -1, "y": 0, "size": 0.8 },
    { "x":  0, "y": 1, "size": 0.6 }
  ],
  "outlineSizeMultiplier": 20,
  "outlineOffset": 10
}

Notes:

  • By default, the maximum size of a single outlined point is about one pixel. Use the outlineSizeMultiplier layer property to provide the scaling factor. For example, when the multiplier is set to 20, dotAtlas will assume that the points to outline have the radius of 20 pixels.

  • A single visualization can display multiple outline layers.

See the Outline layer API for a list of all properties and events of this layer type.