ArcGIS Runtime SDK for .NET

Defining scale-based symbology using ArcGIS Runtime SDK

Unique value and class breaks renderers allow you to specify a criterion to uniquely symbolize data so the viewer can understand trends and patterns within the data. There are situations where a dataset has a lot of unique values or classes. An example is a utility network dataset. For such datasets, it may not make sense to render data at all scales. To do so, one option is to set a minimum and a maximum scale on the layer. Although with this option, the entire layer will either be shown or hidden, depending on map’s scale. Another option is to use multiple layers that reference the same data. For the correct symbology to display at the correct scale, each layer must be configured to have its own visible scale range, symbology definition, and definition expression defining the subset of data to be made visible at different scales.

These are valid options, but not the most optimal solutions as they require having to manage multiple layers representing the same dataset and are less effective in understanding trends and patterns in the data.

An ideal workflow is to use a single layer that continues to display at all scales and its features or elements switch visibility at different map scales.

At ArcGIS Runtime 100.12, ArcGIS Runtime SDKs introduced support for rendering scale-based symbol classes and alternate symbols in the mobile map package, published from ArcGIS Pro 2.9. Let’s look at a mobile map package published with ArcGIS Pro 2.9 rendered in an ArcGIS Runtime SDK application. In the map images below, the Electric Device Component layer is configured with scale-based symbols and alternate symbols. Based on the configuration, visibility and symbolization of elements change at different map scales.

In Figure 1 below, Service point and Transformer features are not visible at map scale 11000.

Map scale is 11000, Service point and Transformer elements are configured to not render at this scale.
Figure 1 : Service point and Transformer are not visible at 11000 map scale.

In Figure 2 map scale is 2500 and Service points are displayed with green squares green squareand Transformers with purple circle around a triangle Purple circle around a triangle. .


Map scale is 2500. Service point and Transformer elements displaying using scale-based symbols. In the image, features are drawn using primary symbols. Service point is rendered as green squares and transformer is rendered as purple circle around a triangle.
Figure 2: Map scale is 2500. Service point and Transformer elements are displayed using primary symbols, green squares and purple circle with a triangle respectively.

In Figure 3, as the map’s active scale progresses to 900, symbols switch to the configured alternate symbols. Service points are now drawn using a person icon and Transformers are represented with a purple rectangle around a triangle .


As the map scale progressed to 900, Service point and Transformer symbols switch to their configured alternate symbols. In this image features are using the alternate symbols. Service point is rendered as green person and transformer is rendered as black outlined purple rectangle with a triangle inside it.
Figure 3: Map scale is 900. Service point and Transformer elements are displayed using alternate symbols, green person icon and purple rectangle with a triangle respectively.

Scale-based symbols configuration in ArcGIS Pro

To better understand scale-based symbology, let’s dive into how the Electric Component Device layer’s symbology is configured in ArcGIS Pro. In Figure 4 below, the Symbology pane UI from ArcGIS Pro is illustrating UniqueValueRenderer symbol classes for the Electric Device Component layer. The position of the slider determines the scales at which unique values are visible and can be adjusted to change the visibility range. As seen in the UI, most of the unique values are configured to render at much higher scales (smaller, more zoomed-in areas).

The image is a snapshot of symbology pane from ArcGIS Pro showing unique value renderer configuration. There are symbols assigned for different unique values. Each symbol has visibility scale defined, along with its alternate symbols for fuse, service point and transformer elements.
Figure 4: The ArcGIS Pro Symbology pane with scale-based and alternate symbols configurations.

Alternate symbols configuration in ArcGIS Pro

In addition to controlling the visible scale range of each symbol class, display of the data can be further refined by assigning additional symbols to each unique value. In figure 4 above, notice symbols for Fuses (5), Service points (11), and Transformers (15). For these classes, there is more than one symbol defined, denoted by a minus sign if the group is expanded or a plus sign next to the symbol (see circled sections in the image above). These symbols are referred to as alternate symbols.

