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 API

This reference describes the common API elements exposed by the top-level dotAtlas instance and layer instances.

All methods described in this reference are available on dotAtlas instance objects created using the `DotAtlas.embed()` method as well as on layer instance objects retrieved from dotAtlas or created with the `DotAtlas.createLayer()` method.

##
Methods

###
get()

Returns an object containing current values of all properties.

    console.log("dotAtlas properties", dotatlas.get());

    const elevations = dotatlas.get("layers")[0];
    console.log("elevation layer properties", elevations.get());

###
get(prop)

Returns the current value of one `prop`. If the provided string does not correspond to any property name, the result is undefined.

    console.log(dotatlas.get("layers"));

    const elevations = dotatlas.get("layers")[0];
    console.log("light intensity", elevations.get("lightIntensity"));

###
get(prop, args...)

Returns the current value of the requested read-only `prop`, optionally parameterized by the provided `args`. The number and type of arguments depends on the requested read-only property, see the documentation of the specific the property for details.

The following example retrieves the current visualization image in the JPEG format.

    const bitmap = dotatlas.get("imageData", {
      format: "image/jpg", quality: 0.8
    });

The following example gets the elevation value at the provided screen coordinates:

    const elevations = dotatlas.get("layers")[0];
    const elevationValue = elevations.get("elevationAt", 150, 200);

###
set(prop, value)

Sets a new value for one property of dotAtlas or layer instance. If the string passed in the `prop` parameter does not correspond to any property, the call will be ignored.

    dotatlas.set("layers", [ /* layers to set */ ]);

    const elevations = dotatlas.get("layers")[0];
    elevations.set("lightAzimuth", 2 * Math.PI);

###
set(props)

Sets values of dotAtlas global properties provided in the literal object `props`.

    dotatlas.set({
      "maxZoomLevel": 32768,
      "layers": [
        // layers to set
      ]
    });

    const elevations = dotatlas.get("layers")[0];
    elevations.set({
      "lightIntensity": 0.5,
      "lightAzimuth": 2 * Math.PI
    });

###
on()

Registers a listener for a dotAtlas or layer event.

    dotatlas.on(event, listener);

The `event` parameter is the event name. The `listener` parameter is the function to call when the event occurs. For most events, the function will receive the event details object as the first and only parameter.

Note that event names here are slightly different from the event names used in the `set()` method. To get the event name to use with the `on()`, `once()`,`off()` method, take the event property name, remove the leading "on" and lower-case the first letter, for example:

Property name for `set()` | Event name for `on()`, `once()` and `off()`
--- | ---
`onClick` | `click`
`onPointClick` | `pointClick`
`onMaxElevationChanged` | `maxElevationChanged`
`selection:onSelectionChanged` | `selection:selectionChanged`

As opposed to using the `set()` method, this method preserves the previously registered listeners. Typical invocations of this method will be similar to:

    dotatlas.on("redraw", e => { /* react to visualization redraw */ });

    const elevations = dotatlas.get("layers")[0];
    elevations.on("maxElevationChanged", e => { /* react to peak change */ });

For an overview of dotAtlas event handling, see the Listening to events guide.

###
once()

Registers a one-time listener for a dotAtlas or layer event. Once the event is triggered, the listener will be removed from the listeners list and will not be notified of further events.

    dotatlas.once(event, listener);

The `event` parameter is the event name. Note the event naming convention differences when using `on()`, `once()` and `off()` methods. The `listener` parameter is the function to call when the event occurs.

The typical invocations of this method will look like this:

    dotatlas.once("redraw", e => { /* react to visualization redraw */ });

    const elevations = dotatlas.get("layers")[0];
    elevations.once("maxElevationChanged", e => { /* react to peak change */ });

If the `listener` parameter is not provided, this method returns a `Promise` that is resolved once the event is triggered:

    dotatlas.once("layersChanged").then(e => {
      // handle the one-time event
    });

For an overview of dotAtlas event handling, see the Listening to events guide.

###
off()

Removes a listener from the list of listeners registered for the specified event.

    dotatlas.off(event, listener);

The `event` parameter is the event name. Note the event naming convention differences when using `on()`, `once()` and `off()` methods. The `listener` parameter is the function to remove from the listener list.

As opposed to using the `set()` method, this method will preserve the other listeners registered for the event.

The invocations of this method will typically be similar to:

    const redrawListener = e => { console.log("visualization redrawn", e ); };
    dotatlas.on("redraw", redrawListener);
    dotatlas.off("redraw", redrawListener);

##
Data structures

###
2d point

Many parts of the API require 2d points on input or return them as a result of some computation. In all such cases the 2d point is represented by a literal object containing the coordinates in the `x` and `y` properties, for example:

    const point = {
      "x":  0.125,
      "y": -0.5
    };

The exact semantics of the point depends on the context. Typically, the points will be expressed in one of the two 2d spaces:

element space

  coordinates refer to the on-screen pixels where point `(0, 0)` is the upper left corner of the DOM `element` in which dotAtlas is embedded. Typically, points in the element space will appear in screen-based events, such as `onMouseMove`.

layer space

  coordinates refer to the 2d space defined by the data points you provide in the `layers` to be visualized. Layer space coordinates will typically appear in events related to specific data points, such as `onPointClick`.

###
Colors

In all properties involving colors, such as `markerColor` or `colorBands`, dotAtlas supports CSS3 color strings, such as:

- `#aaa`
- `#f0e0e0`
- `#ff0000a0`
- `rgb(255, 128, 128)`
- `rgba(64, 192, 32, 0.25)`
- `hsl(60, 100%, 50%)`
- `hsla(60, 60%, 80%, 0.4)`
- `transparent`

Please note that descriptive color names, such as, `red` or `hotpink` are not supported to limit the size of dotAtlas code. Use color-name or a similar utility to retrieve RGBA values for named colors.

In addition to CSS3 color strings, you can pass object- or array-based color specifications:

- `{ r: 255, g: 128, b: 64, a: 0.5 }`
- `{ h: 85, s: 50, l: 80, a: 1.0 }`
- `[ 255, 192, 64, 64 ]` – RGBA components in the 0...255 range.

###
Event details

All event handler functions will be called with an event details object as the first parameter. For all event types, the event details object will contain the following properties:

`type`

  Type of the low-level event that gave rise to this event, such as `click` or `move`.

`inside`

  `true` if the event happened inside the dotAtlas DOM element. While this will be the case most of the time, some `onMouseMove` events may be raised with `inside` equal to `false`, which means the mouse pointer left the dotAtlas element area.

`elementX`, `elementY`

  element space coordinates of the point over which the event was triggered. You can use them when, for example, positioning a HTML tooltip over dotAtlas area.

`x`, `y`

  Aliases for `elementX` and `elementY`.

`layerX`, `layerY`

  layer space coordinates of the point over which the event was triggered. You can use these coordinates as start locations for point clustering, center for zooming or adding new markers.

`delta`

  The direction in which the mouse wheel was rotated. Positive values mean the upwards rotation, negative values mean downwards rotation. Meaningful only for the `onMouseWheel` event, equal to 0 for other events.

`ctrlKey`

  Set to `true` if the `Ctrl` key was pressed at the time of the event.

`shiftKey`

  Set to `true` if the `Shift` key was pressed at the time of the event.

`altKey`

  Set to `true` if the `Alt` key was pressed at the time of the event.

`preventDefault()`

  Call this function to prevent the default dotAtlas action bound to this event, for example map zooming on the `onMouseWheel` event.

Certain event types, such as `onPointClick`, come with additional properties, see the specific event documentation for details.

previous article
Using plugins
next article
DotAtlas API