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.

# DotAtlas API

This reference describes the `DotAtlas` class, which exposes the top-level API, including visualization embedding, layer creation or global event handling.

For the description of the general dotAtlas API structure, see API overview .

##
Properties

###
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")
    });

Heads up, non-zero dimensions!

Note that the provided HTML must have non-zero dimensions, otherwise an exception will be thrown when embedding dotAtlas.

The most common causes of the element having zero dimensions are:

- the element does not have dimensions set and is not stretched to fill its container. Make sure you provide the element size explicitly or cause it to stretch to fill its parent.

- the element is not displayed during embedding due to the `display: none` CSS applied to the element or any of its parents. If this is the case, delay embedding until the element becomes visible. Once dotAtlas embeds successfully, the element can be hidden and shown using `display: none` without affecting the visualization.

- dotAtlas is initialized too early and the element has not yet been styled and laid out by the browser. If this is the case, consider delaying embedding until the page fully loads using the document's `load` event.

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

###
imageData

Returns the current state of the visualization as an image in the data URL format. Unlike most attributes, this one accepts an optional object which can specify the image format details. This object can contain the following keys:

`format`

  format of the image data: `image/png` (default) or `image/jpeg`

`quality`

  if `format` is `image/jpeg`, specifies the desired quality of JPEG compression in the `0`...`1`, where `1` means the highest quality and largest image data. The default quality is `0.8`. Note that JPEG images are always opaque, use PNG images to handle background transparency.

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

##
Events

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

##
Methods

###
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 `layers`option 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 }} />;
    };

##
Defaults

You can obtain default DotAtlas and layer property values by accessing the special `defaults` static literal objects listed below.

###
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"];

previous article
Common API
next article
Common layer API