univariateColorSize

require(["esri/renderers/smartMapping/creators/univariateColorSize"], function(colorAndSizeRendererCreator) { /* code goes here */ });
Object: esri/renderers/smartMapping/creators/univariateColorSize
Since: ArcGIS API for JavaScript 4.2

This object contains helper methods for generating data-driven univariate visualizations using both continuous color and continuous size based on a field value or expression from features in a Layer. The createContinuousRenderer() method generates a Renderer object that may be applied directly to a supported layer. This renderer contains a continuous color and size ramp with optimal colors based on the indicated basemap and mapped to specific break values based on the statistics of the indicated field or expression.

Alternately, you can use the createVisualVariable() method to generate a color and a size visual variable with default stops and colors that are optimally chosen based on the statistics of the indicated field and the desired basemap.

These methods are intended for use in applications that contain 3D visualizations. Since thematic size may be difficult to interpret on its own in 3D extrusions, adding a color ramp representing the same data helps effectively communicate the story of the visualization so it's more easily understood by the audience.

Known Limitations

  • Currently 3D symbols can only be generated for layers with a point geometry type.
  • Only FeatureLayer, SceneLayer, and CSVLayer layer types are currently supported, except in the following scenarios:
  • You cannot generate renderers and visual variables using SQL expressions for client-side FeatureLayers in a SceneView.

Method Overview

NameReturn TypeSummaryObject
Promise<ContinuousRendererResult>

Generates a Renderer that may be applied directly to a Layer.

more details
more detailsunivariateColorSize
Promise<VisualVariablesResult>

This method generates color and size visual variables, both based on the same given field or expression.

more details
more detailsunivariateColorSize

Method Details

createContinuousRenderer(params){Promise<ContinuousRendererResult>}

Generates a Renderer that may be applied directly to a Layer. The renderer contains continuous color and size visual variables that map symbols with optimal colors and sizes based on the indicated basemap to specific stop values based on queried statistics from the indicated field or expression.

In most cases you will provide a layer, basemap, field, and theme to generate this renderer. This is a scenario in which the statistics of the data aren't well known and the user doesn't know what colors and sizes to use in the visualization. You can also use a valueExpression instead of a field to visualize features based on a value returned from a script executed at runtime.

The other options are provided for convenience for more involved custom visualization authoring applications. For example, if you already generated statistics in another operation, you can pass the statistics object to the statistics parameter to avoid making an extra call to the server.

Parameters:
params Object

See the table below for details of each parameter that may be passed to this method.

Specification:

The layer for which the visual variable is generated.

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.

field String
optional

The name of the field whose data will be queried for statistics and used for the basis of the data-driven visualization. This property is ignored if a valueExpression is used.

normalizationField String
optional

The name of the field to normalize the values of the given field. Providing a normalization field helps minimize some visualization errors and standardizes the data so all features are visualized with minimal bias due to area differences or count variation. This option is commonly used when visualizing densities.

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. This is used by the Legend widget.

sqlExpression String
optional

A SQL expression evaluating to a number.

sqlWhere String
optional

A SQL where clause used to filter features for the statistics query. For example, this is useful in situations where you want to avoid dividing by zero as is the case with creating a predominance visualization.

optional

A statistics object generated from the summaryStatistics function. If statistics for the field have already been generated, then pass the object here to avoid making a second statistics query to the server.

minValue Number
optional

A custom minimum value set by the user. Use this in conjunction with maxValue to generate statistics between lower and upper bounds. This will be the lowest stop in the returned visual variables.

maxValue Number
optional

A custom maximum value set by the user. Use this in conjunction with minValue to generate statistics between lower and upper bounds. This will be the uppermost stop in the returned visual variables.

defaultSymbolEnabled Boolean
optional

Enables the defaultSymbol on the renderer and assigns it to features with no value and features that do not fall within the configured data range.

colorOptions Object
optional

Options for configuring the color portion of the visualization.

Specification:
theme String
optional

Determines which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

ValueDescriptionExample
high-to-lowHigh values are emphasized with strong colors.high-to-low
above-and-belowValues centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors.above-and-below
centered-onValues centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors.centered-on
extremesHigh and low values are emphasized with strong colors. All others are visualized with weak colors.extremes
colorScheme ColorScheme
optional

In authoring apps, the user may select a pre-defined color scheme. Pass the scheme object to this property to avoid getting one based on a theme and the basemap.

legendOptions Object
optional

Provides options for setting a title to a field when an expression is provided instead of a field name. This title will represent the field in the Legend.

Specification:
title String

The title used to represent the given field or expression in the Legend.

sizeOptions Object
optional

Options for configuring the size portion of the visualization.

Specification:
sizeScheme SizeScheme
optional

In authoring apps, the user may select a pre-defined size scheme. Pass the scheme object to this property to avoid getting one based on the basemap.

legendOptions Object
optional

Provides options for setting a title to a field when an expression is provided instead of a field name. This title will represent the field in the Legend.

Specification:
title String

The title used to represent the given field or expression in the Legend.

view View
optional

