element

A reference to the HTML into which to embed dotAtlas. A non-empty element property must be provided when calling DotAtlas.embed():

const dotatlas = DotAtlas.embed({
  element: document.querySelector("#visualization")
});

layers

An array of map layers to display.

Each element of the array must be either a layer specification object or a layer instance created using the DotAtlas.createLayer()method. The layers you provide will be stacked in the order they appear in the array, bottom-up.

Once passed to dotAtlas, each layer will be 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
});

See Defining layers for an overview of the layer definition and management process.

transform

The current 2d transform determining the zoom scale and translation offset.

The transform is represented by a literal object with the following properties:

translateX

Horizontal offset.

translateY

Vertical offset.

scale

Scale factor.

The initial transform is { translateX: 0, translateY: 0, scale: 1 }, which brings all points in all layers into view. When the layers property is set, the transform also gets automatically reset to the initial value.

To start the visualization with a non-default transform, set the desired values along with the layers property. The following code initializes the visualization to a non-default transform. After a short delay, it increases the zoom level even further.

const dotatlas = DotAtlas.embed({
  "element": document.getElementById("dotatlas"),
  "layers": [
    {
      "type": "elevation",
      "points": [{ "x": 0, "y": 0, "elevation": 1 }]
    }
  ],
  "transform": {
    "translateX": -300,
    "translateY": -200,
    "scale": 2
  }
});

window.setTimeout(() => {
  dotatlas.set("transform", {
    "translateX": -900,
    "translateY": -600,
    "scale": 4
  });
  dotatlas.redraw();
}, 1000);

maxZoomScale

The maximum zoom scale dotAtlas will allow to set.

The supplied value will be rounded down to the nearest power of 2. The default value is the scale at which rendering artifacts related to limited precision of floating point computations start showing up.

pixelRatio

Determines the pixel density of the visualization.

The default value of auto causes dotAtlas to use the devicePixelRatio value reported by the browser. With the auto value, dotAtlas adapts to dynamic changes to device pixel ratio values caused by browser viewport zoom level changes.

You can override the default pixel density by providing a floating point value, such as 1.0, 1.5 or 2.0 in this property. A higher pixel density value can improve clarity in high-resolution displays but may adversely affect performance.

We recommend keeping the auto value of the pixelRatio property to ensure the best rendering across different devices and browser viewport zoom levels.

boundingBox

The bounding box of the points in the visualization.

The bounding box is an object with the following properties. Values of all properties are in layer space.

x

The left edge of the bounding box.

y

The top edge of the bounding box.

w

The width of the bounding box.

h

The height of the bounding box.

The bounding box determines the set of points visible in the non-zoomed viewport.

If you don't provide the bounding box when initializing the visualization, dotAtlas computes the bounding box automatically, taking into account all points across all layers. Getting the boundingBox property returns the bounding box dotAtlas computed.

One reason you may want to provide your own bounding box instead of using the automatically computed one is when you incrementally load and display a large dataset. In this case, you can initialize the bounding box right away and add points to the visualization as the data becomes available. Pre-setting the bounding box ensures that the viewport remains stable during data updates. See the Visualizing 1m points. demo for an implementation of this technique.

onClick

Called when the user clicks inside the visualization area. Listeners will be called with one parameter – the event details object.

If any listener prevents the default action of this event, the point-specific onPointClick listeners will not be called.

onDoubleClick

Called when the user double clicks inside the visualization area. Listeners will be called with one parameter – the event details object.

If any listener prevents the default action of this event, the point-specific onPointDoubleClick listeners will not be called.

onHold

Called when the user clicks and holds mouse button inside the visualization area. Listeners will be called with one parameter – the event details object.

If any listener prevents the default action of this event, the point-specific onPointHold listeners will not be called.

onMouseMove

Called when the mouse pointer hovers over the visualization area or leaves it. Listeners will be called with one parameter – the event details object.

If any listener prevents the default action of this event, the point-specific onPointHover listeners will not be called.

onMouseWheel

Called when the mouse wheel is rotated over the visualization area. Listeners will be called with one parameter – the event details object.

If any listener prevents the default action of this event, the default mouse-wheel-based zooming will not be performed.

