dotDensity

AMD: require(["esri/smartMapping/renderers/dotDensity"], (dotDensityRendererCreator) => { /* code goes here */ });
ESM: import * as dotDensityRendererCreator from "@arcgis/core/smartMapping/renderers/dotDensity.js";
Object: esri/smartMapping/renderers/dotDensity
Since: ArcGIS Maps SDK for JavaScript 4.12

This object contains a helper method for generating a dot density visualization. The createRenderer() method uses the view's background to determine the most appropriate dot color for each attribute. It also queries the layer for spatial statistics to determine an appropriate dot value for the given scale. The starting dot value isn't necessarily what will work best for your data. Rather, it is a suggestion that should give you a good starting point for authoring a dot density renderer.

Known Limitations

Method Overview

Name Return Type Summary Object
Promise<RendererResult>

Generates a DotDensityRenderer based on one or more complementary numeric fields and/or Arcade expressions.

dotDensity

Method Details

createRenderer

Method
createRenderer(params){Promise<RendererResult>}

Generates a DotDensityRenderer based on one or more complementary numeric fields and/or Arcade expressions. This method will determine an appropriate dotValue for the data at the scale of the provided view.

For example, suppose you have a layer of U.S. counties with fields containing the total sales of various crops: wheat, soybeans, corn, cotton, and vegetables. If a feature has the following values for each field:

Field Name Count Color
Wheat 140 purple
Soybeans 2000 blue
Corn 0 yellow
Cotton 300 green
Vegetables 120 red

This method will generate a renderer that may determine the dotValue should be 20. The feature with the data above will be rendered with a random placement of 6 purple dots, 100 blue dots, no yellow dots, 60 green dots, and 5 red dots.

The suggested value is calculated based on a sampling of features. So executing this method multiple times using the same parameters may yield varied results.

Other options are provided for convenience for more involved custom visualization authoring applications.

Parameters
Specification
params Object

Input parameters for generating a dot density visualization based on a set of complementary numeric field(s). See the table below for details of each parameter.

Specification

The polygon layer for which the visualization is generated.

view MapView

The MapView instance in which the visualization will be rendered.

attributes Object[]

A set of complementary numeric fields/expressions used as the basis of the dot density visualization. For example, if creating an election map, you would indicate the names of each field representing the candidate or political party where total votes are stored.

Specification
field String
optional

The name of a numeric field.

label String
optional

The label describing the field name (or category) in the legend. This is should be used if the given field doesn't have an intuitive field name or alias. For example, for a field named dem representing the total vote count for the Democratic party, you can set the label to Democrat to clarify the name of the category in the final visualization.

valueExpression String
optional

An Arcade expression following the specification defined by the Arcade Visualization Profile. Expressions may reference field values using the $feature profile variable and must return a number. This property overrides the field property and therefore is used instead of an input field value.

valueExpressionTitle String
optional

Text describing the value returned from the valueExpression.

dotValueOptimizationEnabled Boolean
optional
Default Value: true

Indicates whether to vary the value of each dot by the view's scale. This will set the referenceScale of the output renderer.

dotBlendingEnabled Boolean
optional
Default Value: true

Indicates whether to enable color blending of different colored dots rendered at the same pixel. This is only visible in highly dense and highly diverse features.

outlineOptimizationEnabled Boolean
optional
Default Value: false

Indicates whether the polygon outline width should vary based on view scale. When false, no outline will be used in the output renderer.

legendOptions Object
optional

Provides options for modifying Legend properties describing the visualization.

Specification
unit String
optional

Indicates the unit represented by each dot in the legend. For example, in a population density map, you might set the value of people to this param. The output renderer would display 1 dot = 300 people in the Legend.

dotDensityScheme DotDensityScheme
optional

In authoring apps, the user may select a pre-defined dot density scheme. Pass the scheme object to this property to avoid getting one based on the view's background.

forBinning Boolean
optional

Indicates whether the generated renderer is for a binning visualization. If true, then the input field(s) in this method should refer to aggregate fields defined in the featureReduction property of the layer.

signal AbortSignal
optional

Allows for cancelable requests. If canceled, the promise will be rejected with an error named AbortError. See also AbortController.

Returns
Type Description
Promise<RendererResult> Resolves to an instance of RendererResult.
Example
const layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/USA_County_Crops_2007/FeatureServer/0"
});

// will create a visualization of predominant crop by U.S. county

const params = {
  layer: layer,
  view: view,
  attributes: [{
    field: "M217_07",
    label: "Vegetables"
  }, {
    field: "M188_07",
    label: "Cotton"
  }, {
    field: "M172_07",
    label: "Wheat"
  }, {
    field: "M193_07",
    label: "Soybeans"
  }, {
    field: "M163_07",
    label: "Corn"
  }]
};

// when the promise resolves, apply the renderer to the layer
dotDensityRendererCreator.createRenderer(params)
  .then(function(response){
    layer.renderer = response.renderer;
  });

Type Definitions

RendererResult

Type Definition
RendererResult

The result object of the createRenderer() method. See the table below for details of each property.

Properties

The object representing the dot density visualization. Set this on a layer's renderer property to update its visualization.

dotDensityScheme DotDensityScheme

The dot density scheme used by the renderer based on the view's background.

basemapId String

The ID of the basemap used to determine the optimal colors of the dots.

basemapTheme String

Indicates whether the average color of the input view's basemap is light or dark.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.