/

Managing properties

Properties control various aspects of your visualization, such as marker shape or elevation contour width.

dotAtlas properties can be defined at three different levels:

  • global properties control instance-level aspects of your visualization, such as the array of layers to display or zoom level. Read-only global properties allow, for example, obtaining the current visualization image in the PNG or JPEG format.

  • layer properties control characteristics of one dotAtlas layer, such as the font family used to draw labels on the labels layer or the intensity of light shading on the elevations layer.

  • point properties control how an individual point on a specific layer is displayed. Mandatory point properties are its x and y coordinates, but other properties are available depending on the layer type. For the markers layer this could be, for example, marker shape or color.

    Certain per-point properties have their counterparts on the layer level. In this case they serve as the default value that can be overridden on the point level.

Initialization

You can provide the initial global property values when embedding dotAtlas using the DotAtlas.embed() method. Pass all your properties as a literal object, where property names correspond to the dotAtlas properties you'd like to initialize: 

import { DotAtlas } from "@carrotsearch/dotatlas";

const dotatlas = DotAtlas.embed({
  "element": document.getElementById("dotatlas"),
  "layers": [
    // provide layer data here
  ]
});

Layer- and point-specific properties are initialized when defining layers: 

const elevations = DotAtlas.createLayer({
  "type": "elevation",
  "points": [
    { "x":  0, "y": 0, "elevation": 1.0 },
    { "x": -1, "y": 0, "elevation": 0.8 },
    { "x":  0, "y": 1, "elevation": 0.5 }
  ],
  "lightIntensity": 0.2,
  "contourWidth": 1.0
});

Updating

Global properties

You can change global property values at any time using the set(props) method. For certain properties you may need to call redraw() for the changes to take effect. Please see the reference documentation for specific properties for details. 

dotatlas.set({
  "transform": {
    "translateX": 10,
    "translateY": 10,
    "scale": 1
  }
});
dotatlas.redraw();

Layer properties

Similarly, you can call the set(props) method on a layer instance to set layer-specific properties. Again, many properties will require a redraw() call for the changes to appear on the screen. 

const elevations = dotatlas.get("layers")[0];
elevations.set({
  "lightIntensity": 0.5,
  "contourWidth": 0.5
});
dotatlas.redraw();

Point properties

Updating point properties is different from updating global and layer properties. The reason is that dotAtlas copies point properties, such as coordinates or marker color, to an internal buffer when the layer is created. If you change any of the point properties, you will need to let dotAtlas know by calling the layer's update() method to refresh the internal buffers. To reflect the changes on the screen, you will also need to call redraw(). 

const dotatlas = DotAtlas.embed({
  "element": document.getElementById("dotatlas"),
  "layers": [
    {
      "type": "marker",
      "points": [{ x: 0, y: 0 }],
      "markerSizeMultiplier": 60
    }
  ]
});

window.setTimeout(() => {
  const markers = dotatlas.get("layers")[0];
  markers.get("points")[0].markerShape = "square";
  markers.update("markerShape");
  dotatlas.redraw();
}, 2000);

Read-only properties

dotAtlas exposes a number of read-only properties you can access using the get(prop, args...) method. Getting some properties, such as imageData, may require passing extra arguments as the second method argument: 

const image = dotatlas.get("imageData", {
  "format": "image/jpeg",
  "quality": 0.9
});