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.

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 markerColorproperty 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.

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.

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:

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.

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:

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.