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.

# Common layer API

All dotAtlas layers share some common API methods and properties. This part of the reference describes them in detail.

##
Point properties

###
x, y

The x and y coordinate of the point, required.

There are no constraints on the coordinate values, so you can use a coordinate system that makes the most sense for your data. dotAtlas will ensure that the initial view includes all points from all layers.

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

##
Layer properties

###
points

The array of 2d points to display on this layer.

Each point is represented by a JavaScript object with the mandatory `x` and `y` properties. Specific layer types require other properties to be present in the point object, such as the `elevation` property in the elevations layer or the `markerColor`property in the markers layer.

When different layers share points of the same coordinates, for example when elevations, markers and labels need to be drawn for each point, you can set the same array of points for all layers.

###
visible

Determines if this layer is visible. Set this property to `false` to hide the layer. When a layer is hidden, its layer-specific events, such as `onPointClick` will not be triggered.

###
opacity

Opacity level of this layer.

The default opacity value is `1.0`, which will render a fully opaque layer. A value of `0.0` will hide the layer. If the layer's opacity is `0.0`, its layer-specific events, such as `onPointClick` will still be triggered.

###
pointHoverRadiusMultiplier

How much the point's active area should be larger than the actual point.

To improve usability of point-related events, the point's active area can be made larger than its on-screen size. This property determines what the scaling factor should be.

##
Events

###
onPointHover

Triggered when the user hovers over a specific point of this layer, when the mouse pointer moves to an area without points or moves out of the visualization area completely.

In addition to the common event details properties, this event comes with the following additional properties:

points

  An array of point objects hovered by the user. The array may contain zero, one or more points. In case the array contains more than one point, the points will be sorted in the increasing distance from the mouse pointer location.

###
onPointClick

Triggered when the user clicks on a specific point of this layer.

In addition to the common event details properties, this event comes with the following additional properties:

points

  An array of point objects clicked by the user. The array may contain one or more points. In the latter case, the points will be sorted in the increasing distance from the mouse pointer location.

###
onPointDoubleClick

Triggered when the user double-clicks on a specific point of this layer.

In addition to the common event details properties, this event comes with the following additional properties:

points

  An array of point objects double-clicked by the user. The array may contain one or more points. In the latter case, the points will be sorted in the increasing distance from the mouse pointer location.

###
onPointHold

Triggered when the user clicks and holds mouse button on a specific point of this layer.

In addition to the common event details properties, this event comes with the following additional properties:

points

  An array of point objects click-and-held by the user. The array may contain one or more points. In the latter case, the points will be sorted in the increasing distance from the mouse pointer location.

##
Methods

###
update()

Notifies dotAtlas that some property has been changed for some of the points of this layer. Upon the next redraw, dotAtlas will refresh its external buffers and reflect the change on the screen.

    layer.update(prop);

The following `prop` parameter values are supported:

`prop` parameter | layer type | use when...
--- | --- | ---
`xy` | all types | you change point coordinates represented by the `x` and `y` point properties.
`elevation` | elevation | point's `elevation` property changes.
`markerColor` | marker | point's `markerColor` property changes.
`markerOpacity` | marker | point's `markerOpacity` property changes.
`markerSize` | marker | point's `markerSize` property changes.
`markerShape` | marker | point's `markerShape` property changes.
`labelColor` | label | point's `labelColor` property changes.
`labelOpacity` | label | point's `labelOpacity` property changes.
`labelBoxColor` | label | point's `labelBoxColor` property changes.
`labelBoxOpacity` | label | point's `labelBoxOpacity` property changes.
`labelVisibilityScales` | label | you change label point `x` or `y` properties or visualization container size changes. This will ensure that dotAtlas recomputes label layout so that the labels don't overlap.
`markerSize` | outline | point's `markerSize` property changes.

The typical workflow for updating point properties will look like this:

    const markers = dotatlas.get("layers")[0];
    const points  = markers.get("points");

    points[0].x += 0.1;
    points[0].y += 0.1;
    points[0].markerSize *= 1.2;

    points.update("xy");
    points.update("markerSize");
    dotatlas.redraw();

Note that if several layers share the same point instances, you still need to notify each involved layer about the changed properties:

    const points = [
      { x: 0.0, y: 0.0, elevation: 0.5 },
      { x: 0.0, y: 0.5, elevation: 0.3 }
    ];

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

    const markers = DotAtlas.createLayer({
      "type": "marker",
      "points": points
    });

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

    points[0].x += 0.1;
    points[0].y += 0.1;
    points[0].elevation += 0.1;

    elevations.update("elevation");
    elevations.update("xy");
    markers.update("xy");

###
within()

Computes points lying within the requested 2d circle.

A group of points obtained from the `circle()` method. The start point is marked with the mouse pointer. The method includes all points lying within a certain distance from the start point. Therefore, isolated within-circle points can also be included in the group. Compare how the `cluster()` method returns a different set of points based on the same start point.

    const withinCircle = await layer.within(params);

This method returns a `Promise` resolving to the array of points inside the circle.

The `params` literal object contains the definition of the circle:

`startX`, `startY`

  Coordinates of the center of the circle. The coordinates must be in the same space as coordinates of the layer's points.

`radius`

  Circle radius, relative to the dimension of the bounding box of the point's layer, `0.05` by default. The dimension of the bounding box is assumed to be the minimum of the box width and height.

  For example, if the point's bounding box is a `2.5` x `2.0` rectangle, and `radius` is `0.1`, then all points within the distance of `0.2` from the center will be returned.

`sortByDistance`

  If `true`, the returned points will be sorted by the increasing distance to the center. If this property is not defined, `false` will be assumed and points will be returned in an arbitrary order.

You can use this method to build a simple mechanism for selecting multiple points at once. Alternatively, use the `cluster()` method to find non-circular density-based clusters of nearby points.

The typical invocation looks like this:

    const markers = dotatlas.get("layers")[1];
    const points = await markers.within({
      "startX": 0.2,
      "startY": 0.5
    });
    console.log(`${points.length} point(s) found.`);

###
cluster()

Computes a density-based cluster of nearby points around some start point:

A cluster of points obtained from the `cluster()` method. The start point is marked with the mouse pointer. Notice how the cluster is asymmetrical and follows the density of the markers. Non-connected outlier points are not included in the cluster. Compare how the `within()` method returns a different group of points based on the same start point.

    const cluster = await layer.cluster(params);

This method returns a `Promise` resolving to the array of points in the cluster.

The `params` literal object contains parameters for the clustering algorithm:

`startX`, `startY`

  Coordinates of the start point from which to build the cluster. If the point lies inside a densely-populated area, most points in that area will be included in the cluster. If the point does not have any neighbors, the cluster will contain only that point.

`radius`

  Defines the desired size of the cluster, `0.4` by default. The larger the radius, the larger the cluster. In most cases, a value from the `0...1` range will produce the best results. In an interactive selection scenario, you can let the user change the size and dynamically re-compute and present the cluster.

`maxClusterRadius`

  Defines the maximum allowed cluster radius, relative to the bounding box of all points in the layer, `0.1` by default. The limit on the maximum cluster radius prevents a situation where all points in the layer are included in the cluster.

You can use this method to build a mechanism for selecting entire regions of related points on the map. As opposed to the `within()` method, this method will usually return non-circular clusters that match the densely-populated region around the start point.

See the implementation of the Selection plugin for example invocations of this method.

previous article
DotAtlas API
next article
Elevations layer API