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

This object contains a helper method for generating data-driven visualizations with continuous opacity based on data returned from a field value or expression in a Layer.

The createVisualVariable() method generates an opacity visual variable with default alpha values that are optimally mapped to data values based on the statistics of the indicated field.

Known Limitations

  • 3D symbols cannot be generated for layers with a polyline or polygon geometry type.
  • Only FeatureLayer, SceneLayer, and CSVLayer layer types are supported, except in the following scenarios:
    • SceneLayers without the supportsRenderer and supportsLayerQuery capabilities enabled, unless a predefined statistics object is passed to the statistics parameter of the method in conjunction with the layer. To check a SceneLayer's capabilities, use the getFieldInfoUsage() method.
  • Generating visual variables using SQL expressions is restricted to feature services hosted on ArcGIS Online.

Method Overview

NameReturn TypeSummaryObject
Promise<VisualVariableResult>

This method generates an opacity visual variable with default alpha values optimally mapped to data values based on the statistics queried for the indicated field or expression.

more details
more detailsopacity

Method Details

createVisualVariable(params){Promise<VisualVariableResult>}

This method generates an opacity visual variable with default alpha values optimally mapped to data values based on the statistics queried for the indicated field or expression.

There are several ways this method may be called. The most common case is by providing a layer and a field. This is the scenario where the statistics of the data aren't well known and the user doesn't know the which alpha values to map to data values. 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 stats in the statistics parameter to avoid making an extra call to the server.

Parameters:
params Object

Input parameters for generating an opacity visual variable 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.

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. This parameter is only supported for service-based FeatureLayers.

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.

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
optional

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

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

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

view View
optional

A SceneView or MapView instance is required when a valueExpression is specified.

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

// visualization based on field and normalization field
var params = {
  layer: layer,
  field: "POP_POVERTY",
  normalizationField: "TOTPOP_CY"
};

// when the promise resolves, apply the visual variable to the renderer
opacityVariableCreator.createVisualVariable(params)
  .then(function(response){
    var renderer = layer.renderer.clone();
    renderer.visualVariables = [ response.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 Arcade expression
var params = {
  layer: layer,
  valueExpression: "($feature.POP_POVERTY / $feature.TOTPOP_CY) * 100",
  view: view,
  valueExpressionTitle: "% of people living in poverty"
};

// when the promise resolves, apply the visual variable to the renderer
opacityVariableCreator.createVisualVariable(params)
  .then(function(response){
    var renderer = layer.renderer.clone();
    renderer.visualVariables = [ response.visualVariable ];
    layer.renderer = renderer;
  });

Type Definitions

VisualVariableResult

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

Properties:
visualVariable OpacityVisualVariable

An opacity visual variable configured based on the statistics of the data.

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

defaultValuesUsed Boolean

Indicates whether default values are 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.

authoringInfo AuthoringInfo

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

Searching...

API Reference search results

NameTypeModule

There were no match results from your search criteria.