opacity | References | ArcGIS Maps SDK for JavaScript

import { createVisualVariable } from "@arcgis/core/smartMapping/renderers/opacity.js";

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

SceneLayers must have the supportsRenderer and supportsLayerQuery capabilities enabled unless a predefined statistics object is provided to the statistics parameter of the method. To check a SceneLayer's capabilities, use the SceneLayer.getFieldUsageInfo() method. You cannot generate renderers and visual variables using SQL expressions for client-side FeatureLayers in a SceneView.

See also

Styles and data visualization

Functions

Name	Return Type	Object
`createVisualVariable`	`Promise<VisualVariableResult>`
`VisualVariableParameters`
`VisualVariableResult`

createVisualVariable

Function

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.

Signature: createVisualVariable (parameters: VisualVariableParameters): Promise<VisualVariableResult>

Parameters

Parameter	Type	Description	Required
parameters	`VisualVariableParameters`	Input parameters for generating an opacity visual variable based on data returned from a given field or expression.

Returns: Promise<VisualVariableResult>
Resolves to an instance of VisualVariableResult.

Examples

let layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
});

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

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

let layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
});

// visualization based off Arcade expression
let parameters = {
  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(parameters)
  .then(function(response){
    let renderer = layer.renderer.clone();
    renderer.visualVariables = [ response.visualVariable ];
    layer.renderer = renderer;
  });

Type definitions

VisualVariableParameters

Type definition

Supertypes: AbortOptions

layer

Property

Type: FeatureLikeLayerOrAdapter | null | undefined

The layer for which the visual variable 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.

field

Property

Type: string | null | undefined

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

Property

Type: string | null | undefined

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

Property

Type: string | null | undefined

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. The view parameter is required if specifying a valueExpression. When using a valueExpression, client-side statistics are calculated based on the features in the view's extent. To generate statistics for the entire layer, set an equivalent sqlExpression.

valueExpressionTitle

Property

Type: string | null | undefined

Text describing the value returned from the valueExpression. This is used by the Legend.

sqlExpression

Property

Type: string | null | undefined

A SQL expression evaluating to a number. When provided, statistics are queried from the server for the entire layer. Only use this parameter when generating a renderer based on an equivalent valueExpression. This parameter is ignored for client-side layer types.

sqlWhere

Property

Type: string | null | undefined

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.

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.

legendOptions

Property

Type: IVisualVariableLegendOptions | null | undefined

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.

statistics

Property

Type: SummaryStatisticsResult | null | undefined

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

Property

Type: number | null | undefined

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

Property

Type: number | null | undefined

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.

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.

view

Property

Type: MapViewOrSceneView | null | undefined

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

VisualVariableResult

Type definition

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

visualVariable

Property

Type: OpacityVariable

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

defaultValuesUsed

Property

Type: 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.

statistics

Property

Type: SummaryStatisticsResult

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

authoringInfo

Property

Type: AuthoringInfo

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