dotDensity | References | ArcGIS Maps SDK for JavaScript

import { createRenderer } from "@arcgis/core/smartMapping/renderers/dotDensity.js";

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

DotDensityRenderer is currently not supported in 3D SceneViews. Only layers with polygon geometries are supported.

See also

Functions

Name	Return Type	Object
`createRenderer`	`Promise<RendererResult>`
`RendererParameters`
`RendererParamsLegendOptions`
`RendererResult`

createRenderer

Function

Generates a DotDensityRenderer based on one or more complementary numeric fields and/or Arcade expressions. This method will determine an appropriate DotDensityRenderer.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.

Signature: createRenderer (parameters: RendererParameters): Promise<RendererResult>

Parameters

Parameter	Type	Description	Required
parameters	`RendererParameters`	Input parameters for generating a dot density visualization based on a set of complementary numeric field(s).

Returns: 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

RendererParameters

Type definition

Supertypes: AbortOptions

layer

Property

Type: Exclude<SupportedLayer, ImageryLayer | KnowledgeGraphSublayer | PointCloudLayer | SceneLayer | StreamLayer> | null | undefined

The polygon layer for which the visualization is generated. When a client-side layer type is provided, attribute and spatial statistics are calculated only from features in the view's extent. When a server-side layer type is provided, the statistics are calculated from the entire layer, unless a valueExpression is provided.

attributes

Property

Type: Attribute[] | null | undefined

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.

view

Property

Type: MapView | null | undefined

The MapView instance in which the visualization will be rendered.

dotValueOptimizationEnabled

Property

Type: boolean | null | undefined

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

Default value: true

dotBlendingEnabled

Property

Type: boolean | null | undefined

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.

Default value: true

outlineOptimizationEnabled

Property

Type: boolean | null | undefined

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

Default value: false

dotDensityScheme

Property

Type: DotDensityScheme | null | undefined

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.

legendOptions

Property

Type: RendererParamsLegendOptions | null | undefined

Provides options for modifying Legend properties describing the visualization.

forBinning

Property

Type: boolean | null | undefined

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

filter

Property

Type: FeatureFilter | null | undefined

Since: ArcGIS Maps SDK for JavaScript 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.

RendererParamsLegendOptions

Type definition

unit

Property

Type: string | undefined

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.