One of the most common approaches to alternate symbols is to use a complex symbol at large scales (when zoomed into a smaller area) and a simple but related alternate symbol at small scales (when zoomed out to a large area). In the ArcGIS Pro UI above, fuse symbol (5) has a visible scale range of 0–10000 with the pink circle symbol as its primary symbol. Beyond the 10000 mark, the pink circle  symbol is replaced by an electric fuse symbol . For more information on scale-based symbol classes and alternate symbols, view the ArcGIS Pro documentation.

Now that we have reviewed the conceptual side of scale-based symbols, let’s move on to the API side of things.

ArcGIS Runtime APIs to define scale-based and alternate symbol classes

With ArcGIS Runtime 100.13, developers can now control the visibility and symbology for features according to the scale at which they are displayed by defining scale-based and alternate symbols for unique values and class breaks. Note – that only multilayer symbols are supported as scale-based and alternate symbols. Simple symbols do not qualify for scale-based symbols. In this post, I will walk you through the step-by-step process for defining scale-based symbols for a unique value renderer. For ease of understanding, I will use an ArcGIS Pro UI (in Figure 4 above) as a guideline to define scale-based symbol classes via API.

Step 1) Create or provision multilayer symbols.

The first step is to gather multilayer symbols for unique values. There are two approaches for creating or defining multilayer symbols. Either create them in code using APIs or create symbols in ArcGIS Pro and package them in a mobile style file (.stylx) or as a web style. For this walkthrough, I will use symbols from a style file called Electric_Assets.stylx.

SymbolStyle APIs provide methods to open and query a style file and get access to the symbols and information in style file. A SymbolStyle object holds information about every symbol in the style file. To open a style file, use the OpenAsync method, passing the path to a style file on disk as parameter. For webstyles pass in uri of the published webstyle.

code to open style file

Step 2) Define unique values for the renderer.

Now that we have access to a style file containing symbols, we will create three unique values covering three different scenarios.

Unique value 1: The circuit breaker (4) symbol class is scale-based and has no alternate symbols.

Unique value 2: The fuse (5) symbol class is not scale-based but uses alternate symbols.

Unique value 3: The service point (11) symbol class is scale-based and has alternate symbols.

Unique value 1: Circuit breaker

In the ArcGIS Pro screen capture below, the slider ticks positions for Circuit Breaker (4) symbol class indicate that the symbol has a visibility scale range. In this case it is 24000 – 0.

The image is a expanded view of the scale-ranges defined for Circuit breaker elements.

First, fetch the circuit breaker multilayer symbol circuit breaker symbol from style file using the GetSymbolAsync method. GetSymbolAsync takes a set of keys as a parameter and returns the symbol matching the keys passed.

code to fetch circuit breaker symbol

Next, set the ReferenceProperties property on the symbol to define the visible scale range for the circuit breaker circuit breaker symbolsymbol class.

SymbolReferenceProperties contains conditional properties that are not directly used by the symbol but rather by the renderer to change how a symbol is visualized based on the state of the map and the data. The constructor for this class takes two parameters: minScale and maxScale. Values passed to these parameters determine visibility of a symbol at a certain scale. A value of 0 for min or max scale represents infinite scale.

In the code below, the Circuit breaker symbol’s reference properties are to set minScale:24000 and maxScale:0. This implies the symbol will display when the map scale is equal to or less than 24000. Then create a unique value object representing circuit breaker.

code to set circuit breaker reference properties and create a unique value

Unique value 2: Fuse

In ArcGIS Pro’s symbol configuration UI shown below, the Fuse unique value is configured to render at all scales. Its primary symbol, pink circlepink circle, switches to an alternate symbol, electric fuse , when the map scale progresses beyond 10000.

The image is a expanded view of scale-ranges and alternate symbols defined for Fuse elements.

Let’s see some code to set up unique value with similar configuration.

First, get the pink circle pink circlesymbol from style file. This will be the primary symbol for the fuse unique value.

code to get pink circle symbol

Since primary symbol, pink circle pink circle, switches to an electric fuse Electric Fuse symbolsymbol, we need to fetch electric fuse Electric Fuse symbol symbol from the style file as well.

code to open fuse symbol

Define the visible scale range for electric fuse multilayer symbol between minScale:10000 and maxScale:0 by setting its ReferenceProperties property. When the map scale is less than or equal to 10000, pink circle will switch to this electric fuse symbol .