The view instance in which the visualization will be rendered. A SceneView is required if symbolType = "3d-volumetric" or 3d-volumetric-uniform. The relevant SceneView or MapView is required when a valueExpression is specified.

symbolType String
optional
Default Value: 2d

The type of symbol to generate. This depends on the view in which you are working and the desired visualization. Possible values are described below.

ValueDescription
2dGenerates a visualization using 2D symbols such as SimpleMarkerSymbol, SimpleLineSymbol, or SimpleFillSymbol. Use this option if generating a visualization for data in a MapView.
3d-flatGenerates a visualization using 3D symbols with flat symbol layers such as IconSymbol3DLayer, LineSymbol3DLayer, or FillSymbol3DLayer. Use this option if generating a 2D visualization for data in a SceneView.
3d-volumetricGenerates a visualization using 3D symbols with volumetric symbol layers such as ObjectSymbol3DLayer, PathSymbol3DLayer, or ExtrudeSymbol3DLayer. Use this option if generating a 3D visualization for data in a SceneView and only the symbol's height should be variable, for example with cylinders. A SceneView instance must be provided to the view parameter if this option is used.
3d-volumetric-uniformGenerates a visualization using uniformly sized 3D symbols with volumetric symbol layers. Use this option if generating a 3D visualization for data in a SceneView and the symbol should be sizes uniformly, for example with spheres. A SceneView instance must be provided to the view parameter if this option is used.
Returns:
TypeDescription
Promise<ContinuousRendererResult>Resolves to an instance of ContinuousRendererResult.
Examples:
var layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
});

// color/size univariate visualization based on field and normalization field
var params = {
  layer: layer,
  basemap: map.basemap,  // "gray"
  field: "POP_POVERTY",
  normalizationField: "TOTPOP_CY",
  colorOptions: {
    theme: "above-and-below"
  }
};

// when the promise resolves, apply the renderer to the layer
colorAndSizeRendererCreator.createContinuousRenderer(params)
  .then(function(response){
    layer.renderer = response.renderer;
  });
var layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
});

// visualization based off Arcade expression
var params = {
  layer: layer,
  basemap: "topo",
  valueExpression: "($feature.POP_POVERTY / $feature.TOTPOP_CY) * 100",
  view: view,
  sqlWhere: "TOTPOP_CY > 0",
  colorOptions: {
    legendOptions: {
      title: "% of people living in poverty"
    }
  },
  sizeOptions: {
    legendOptions: {
      title: "% of people living in poverty"
    }
  }
};

// when the promise resolves, apply the renderer to the layer
colorAndSizeRendererCreator.createContinuousRenderer(params)
  .then(function(response){
    layer.renderer = response.renderer;
  });
createVisualVariables(params){Promise<VisualVariablesResult>}

This method generates color and size visual variables, both based on the same given field or expression. These visual variables are generated with default stops that are optimally chosen based on the statistics queried for the indicated field or expression and colors based on the input basemap.

There are two different ways this method may be called. The most common case is by providing a layer, basemap, and field. This is the scenario where the statistics of the data aren't well known and the user doesn't know what colors to use. You can optionally use a valueExpression instead of a field to visualize features based on a numeric value returned from a script executed at runtime.

The other options are provided for convenience for more involved custom visualization authoring applications. For example, if you already generated statistics in another operation, you can pass the object in the statistics parameter to avoid making an extra call to the server. You can also provide a colorScheme and/or a sizeScheme if you don't want one picked for you. In this case the basemap and theme options would be ignored.

The resulting array of visual variables will contain one color visual variable, and one or two size visual variables depending on the value of the sizeOptions.axis parameter.

Parameters:
params Object

Input parameters for generating color and size visual variables based on data returned from a given field or expression. See the table below for details of each parameter.

Specification:

The layer for which the visual variable is generated.

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.

field String
optional

The name of the field whose data will be queried for statistics and used for the basis of the data-driven visualization. This property is ignored if a valueExpression is used.

normalizationField String
optional

The name of the field to normalize the values of the given field. Providing a normalization field helps minimize some visualization errors and standardizes the data so all features are visualized with minimal bias due to area differences or count variation. This option is commonly used when visualizing densities.

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. This is used by the Legend widget.

sqlExpression String
optional

A SQL expression evaluating to a number.

sqlWhere String
optional

A SQL where clause used to filter features for the statistics query. For example, this is useful in situations where you want to avoid dividing by zero as is the case with creating a predominance visualization.

optional

A statistics object generated from the summaryStatistics function. If statistics for the field have already been generated, then pass the object here to avoid making a second statistics query to the server.

minValue Number
optional

A custom minimum value set by the user. Use this in conjunction with maxValue to generate statistics between lower and upper bounds. This will be the lowest stop in the returned visual variables.

maxValue Number
optional

A custom maximum value set by the user. Use this in conjunction with minValue to generate statistics between lower and upper bounds. This will be the uppermost stop in the returned visual variables.

colorOptions Object
optional

Options for configuring the color portion of the visualization.

Specification:
theme String
optional

Determines which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

