Skip To ContentArcGIS for DevelopersSign In Dashboard
require(["esri/renderers/smartMapping/creators/dotDensity"], function(dotDensityRendererCreator) { /* code goes here */ });
Object: esri/renderers/smartMapping/creators/dotDensity
Since: ArcGIS API for JavaScript 4.12

This object contains a helper method for generating a dot density visualization. The createRenderer() method uses the input basemap 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

NameReturn TypeSummaryObject
Promise<RendererResult>

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

more details
more detailsdotDensity

Method Details

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 NameCountColor
Wheat140purple
Soybeans2000blue
Corn0yellow
Cotton300green
Vegetables120red

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 that returns a number. This expression can reference field values using the $feature global variable. 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.

basemap String|Basemap
optional
Default Value: gray

The named string or basemap object of the Esri basemap that will be paired with the output visualization.

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

Returns:
TypeDescription
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,
  basemap: map.basemap,  // "gray"
  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

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 given basemap.

basemapId String

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

API Reference search results

NameTypeModule
Loading...