code to set reference properties on fuse symbol

This electric fuse symbol is an alternate symbol for the Fuse unique value. To define alternate symbols for a unique value, create an AlternateSymbols collection, which is essentially a list of multilayer symbols. In this example, we only have one alternate symbol in the list.

code to create alternate symbol for fuse

Construct a unique value object for the fuse symbol class.  In ArcGIS Runtime 100.13, to support alternate symbols for a unique value, a new constructor is introduced on UniqueValue. In addition to other parameters, it takes a collection of multilayer symbols representing alternate symbols.

code to set unique value for fuse

In the code above, unique value fuse with value 5 is being configured to render at all scales. The primary symbol for the class is pink circle pink circle. As map scale progresses beyond 10000, symbol changes from pink circle pink circleto the electric fuse symbol .

Unique value 3: Service point

Refer to the Service point (11) symbol class in the ArcGIS Pro UI below. The position of slider ticks indicates that the primary symbol, green square symbol green square , is scale-based. The visible scale range for this unique value is 5000–0. Service points are only visible when the map scale is less than or equal to 5000.

There is also an alternate symbol, a green person green person icon, defined for this class with visible scale range of 1000-0. The primary symbol, green square symbol green square, is replaced with green persongreen person icon alternate symbol when the map scale progresses beyond 1000.

The image is a expanded view of the scale-ranges and alternate symbols defined for Service Point elements.

Let’s write code to define the third unique value: Service point

Get the green square symbol from the style file and set the scale range on the primary symbol, the green square , via its ReferenceProperties property. The visible scale range is set between minScale:5000 and maxScale:0. This symbol class will not draw on the map until the map scale is 5000 or less.

code to get green square and set its reference properties

Fetch the person symbol from the style file for defining an alternate symbol and define its visibility scale range. By doing so, the primary symbol, green square , will switch to the green person symbol as the map scale progresses to or beyond 1000.

code to get person symbol and set its reference properties

Create a list of multilayer symbols representing alternate symbols for service point unique value. Add the person multilayer symbol to the AlternateSymbols collection. In this example, there is only one alternate symbol in the list.

code to define alternate symbol list for service point

Create the unique value object for service point with all the inputs.

code to create unique value object for service point

After defining all three unique values (circuit breaker, fuse, service point)- create a unique value renderer. Follow through the steps and refer the code snippet below:

  1. Create a UniqueValueRenderer.
  2. Assign the field for the renderer. In this case, the field is called “assetgroup”.
  3. Define a default symbol for the renderer. Note, the default symbol is applied when no match is found for a value.
  4. Add all three unique values configured to the renderer’s UniqueValues collection.
  5. The final step is to apply the renderer to the Electric Device Component layer.
code to create a unique value renderer with all inputs

This concludes defining the scaled-based renderer via Runtime APIs. You can follow the same workflow outlined above for unique values to set up ClassBreaksRenderer with scale-based and alternate symbols. To summarize, there are multiple ways to configure scale-based and alternate symbols for a symbol class. In any given scenario, the renderer will pick only one symbol at a given map scale. If the primary symbol’s scale range falls within the map’s current active scale, the primary symbol is used. If not, symbols in the alternate symbols list are iterated through and the first symbol matching the current map scale is picked for rendering. A symbol becomes visible if the map scale is less than or equal to the symbol’s minimum scale and greater than the symbol’s maximum scale. If a symbol class has an invalid scale range, the symbol won’t render for that class.

About the author

Preeti Maske is Principal Product Engineer at Esri and within ArcGIS Runtime development she is a product owner for Symbology feature team. She has 20+ years of experience working with ArcGIS products and platform. She is passionate about symbology in maps and works closely with other part of ArcGIS system like ArcGIS Pro, ArcGIS Online to ensure symbology advancements that are relevant to ArcGIS Runtime are made available to ArcGIS Runtime users. She focuses on bringing best experience to ArcGIS Runtime users when it comes to authoring maps with beautiful vector symbols or consuming maps authored from other parts of ArcGIS System.

Notify of
Inline Feedbacks
View all comments

Next Article

UC 2024 ArcGIS Security & Privacy Cheat Sheet

Read this article