@arcgis/core
Version:
ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API
869 lines (850 loc) • 59.5 kB
TypeScript
/**
* This object contains helper methods for generating data-driven visualizations with continuous
* size or class breaks based on a field value or expression from features in a [Layer](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/).
* The methods in this module generate renderer or visual variable objects that may be applied directly to a supported layer. The
* renderers specify how features should be visualized based on data values and the view's background.
*
* > [!WARNING]
* >
* > **Known Limitations**
* >
* > Currently, 3D symbols can only be generated for layers with a `point` geometry type.
* > [SceneLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) with `mesh` [SceneLayer.geometryType](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#geometryType) or [SceneLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) without the `supportsRenderer` and `supportsLayerQuery` capabilities enabled are not supported unless a predefined [statistics](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/types/#SummaryStatisticsResult) object is passed to the `statistics` parameter of the method in conjunction with the layer. To check a SceneLayer's capabilities, use the [SceneLayer.getFieldUsageInfo()](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#getFieldUsageInfo) method.
* > You cannot generate renderers and visual variables using SQL expressions for client-side [FeatureLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/)
* > in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
*
* @since 4.2
* @see [Styles and data visualization](https://developers.arcgis.com/javascript/latest/visualization/)
*/
import type FeatureFilter from "../../layers/support/FeatureFilter.js";
import type ClassBreaksRenderer from "../../renderers/ClassBreaksRenderer.js";
import type UniqueValueRenderer from "../../renderers/UniqueValueRenderer.js";
import type AuthoringInfo from "../../renderers/support/AuthoringInfo.js";
import type SizeVariable from "../../renderers/visualVariables/SizeVariable.js";
import type SizeStop from "../../renderers/visualVariables/support/SizeStop.js";
import type { MapViewOrSceneView } from "../../views/MapViewOrSceneView.js";
import type { AbortOptions } from "../../core/promiseUtils.js";
import type { DateProperties } from "../../intl/date.js";
import type { ClassificationMethod, NormalizationType, VisualVariableLegendOptions } from "../../renderers/types.js";
import type { StandardDeviationInterval, RendererLegendTitleOption } from "../../renderers/support/types.js";
import type { SmartMappingTimeUnit } from "../types.js";
import type { SpikeSymbolStyle } from "./support/spikeUtils.js";
import type { ClassBreaksResult, SummaryStatisticsResult } from "../statistics/types.js";
import type { FeatureLikeLayerOrAdapter } from "../support/adapters/types.js";
import type { BasemapTheme, SizeScheme, TypeScheme } from "../symbology/types.js";
/**
* This method generates an array of size visual variables
* with default stops that are optimally chosen based on the statistics
* queried for the indicated field or expression and mapped to appropriate sizes.
*
* There are two different ways this method may be called. The most common case is by
* providing a `layer`, `view`, and `field`. This is the scenario where
* the statistics of the data aren't well known and the user doesn't know what sizes
* 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 `sizeScheme` if you don't want one picked for you. In this case the
* `theme` options would be ignored.
*
* The resulting array of visual variables will contain exactly one size visual variable unless the
* `axis` parameter is set to "height".
*
* @param parameters - Input parameters for generating size visual variables based on data
* returned from a given field or expression.
* @returns Resolves to an instance of [VisualVariableResult](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#VisualVariableResult).
* @example
* const layer = new FeatureLayer({
* url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
* });
*
* // visualization based on field and normalization field
* const sizeParams = {
* layer: layer,
* view: view,
* field: "POP_POVERTY",
* normalizationField: "TOTPOP_CY",
* theme: "below"
* };
*
* // when the promise resolves, apply the visual variables to the renderer
* sizeRendererCreator.createVisualVariables(sizeParams)
* .then(function(response){
* const renderer = layer.renderer.clone();
* renderer.visualVariables = response.visualVariables;
* layer.renderer = renderer;
* });
* @example
* const layer = new FeatureLayer({
* url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/counties_politics_poverty/FeatureServer/0"
* });
*
* // visualization based off Arcade expression
* const sizeParams = {
* layer: layer,
* valueExpression: "($feature.POP_POVERTY / $feature.TOTPOP_CY) * 100",
* view: view,
* legendOptions: {
* title: "% of people living in poverty"
* }
* };
*
* // when the promise resolves, apply the visual variables to the renderer
* sizeRendererCreator.createVisualVariables(sizeParams)
* .then(function(response){
* const renderer = layer.renderer.clone();
* renderer.visualVariables = response.visualVariables;
* layer.renderer = renderer;
* });
*/
export function createVisualVariables(parameters: VisualVariableParameters): Promise<VisualVariableResult>;
/**
* Generates a [Renderer](https://developers.arcgis.com/javascript/latest/references/core/renderers/Renderer/) that may be applied directly to the
* layer used to call this method. The
* renderer contains a continuous size visual variable that maps marker sizes
* to specific stop values based on queried statistics from the indicated field or expression.
*
* In most cases you will provide a `layer`, `view`, and `field` 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 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.
*
* @param parameters - Input parameters for generating size visual variables based on data
* returned from a given field or expression.
* @returns Resolves to an instance of [ContinuousRendererResult](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#ContinuousRendererResult).
* @example
* // visualization based on field and normalization field
* const sizeParams = {
* layer,
* view,
* field: "POP_POVERTY",
* normalizationField: "TOTPOP_CY"
* };
*
* // when the promise resolves, apply the renderer to the layer
* const { renderer } = await createContinuousRenderer(sizeParams);
* layer.renderer = renderer;
* @example
* // visualization based off Arcade expression
* const sizeParams = {
* layer,
* valueExpression: "($feature.POP_POVERTY / $feature.TOTPOP_CY) * 100",
* view,
* legendOptions: {
* title: "% of people living in poverty"
* },
* theme: "above"
* };
*
* // when the promise resolves, apply the renderer to the layer
* const { renderer } = await createContinuousRenderer(sizeParams);
* layer.renderer = renderer;
*/
export function createContinuousRenderer(parameters: ContinuousRendererParameters): Promise<ContinuousRendererResult>;
/**
* Updates a renderer generated from [createContinuousRenderer()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#createContinuousRenderer) that uses a specialty reference size variable (i.e. [AuthoringInfoVisualVariable.theme](https://developers.arcgis.com/javascript/latest/references/core/renderers/support/AuthoringInfoVisualVariable/#theme) is set to `reference-size`). This would have already been generated in [createContinuousRenderer()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#createContinuousRenderer).
*
* @param parameters - Input parameters for updating an existing reference size visualization.
* @returns Resolves to the updated renderer with a specialty reference size variable.
* @since 4.30
* @example
* sizeSlider.on(["thumb-change", "thumb-drag"], async () => {
* // layer.renderer must already have a reference size variable
* const isReferenceSize = layer.renderer?.authoringInfo?.visualVariables.some(
* (vv) => vv.theme === "reference-size"
* );
*
* if(isReferenceSize){
* const renderer = await updateRendererWithReferenceSize({
* layer,
* view,
* sizeStops: sizeSlider.stops
* });
* layer.renderer = renderer;
* }
* });
*/
export function updateRendererWithReferenceSize(parameters: UpdateRendererWithReferenceSizeParameters): Promise<NonNullable<UpdateRendererWithReferenceSizeParameters["renderer"]>>;
/**
* Updates a renderer that uses a specialty spike variable (i.e. [AuthoringInfoVisualVariable.theme](https://developers.arcgis.com/javascript/latest/references/core/renderers/support/AuthoringInfoVisualVariable/#theme) is set to `spike`). This would have already been generated in [createContinuousRenderer()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#createContinuousRenderer) with `theme` set to `spike`.
*
* @param params - Input parameters for updating an existing spike visualization.
* @returns Resolves to the updated renderer with a specialty spike variable.
* @since 4.33
* @example
* sizeSlider.on(["thumb-change", "thumb-drag"], async () => {
* // layer.renderer must already include a spike variable
* const isSpike = layer.renderer?.authoringInfo?.visualVariables.some(
* (vv) => vv.theme === "spike"
* );
*
* if(isSpike){
* const renderer = await updateRendererWithReferenceSize({
* layer,
* sizeStops: sizeSlider.stops
* });
* layer.renderer = renderer;
* }
* });
*/
export function updateRendererWithSpike(params: UpdateRendererWithSpikeParameters): Promise<NonNullable<UpdateRendererWithSpikeParameters["renderer"]>>;
/**
* Generates a [ClassBreaksRenderer](https://developers.arcgis.com/javascript/latest/references/core/renderers/ClassBreaksRenderer/) that may be applied directly to the
* layer used to call this method. The resulting renderer defines the symbol size of each feature
* based on the value of the given `field` value. A default size scheme is determined based on the background of the view.
* Depending on the `classificationMethod`, class breaks (or data ranges) are generated based on the statistics of the data.
* Each feature is assigned a size based on the class break in which the value of the `field` falls.
*
* In most cases you will provide a `layer`, `view`, `field`, and `classificationMethod` 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 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.
*
* @param parameters - Input parameters for generating a classed size visualization based on data
* returned from a given field or expression.
* @returns Resolves to an instance of [ClassBreaksRendererResult](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#ClassBreaksRendererResult).
* @since 4.6
* @example
* // visualization based on field and normalization field
* const sizeParams = {
* layer,
* view,
* field: "POP_POVERTY",
* normalizationField: "TOTPOP_CY",
* classificationMethod: "quantile",
* numClasses: 4
* };
*
* // when the promise resolves, apply the renderer to the layer
* const { renderer } = await createClassBreaksRenderer(sizeParams);
* layer.renderer = renderer;
* @example
* // visualization based off Arcade expression
* const sizeParams = {
* layer,
* classificationMethod: "equal-interval",
* valueExpression: "($feature.POP_POVERTY / $feature.TOTPOP_CY) * 100",
* view,
* legendOptions: {
* title: "% of people living in poverty"
* }
* };
*
* // when the promise resolves, apply the renderer to the layer
* const { renderer } = await createClassBreaksRenderer(sizeParams);
* layer.renderer = renderer;
*/
export function createClassBreaksRenderer(parameters: ClassBreaksRendererParameters): Promise<ClassBreaksRendererResult>;
/**
* Generates a continuous size [Renderer](https://developers.arcgis.com/javascript/latest/references/core/renderers/Renderer/) representing the age of features based
* on one or more fields. The age of a feature is calculated based on a given `startTime` and `endTime`, one of which
* must be a date field in the input `layer`. This method generates an Arcade expression and calculates statistics on the
* output of the expression to accomplish this. The resulting
* renderer contains a continuous size visual variable that maps optimal sizes to
* data values returned from summary statistics.
*
* You are required to provide a `layer`, `view`, `startTime`, and `endTime` to generate this renderer. Optionally, you can
* set a `unit` for the visualization. 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.
*
* @param parameters - Input parameters for generating a continuous size visualization of age for time data
* returned from start and/or end date field(s).
* @returns Resolves to an instance of [AgeRendererResult](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#AgeRendererResult).
* @since 4.9
* @example
* // visualization based age of incidents closed passed their due date
* // or the number of days an incident was overdue at the time of closure.
* const ageParams = {
* layer,
* view,
* startTime: "Due_Date",
* endTime: "Closed_Date",
* unit: "days"
* };
*
* // when the promise resolves, apply the renderer to the layer
* const { renderer } = await createAgeRenderer(sizeParams);
* layer.renderer = renderer;
* @example
* // visualization based off current age of incident
* const ageParams = {
* layer,
* view,
* startTime: "time",
* endTime: Date.now(),
* legendOptions: {
* title: "Time since earthquake struck"
* }
* };
*
* // when the promise resolves, apply the renderer to the layer
* const { renderer } = await createAgeRenderer(sizeParams);
* layer.renderer = renderer;
*/
export function createAgeRenderer(parameters: AgeRendererParameters): Promise<AgeRendererResult>;
export interface VisualVariableParamsBase extends AbortOptions {
/**
* The layer for which the renderer
* 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.
*/
layer: FeatureLikeLayerOrAdapter;
/**
* 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.
*/
field?: string | null;
/**
* 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.
*/
normalizationField?: string | null;
/**
* Defines the size theme.
* For gridded datasets, the default is `reference-size`. For all other datasets, the default is `high-to-low`.
* | Value | Description
* | ----- | -----------
* | high-to-low | The max data value is assigned the max size. The min data value is assigned the min size. All other values are interpolated.
* | above | The max data value is assigned the max size. The average data value is assigned the min size. All other values between the max data value and the average are interpolated. This is useful for mapping an increase in a variable over time, like an increase in population, or unemployment between two dates.
* | below | The min data value is assigned the max size. The average data value, is assigned the min size. All other values between the min data value and the average are interpolated. This is useful for mapping a decline in a variable over time, like a decrease in population, or unemployment between two dates.
* | reference-size | _Since 4.30_ When defined, creates a proportional size renderer with an outer ring that functions as a reference line representing the maximum data value (or other threshold). The ring is proportionally filled by an inner dot based on the feature's data value specified in `field` (and `normalizationField` if defined). This is a good style for visualizing ratios and percentages. It works best for gridded datasets where geometries don't overlap, such as styles for binning (i.e. `forBinning = true`), hexbin layers, or any other layer created with data aggregated to tessellated shapes. This theme only applies to layers with a `polygon` geometry type, or any layer that has [binning](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/) enabled. This theme is ignored if `valueExpression` is specified in lieu of a `field`.
* | spike | _Since 4.33_ When defined, creates a spike symbol whose height is scaled based on the value of `field` and `normalizationField`. This theme works best for skewed datasets. This theme only applies to layers with a `polygon` or `point` geometry type. This theme is ignored if `valueExpression` is specified in lieu of a `field`.
*
* @default "high-to-low"
*/
theme?: SizeThemes | null;
/**
* 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 view's background.
*/
sizeScheme?: SizeScheme | null;
/**
* An [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expression following
* the specification defined by the [Arcade Visualization Profile](https://developers.arcgis.com/javascript/latest/arcade/#visualization).
* 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`.
*/
valueExpression?: string | null;
/**
* Text describing the value returned from the `valueExpression`.
* This is used by the [Legend](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/).
*/
valueExpressionTitle?: string | null;
/**
* 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.
*/
sqlExpression?: string | null;
/**
* 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.
*/
sqlWhere?: string | null;
/**
* 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](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/).
*/
legendOptions?: VisualVariableLegendOptions | null;
/**
* A statistics object generated from the [summaryStatistics](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/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.
*/
statistics?: SummaryStatisticsResult | null;
/**
* 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 size visual variable.
*/
minValue?: number | null;
/**
* 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 size visual variable.
*/
maxValue?: number | null;
/**
* Indicates whether
* symbol sizes should vary based on view scale. When set, a valid [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/)
* instance must be provided in the `view` parameter. This option is not supported for 3D
* [SceneViews](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
*
* @default false
*/
sizeOptimizationEnabled?: boolean | null;
/**
* Options for specifying the symbol used in a reference size visualization. When defined, creates a proportional size renderer with an outer ring
* that functions as a reference line representing a maximum data value (or threshold). The ring is proportionally filled by an inner
* dot based on the feature's data value specified in `field` (and `normalizationField` if defined). This is a good style for visualizing
* ratios and percentages. It works best for gridded datasets where geometries don't overlap, such as styles for
* binning (i.e. `forBinning = true`), hexbin layers, or any other layer created with data aggregated to tessellated
* shapes. This parameter only applies to layers with a `polygon` geometry type, or any layer that has [binning](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/) enabled.
* This parameter is ignored if `valueExpression` is specified in lieu of a `field`.
*
* @since 4.30
*/
referenceSizeOptions?: ReferenceSizeParameters | null;
/**
* Options for specifying the symbol used in a spike theme.
*
* @since 4.33
*/
spikeOptions?: SpikeOptions | null;
/**
* 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 otherwise result in undesired size ranges and stops. 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.
*
* @since 4.31
*/
filter?: FeatureFilter | null;
/**
* 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](https://developers.arcgis.com/javascript/latest/references/core/layers/support/AggregateField/) defined in the `featureReduction` property of the layer.
*/
forBinning?: boolean | null;
/**
* The view where the input layer is rendered. This method
* inspects the view's background (i.e. basemap, web map background, or view container) to determine optimal
* colors for the output renderer. This parameter should always be set in practice, but if not provided this method
* will assume the generated renderer will display on a light background. This parameter is required when creating
* renderers using a `valueExpression` or for renderers intended for display in a SceneView.
*/
view?: MapViewOrSceneView | null;
}
export interface VisualVariableResultBase {
/**
* An array of size visual
* variables configured based on the statistics of the data and the view scale.
*/
visualVariables: SizeVariable[];
/**
* 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.
*/
defaultValuesUsed: boolean;
/** Basic statistics returned from a query to the service for data from the given field name or expression. */
statistics: SummaryStatisticsResult;
/**
* Indicates if the polygon layer used to generate the renderer
* was determined to be gridded. This is done when `referenceSizeOptions` are set for creating
* a reference size visualization.
*
* @since 4.30
*/
isGrid?: boolean;
/** The size scheme used by the visual variables. */
sizeScheme?: SizeScheme | null;
/** The ID of the basemap used to determine the optimal fill color of the features. */
basemapId?: string | null;
/** Indicates whether the average color of the input view's basemap is `light` or `dark`. */
basemapTheme?: BasemapTheme | null;
}
export interface VisualVariableParameters extends VisualVariableParamsBase {
/**
* Indicates if the size units of the symbols will be in meters. This should be `true`
* when generating visualizations with 3D volumetric symbology.
*/
worldScale?: boolean | null;
/**
* 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.
*
* @default "all"
*/
axis?: "all" | "height";
}
/**
* The result object of the [createVisualVariables()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#createVisualVariables) method. See the table
* below for details of each property.
*/
export interface VisualVariableResult extends VisualVariableResultBase {
/**
* Authoring information related to the
* creation of the visual variable. This includes information related to UI inputs from sliders and selected themes.
*/
authoringInfo: AuthoringInfo;
}
export type SymbolType = "2d" | "3d-flat" | "3d-volumetric" | "3d-volumetric-uniform";
export interface SpikeOptions {
/**
* The minimum height of the spike symbol in points.
*
* @default 5
*/
minHeight?: number;
/**
* The maximum height of the spike symbol in points.
*
* @default 112.5
*/
maxHeight?: number;
/**
* The width of the base of the spike in points.
*
* @default 5.33
*/
baseWidth?: number;
/**
* The width of the spike outline in points.
*
* @default 0.75
*/
strokeWidth?: number;
/**
* The default height of the spike symbol in points.
*
* @default 15
*/
defaultHeight?: number;
/**
* Defines the symbol configuration to use in a spike visualization.
*
* @default "triangle-solid-fill-open-outline"
*/
symbolStyle?: SpikeSymbolStyle;
}
export interface ReferenceSizeParameters {
/**
* Defines the symbol shape to use in a reference size visualization. Using a `circle` shape works
* best across a variety of datasets, but other shape options are available for visualizing layers representing
* tessellated grids of other shapes.
*
* @default "circle"
*/
symbolStyle: "circle" | "diamond" | "hexagon-flat" | "hexagon-pointy" | "square";
}
export interface ContinuousRendererParameters extends VisualVariableParamsBase {
/**
* 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.
*
* | Value | Description |
* | ----- | ----------- |
* | 2d | Generates a visualization using 2D symbols such as [SimpleMarkerSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleMarkerSymbol/), [SimpleLineSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleLineSymbol/), or [SimpleFillSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleFillSymbol/). Use this option if generating a visualization for data in a [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/). |
* | 3d-flat | Generates a visualization using 3D symbols with flat symbol layers such as [IconSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/IconSymbol3DLayer/), [LineSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/LineSymbol3DLayer/), or [FillSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/FillSymbol3DLayer/). Use this option if generating a 2D visualization for data in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). |
* | 3d-volumetric | Generates a visualization using 3D symbols with volumetric symbol layers such as [ObjectSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/ObjectSymbol3DLayer/), [PathSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/PathSymbol3DLayer/), or [ExtrudeSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/ExtrudeSymbol3DLayer/). Use this option if generating a 3D visualization for data in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/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-uniform | Generates a visualization using uniformly sized 3D symbols with volumetric symbol layers. Use this option if generating a 3D visualization for data in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/) and the symbol should be sized uniformly, for example with spheres. A SceneView instance must be provided to the `view` parameter if this option is used. |
*
* @default 2d
*/
symbolType?: SymbolType | null;
/**
* 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.
*
* @default true
*/
defaultSymbolEnabled?: boolean | null;
/**
* Only for polygon layers. Indicates whether the
* polygon outline width should vary based on view scale. When set, a valid [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/)
* instance must be provided in the `view` parameter. This option is not supported for 3D
* [SceneViews](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
*
* @default false
*/
outlineOptimizationEnabled?: boolean | null;
}
export interface UpdateRendererWithReferenceSizeParameters {
/**
* The layer for which the renderer
* is updated.
*/
layer: FeatureLikeLayerOrAdapter;
/** The renderer instance to update if not already set on the `layer`. */
renderer?: ClassBreaksRenderer | UniqueValueRenderer;
/** The name of a numeric field used to dynamically change the inner dot size. */
field?: string;
/**
* The name of a numeric field use to normalize the data in the
* input `field`.
*/
normalizationField?: string | null;
/**
* The size stops with which
* to update the reference size visualization. These values typically come from [SizeSlider.stops](https://developers.arcgis.com/javascript/latest/references/core/widgets/smartMapping/SizeSlider/#stops).
*/
sizeStops: SizeStop[];
/** Updates the symbol shape used in the reference size visualization. */
referenceSizeOptions?: ReferenceSizeParameters | null;
/**
* Use this property to update the
* color of the symbols.
*/
sizeScheme?: SizeScheme | null;
/**
* Only valid for reference size visualizations
* implemented in a UniqueValueRenderer. The scheme updates the colors of each category.
*/
typeScheme?: TypeScheme | null;
/** The view where the input layer is rendered. */
view: MapViewOrSceneView;
/**
* Indicates whether the renderer is intended for a binning or clustering visualization.
* If `true`, then the input field(s) in this method should refer to [aggregate fields](https://developers.arcgis.com/javascript/latest/references/core/layers/support/AggregateField/) defined in the `featureReduction` property of the layer.
*/
forBinning?: boolean | null;
/**
* Indicates whether
* symbol sizes should vary based on view scale. When set, a valid [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/)
* instance must be provided in the `view` parameter. For gridded layers (i.e.
* [isGrid is `true](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#ContinuousRendererResult)),
* size optimization is always enabled and therefore this parameter is ignored.
*
* @default false
*/
sizeOptimizationEnabled?: boolean | null;
}
export interface UpdateRendererWithSpikeParameters {
/**
* The layer for which the renderer
* is updated.
*/
layer: FeatureLikeLayerOrAdapter;
/** The renderer instance to update if not already set on the `layer`. */
renderer?: ClassBreaksRenderer | UniqueValueRenderer;
/** The name of a numeric field used to dynamically change the spike height. */
field?: string;
/**
* The name of a numeric field use to normalize the data in the
* input `field`.
*/
normalizationField?: string | null;
/**
* The size stops with which
* to update the spike visualization. These values typically come from [SizeSlider.stops](https://developers.arcgis.com/javascript/latest/references/core/widgets/smartMapping/SizeSlider/#stops).
*/
sizeStops: SizeStop[];
/**
* Use this property to update the
* color of the symbols.
*/
sizeScheme?: SizeScheme | null;
/**
* Only valid for spike visualizations
* implemented in a UniqueValueRenderer. The scheme updates the colors of each category.
*/
typeScheme?: TypeScheme | null;
/**
* Indicates whether the renderer is intended for a binning or clustering visualization.
* If `true`, then the input field(s) in this method should refer to [aggregate fields](https://developers.arcgis.com/javascript/latest/references/core/layers/support/AggregateField/) defined in the `featureReduction` property of the layer.
*/
forBinning?: boolean | null;
/** Options for specifying the symbol used in a spike theme. */
spikeOptions?: Pick<SpikeOptions, "symbolStyle" | "baseWidth" | "defaultHeight" | "strokeWidth"> | null;
}
export interface ClassBreaksRendererParameters extends AbortOptions {
/**
* The 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.
*/
layer: FeatureLikeLayerOrAdapter;
/**
* The name of the field whose data will be queried for statistics and classified.
* This property is ignored if a `valueExpression` is used.
*/
field?: string | null;
/**
* An [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expression following
* the specification defined by the [Arcade Visualization Profile](https://developers.arcgis.com/javascript/latest/arcade/#visualization).
* 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.
*/
valueExpression?: string | null;
/**
* Text describing the value returned from the `valueExpression`.
* This is used by the [Legend](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/).
*/
valueExpressionTitle?: string | null;
/**
* Indicates how the data is normalized.
* The data value obtained from the `field`
* is normalized in one of the following ways before it is compared with the class breaks. See the
* table below for a list of possible values.
*
* Possible Value | Description
* ---------------|------------
* field | Divides the `field` value by the value of `normalizationField`. This value is set by default if the `normalizationField` is provided.
* log | Computes the base 10 logarithm of the data value. This can be a useful approach for some data distributions because it reduces the influence of very large data values.
* percent-of-total | Divides the data value by the sum of all data values then multiplies by 100. Use `normalizationTotal` to define the total value by which to normalize. This value is set by default if the `normalizationTotal` is provided.
*
* With the exception of `log` normalization, data normalization creates a ratio by dividing two values.
* When comparing attribute values between features, normalization minimizes the effect of varying
* map areas and the number of observations. For example, dividing the 18 to 30 year old population by the
* area of a polygon feature yields a density value that can be compared evenly with other features,
* regardless of their size.
*/
normalizationType?: NormalizationType | null;
/**
* 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.
*/
normalizationField?: string | null;
/** When `normalizationType` is `percent-of-total`, this property contains the total of all data values. */
normalizationTotal?: number | null;
/**
* The classification method used for generating breaks.
* See the table below for a list of possible values.
*
* Possible Value | Description
* ---------------|------------
* equal-interval | Divides the range of attribute values into equal-sized subranges. For example, if you specify three classes for a field whose values range from 0 to 300, this method will create three classes with ranges of 0–100, 101–200, and 201–300. Equal interval is best applied to familiar data ranges, such as percentages and temperature. This method emphasizes the amount of an attribute value relative to other values. For example, it could show if a store is part of the group of stores that make up the top one-third of all sales.
* natural-breaks | Groups similar values that maximize the differences between classes. Features are divided into classes whose boundaries are set where there are relatively big differences in the data values. Natural breaks are data-specific classifications and not useful for comparing multiple maps built from different underlying information.
* quantile | Assigns the same number of data values to each class. This is well suited to linearly distributed data. Because features are grouped in equal numbers in each class, the resulting map can often be misleading. Similar features can potentially be placed in adjacent classes, or features with widely different values can be put in the same class. You can minimize this distortion by increasing the number of classes.
* standard-deviation | Creates class breaks with equal value ranges that are a proportion of the standard deviation. This is usually done at intervals of one, one-half, one-third, or one-fourth standard deviations from the mean.
*
* @default equal-interval
*/
classificationMethod?: ClassificationMethod | null;
/**
* If a `standard-deviation` classification method is used, then this indicates the interval by which to generate class breaks.
*
* **Possible Values:** 1 | 0.5 | 0.33 | 0.25
*
* @default 1
*/
standardDeviationInterval?: StandardDeviationInterval | null;
/**
* The number of class breaks to generate. This is ignored if a `standard-deviation` classification method is specified.
*
* @default 5
*/
numClasses?: number | null;
/**
* 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 view's background.
*/
sizeScheme?: SizeScheme | null;
/**
* Provides options for setting a title to describe a field
* instead of using the field name. This title will represent the field in the [Legend](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/).
*/
legendOptions?: RendererLegendTitleOption | null;
/**
* 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.
*
* | Value | Description |
* | ----- | ----------- |
* | 2d | Generates a visualization using 2D symbols such as [SimpleMarkerSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleMarkerSymbol/), [SimpleLineSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleLineSymbol/), or [SimpleFillSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleFillSymbol/). Use this option if generating a visualization for data in a [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/). |
* | 3d-flat | Generates a visualization using 3D symbols with flat symbol layers such as [IconSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/IconSymbol3DLayer/), [LineSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/LineSymbol3DLayer/), or [FillSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/FillSymbol3DLayer/). Use this option if generating a 2D visualization for data in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). |
* | 3d-volumetric | Generates a visualization using 3D symbols with volumetric symbol layers such as [ObjectSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/ObjectSymbol3DLayer/), [PathSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/PathSymbol3DLayer/), or [ExtrudeSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/ExtrudeSymbol3DLayer/). Use this option if generating a 3D visualization for data in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/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-uniform | Generates a visualization using uniformly sized 3D symbols with volumetric symbol layers. Use this option if generating a 3D visualization for data in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/) and the symbol should be sized uniformly, for example with spheres. A SceneView instance must be provided to the `view` parameter if this option is used. |
*
* @default 2d
*/
symbolType?: SymbolType | null;
/**
* 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.
*
* @default true
*/
defaultSymbolEnabled?: boolean | null;
/**
* Only for polygon layers. Indicates whether the
* polygon outline width should vary based on view scale. When set, a valid [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/)
* instance must be provided in the `view` parameter. This option is not supported for 3D
* [SceneViews](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
*
* @default false
*/
outlineOptimizationEnabled?: boolean | null;
/**
* A minimum value set by the user. Use this in conjunction with `maxValue` to
* generate class breaks between lower and upper bounds. This will be the lower bound of the lowest class break.
*/
minValue?: number | null;
/**
* A maximum value set by the user. Use this in conjunction with `minValue` to
* generate class breaks between lower and upper bounds. This will be the upper bound of the highest class break.
*/
maxValue?: number | null;
/**
* 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](https://developers.arcgis.com/javascript/latest/references/core/layers/support/AggregateField/) defined in the `featureReduction` property of the layer.
*/
forBinning?: boolean | null;
/**
* 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.
*
* @since 4.31
*/
filter?: FeatureFilter | null;
/**
* The view where the input layer is rendered. This method
* inspects the view's background (i.e. basemap, web map background, or view container) to determine optimal
* colors for the output renderer. This parameter should always be set in practice, but if not provided this method
* will assume the generated renderer will display on a light background. This parameter is required when creating
* renderers using a `valueExpression` or for renderers intended for display in a SceneView.
*/
view?: MapViewOrSceneView | null;
}
/**
* The result object of the [createContinuousRenderer()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#createContinuousRenderer) method. See the table
* below for details of each property.
*/
export interface ContinuousRendererResult extends VisualVariableResultBase {
/**
* The renderer object configured to best
* match the view's background and the spread of the data. Set this on a layer's `renderer` property to
* update its visualization.
*/
renderer: ClassBreaksRenderer;
}
/**
* The result object of the [createClassBreaksRenderer()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#createClassBreaksRenderer) method. See the table
* below for details of each property.
*
* @since 4.6
*/
export interface ClassBreaksRendererResult {
/**
* The renderer object configured to best
* match the view's background and the spread of the data. Set this on a layer's `renderer` property to
* update its visualization.
*/
renderer: ClassBreaksRenderer;
/** The size scheme used by the visual variables. */
sizeScheme?: SizeScheme | null;
/**
* Indicates whether default values are used in the absence of sufficient
* data