onRedraw

Called after an internal- or API-triggered redraw of the visualization.

onDispose

Called after dispose() has been called but before dotAtlas element is removed from the DOM.

You can use this callback to clean up any custom event listeners registered on the dotAtlas DOM element. The AutoResizing plugin uses this callback to remove the window resize listener it registers.

DotAtlas.supported()

Returns true if the current platform meets all dotAtlas requirements.

dotAtlas will function properly if and only if this method returns true. If the method returns false, an attempt to embed dotAtlas will fail.

DotAtlas.embed()

Embeds dotAtlas into the provided DOM element.

const dotatlas = DotAtlas.embed(props)

Use the DotAtlas.embed() static method to embed dotAtlas into your page and pass initial layer data, property values and event listeners. The method returns the dotAtlas instance you can use to change layer data or properties.

This method accepts one parameter – a literal object containing the initial property values to use. You will most likely include there the element property to pass the HTML element into which to embed dotAtlas and the layersoption containing the map layers to display.

A typical invocation of this method will look like this:

const dotatlas = DotAtlas.embed({
  "element": document.getElementById("dotatlas"),
  "layers": [
    // layer specifications
  ],
  "onClick": e => {
    console.log("visualization area clicked", e);
  }
});

DotAtlas.createLayer()

Creates a dotAtlas layer instance.

const layer = DotAtlas.createLayer(spec)

The DotAtlas.createLayer() static method creates a layer instance based on the specification you provide.

The method accepts one parameter – a literal object containing the specification of the layer to create. The provided object must contain the type property that determines which specific layer to create. The following types are currently supported:

elevation

creates an elevations layer

marker

creates an markers layer

label

creates an labels layer

outline

creates an outline layer

The specification object will likely contain some of the common layer properties, such as points, and properties specific to the layer type.

To display the layers you created, pass the obtained instances in the layers property, for example when initializing dotAtlas.

const elevations = DotAtlas.createLayer({
  type: "elevation",
  points: [ /* some points */ ],
  maxRadius: 1
});
dotatlas.set("layers", [ elevations ]);

Additionally, you can use individual layer instances to modify properties of the layer after initialization.

layer.set("maxRadius", 0.7);
dotAtlas.redraw();

DotAtlas.with()

Returns the DotAtlas class extended with the provided plugins.

const DotAtlasWithPlugins = DotAtlas.with(plugin1, plugin2, ...);

Most of the time, you will chain the call to the with() method with the embed() method to create a dotAtlas instance with extra plugins enabled. Many of the plugins will expose additional options you can initialize when calling the embed() method and change later on.

import { DotAtlas, Theme, Effects } from "@carrotsearch/dotatlas";

const dotAtlas = DotAtlas.with(Theme, Effects).embed({
  "element": document.querySelector("#visualization"),
  "layers": [],
  "theme": "dark",
  "rollbackDuration": 3000
});

See the Using plugins article for the list of available plugins.

redraw()

Schedules a visualization redraw to happen in the next animation frame. If a redraw has already been scheduled but not yet preformed, this call does nothing.

This method returns a Promise, which gets resolved after the render completes.

dotatlas.redraw().then(() => {
  // do something when render is complete
});

You can also use the await syntax to ensure that some code executes after a redraw actually completed:

const redrawWithAwait = async () => {
  await dotatlas.redraw();
  // At this point redraw has completed.
};

resize()

Resizes and redraws the visualization to accommodate to the new size of the container element.

The invocation cost of this function is low, comparable with a single redraw(), so there is no need to throttle the calls made from, for example, the window's resize listener:

window.addEventListener("resize", () => {
  dotatlas.resize();
});

Heads up, overlapping labels.

After the container element shrinks by a large amount, a call to resize() alone may cause crowding and overlapping of labels.

Similarly, when the container element grows by a large amount, a call to resize() alone will spread the labels too much.

To correct this, you will need to force dotAtlas to recompute label display order to match the new container size:

const layers = dotatlas.get("layers");
const labelLayers = layers.filter(l => l.get("type") === "label");
for (let labelLayer of labelLayers) {
  labelLayer.update("labelVisibilityScales");
}
dotatlas.redraw();