ValueDescriptionExample
high-to-lowHigh values are emphasized with strong colors.high-to-low
above-and-belowValues centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors.above-and-below
centered-onValues centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors.centered-on
extremesHigh and low values are emphasized with strong colors. All others are visualized with weak colors.extremes
colorScheme ColorScheme
optional

In authoring apps, the user may select a pre-defined color scheme. Pass the scheme object to this property to avoid getting one based on a theme and the basemap.

legendOptions Object
optional

Provides options for setting a title to a field when an expression is provided instead of a field name. This title will represent the field in the Legend.

Specification:
title String

The title used to represent the given field or expression in the Legend.

sizeOptions Object
optional

Options for configuring the size portion of the visualization.

Specification:
axis Boolean
optional
Default Value: all

When set to all, a single size variable that scales uniformly in all dimensions is generated. When set to height, the result contains two size visual variables: the first one sizes the height according to the field statistics, while the second defines a constant size for width and depth.

Possible Values: all | height

sizeScheme SizeScheme
optional

In authoring apps, the user may select a pre-defined size scheme. Pass the scheme object to this property to avoid getting one based on the basemap.

legendOptions Object
optional

Provides options for setting a title to a field when an expression is provided instead of a field name. This title will represent the field in the Legend.

Specification:
title String

The title used to represent the given field or expression in the Legend.

view View
optional

When generating 3D symbols, a SceneView instance is required. The relevant SceneView or MapView is required when a valueExpression is specified.

worldScale Boolean
optional

Indicates if the size units of the symbols will be in meters. This should be true when generating visualizations with 3D volumetric symbology. A view must be provided if this property is set to true.

Returns:
TypeDescription
Promise<VisualVariablesResult>Resolves to an instance of VisualVariablesResult.
Examples:
var layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
});

// color/size univariate visualization based on field and normalization field
var params = {
  layer: layer,
  basemap: map.basemap,  // "gray"
  field: "POP_POVERTY",
  normalizationField: "TOTPOP_CY",
  colorOptions: {
    theme: "above-and-below"
  }
};

// when the promise resolves, apply the visual variables to the renderer
colorAndSizeRendererCreator.createVisualVariables(params)
  .then(function(response){
    var renderer = layer.renderer.clone();
    renderer.visualVariables = [ response.color.visualVariable, response.size.visualVariable ];
    layer.renderer = renderer;
  });
var layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
});

// visualization based off an Arcade expression
var params = {
  layer: layer,
  basemap: "topo",
  valueExpression: "($feature.POP_POVERTY / $feature.TOTPOP_CY) * 100",
  sqlExpression: "( POP_POVERTY / TOTPOP_CY ) * 100",
  colorOptions: {
    legendOptions: {
      title: "% of people living in poverty"
    }
  },
  sizeOptions: {
    legendOptions: {
      title: "% of people living in poverty"
    }
  }
};

// when the promise resolves, apply the visual variables to the renderer
colorAndSizeRendererCreator.createVisualVariables(params)
  .then(function(response){
    var renderer = layer.renderer.clone();
    renderer.visualVariables = [ response.color.visualVariable, response.size.visualVariable ];
    layer.renderer = renderer;
  });

Type Definitions

ContinuousRendererResult

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

Properties:

The renderer object configured to best match the given basemap and the spread of the data. Set this on a layer's renderer property to update its visualization.

color Object

Object containing visual variable and scheme information for the color portion of the visualization.

Specification:
visualVariable ColorVisualVariable

A color visual variable configured based on the statistics of the data and the given basemap and scheme.

colorScheme ColorScheme

The color scheme used by the visual variable.

size Object

Object containing visual variable and scheme information for the size portion of the visualization.

Specification:
visualVariables SizeVisualVariable[]

The size visual variable(s) configured based on the statistics of the data and the view scale.

sizeScheme SizeScheme

The size scheme used by the visual variable.

defaultValuesUsed Boolean

Indicates whether default values were used in the absence of sufficient data and/or statistics from the layer. Default values are typically used when all features have the same field value or no value at all.

Basic statistics returned from a query to the service for the given field or expression.

basemapId String

The ID of the basemap used to determine the optimal fill color of the features.

VisualVariablesResult

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

Properties:
color Object

Object containing visual variable and scheme information for the color portion of the visualization.

Specification:
visualVariable ColorVisualVariable

A color visual variable configured based on the statistics of the data and the given basemap and scheme.

colorScheme ColorScheme

The color scheme used by the visual variable.

size Object

Object containing visual variable and scheme information for the size portion of the visualization.

Specification:
visualVariables SizeVisualVariable[]

The size visual variable(s) configured based on the statistics of the data and the view scale.

sizeScheme SizeScheme

The size scheme used by the visual variable.

defaultValuesUsed Boolean

Indicates whether default values were used in the absence of sufficient data and/or statistics from the layer. Default values are typically used when all features have the same field value or no value at all.

Basic statistics returned from a query to the service for the given field or expression.

basemapId String

The ID of the basemap used to determine the optimal fill color of the features.

authoringInfo AuthoringInfo

Authoring information related to the creation of the visual variables. This includes inforamation related to UI inputs from sliders and selected themes.

API Reference search results

NameTypeModule
Loading...