dotDensity | API Reference | ArcGIS Maps SDK for JavaScript 4.31

See also

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.

filter FeatureFilter

optional

Since 4.31 When defined, only features included in the filter are considered in the attribute and spatial statistics calculations when determining the final renderer. This is useful when a lot of variation exists in the data that could result in undesired data ranges. A common use case would be to set a filter that only includes features in the current extent of the view where the data is most likely to be viewed. Currently, only geometry filters with an intersects spatial relationship are supported. All other filter types (including where) are ignored.

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: renderer DotDensityRenderer

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.