Updating labelVisibilityScales may be costly for large data sets, so it's best to throttle the calls to the above code. The AutoResizing plugin combines all the necessary code in one place.

reset()

Resets the zoom level and offset back to the initial state, bringing all points into view.

By default, dotAtlas will also reset the view when the user presses Esc.

center()

Centres the view on the specified 2d coordinate.

dotatlas.center(x, y, scale, duration);

This method requires the following parameters:

x, y

The 2d coordinates to which to center the view. The coordinates must be expressed in the same space as the points in the layers being visualized.

scale

The zoom scale to apply when centering. If you are zooming to a small area of the map, using a scale value larger than 1 may help better present the area.

duration

Duration of the centering animation, in milliseconds.

The typical invocation of this method will be similar to:

const elevations = dotatlas.get("layers")[0];
const centerPoint = elevations.get("points")[0];
dotatlas.center(centerPoint.x, centerPoint.y, 4, 500);

layerToElementSpace()

Converts 2d coordinates from the layer space to the element space.

const pointInScreenSpace = dotatlas.layerToElementSpace(pointInLayerSpace)

The method requires one parameter: a 2d point object in the layer space to convert. The return value is the 2d point object converted to the element space.

Use this method when you need, for example, to show a HTML popup over a specific point in one of the layers. In this case, you'd pass the layer point to this method and get its screen coordinates.

Note that the screen coordinates of a layer point depend on the zoom level and offset. If the user zooms or pans the viewport, the screen coordinates will change. Moreover, if a point is outside of the current viewport, its coordinates will be smaller than zero or larger than the visualization element width and height.

elementToLayerSpace()

Converts 2d coordinates from the element space to the layer space.

const pointInLayerSpace = dotatlas.elementToLayerSpace(pointInElementSpace)

The method requires one parameter: a 2d point object in the element space to convert. The return value is the 2d point object converted to the layer space.

Use this method when you need, for example, to find layer points that lie close to the current mouse pointer position. In this case, you can convert the pointer's screen coordinates to the layer space and use the converted point to call the within() or cluster() method.

Note that the conversion result depends on the zoom level and offset. If the user zooms or pans the viewport, the conversion will produce a different result.

dispose()

Releases the resources allocated by the dotAtlas instance.

When you don't need a dotAtlas instance any more, call the dispose() method, so that dotAtlas can remove all the DOM elements it created and free the WebGL resources. Note that the DOM element you passed in the element property will not be removed from the DOM.

One typical use case for this method is when you use dotAtlas in a React component. When the component unmounts, you'll need to call dispose() to remove the internal DOM elements:

import React, { useEffect, useRef } from "react";
import { DotAtlas as DotAtlasImpl } from "@carrotsearch/dotatlas";

export const DotAtlas = () => {
  const element = useRef(null);
  useEffect(() => {
    // Embed dotAtlas when mounted
    const dotatlas = DotAtlasImpl.embed({
      element: element.current,
      layers: [ /* your layer spec */ ]
    });

    // Dispose of dotAtlas when unmounted
    return () => dotatlas.dispose();
  }, []);

  return <div ref={element} style={{ width: 400, height: 300 }} />;
};

DotAtlas.defaults

A literal object containing default values of the top-level dotAtlas properties.

const defaultTransform = DotAtlas.defaults["transform"];

DotAtlas.ElevationsLayer.defaults

A literal object containing default values of the elevation layer properties.

const defaultColorBands = DotAtlas.ElevationsLayer.defaults["colorBands"];

DotAtlas.MarkersLayer.defaults

A literal object containing default values of the marker layer properties.

const defaultMarkerColor = DotAtlas.MarkersLayer.defaults["markerColor"];

DotAtlas.LabelsLayer.defaults

A literal object containing default values of the labels layer properties.

const defaultLabelBoxColor = DotAtlas.LabelsLayer.defaults["labelBoxColor"];

DotAtlas.OutlineLayer.defaults

A literal object containing default values of the outline layer properties.

const defaultOutlineOffset = DotAtlas.OutlineLayer.defaults["outlineOffset"];