ArcGIS Runtime SDK for .NET

Symbols, styles, and renderers

Symbols define all the non-geographic aspects of a graphic or feature's appearance, including color, size, border, and transparency. You can apply a symbol directly to individual graphics when you create them. You can also use symbols to create a renderer for graphics overlays or feature layers.

With a renderer, you can:

  • Use one symbol for all features in a layer (or all graphics in an overlay), regardless of attribute values
  • Symbolize features in a layer (or graphics in an overlay) differently based on one or more of their attribute values

The only way to set symbols on features is to use a renderer.

Some layer types that don't support symbols & renderers, like WMS, have styles as an alternative. Styles provide options for how content is presented.

Symbols

Remember that a symbol is not the thing being represented on the map. Instead, it controls how those things (graphics or features) display. The relationship is similar, for example, between the words you are reading now (the content) and the font that is used to display them (presentation). Changing the font style, size, and color will not change the meaning of the text, but is likely to have an impact on the effectiveness of the presentation. Likewise, the quality of a map's presentation can improve with the proper use of symbols to convey information.

Each symbol type can be used to symbolize specific geometry type(s). Whether you're applying a symbol directly to a graphic or using a symbol to create a renderer, ensure the geometry type of the graphic or feature being symbolized is compatible with the symbol you want to use.

ArcGIS Runtime uses two different symbol models depending on the data source and how you access that data source.

The simple symbol classes follow the web map specification. You access these symbols through the simple symbology API, or get these symbols from web maps and feature services when advanced symbology is turned off.

Advanced symbols, accessed through multilayer symbol classes, follow the ArcGIS Pro symbol model. These symbols come from feature services, mobile style files, the dictionary renderer, and mobile map packages.

Simple (web) symbols

The following is a table of the symbols available in the API with the compatible geometry types and a brief description:

Symbol/Class Geometry Description

SimpleMarkerSymbol

point, multipoint

Symbolizes points or multipoints with basic shapes.

PictureMarkerSymbol

point, multipoint

Symbolizes points or multipoints with images.

SimpleLineSymbol

polyline

Symbolizes polylines with pre-defined styles.

SimpleFillSymbol

polygon, envelope

Fills polygons or envelopes with a color and pre-defined styles.

TextSymbol

point, multipoint, polyline, polygon

Displays text.

Depending on the type of geometry you want to symbolize, you'll have different options available for defining your symbol. Points, lines, and polygons all have a basic symbol you can use: SimpleMarkerSymbol , SimpleLineSymbol , and SimpleFillSymbol respectively. You can also symbolize points using a PictureMarkerSymbol .

All marker symbols provide the ability to set an angle for rotating the symbol. This might be useful for showing things like direction (for wind measurements or moving vehicles, for example). In addition, marker symbols have an angle alignment property that specifies whether your marker symbol remains screen-aligned or map-aligned when the map rotates. The default for all marker symbols is screen-aligned, meaning that the symbol will not rotate with the map. Setting the angle alignment property to map-aligned, the symbol will rotate with the map. This is important in cases where the symbol's angle indicates a direction on the map. You may also have the ability to define an x or y offset, meaning the symbol displays at a specified distance from the location of the feature it represents. This can be especially useful when working with text.

The simple symbol types ( SimpleMarkerSymbol , SimpleLineSymbol , and SimpleFillSymbol ) give you the ability to quickly create a symbol by choosing a style (for example solid or cross hatched fill for polygons; solid or dashed line for polylines; square or circle marker for points), setting a color, and defining a size (for markers) or width (for lines). For markers and fills, you can also define an outline symbol (using a line symbol).

The following example creates a simple marker symbol and a text symbol to display on the map.

// create a red circle marker symbol
var markerSym = new SimpleMarkerSymbol
{
    Style = SimpleMarkerSymbolStyle.Circle,
    Color = Color.Red,
    Size = 12
};


// create a text symbol
var textSym = new TextSymbol
{
    Angle = -55,
    Color = Color.Red,
    Size = 18,
    Text = "You are here",
    HorizontalAlignment = Esri.ArcGISRuntime.Symbology.HorizontalAlignment.Left,
    VerticalAlignment = Esri.ArcGISRuntime.Symbology.VerticalAlignment.Bottom
};


// create a graphic that uses the marker symbol
var pointGraphic = new Graphic(point, markerSym);


// create a graphic that uses the text symbol
var textGraphic = new Graphic(point, textSym);


// add the graphics to a graphics overlay in the map view
var graphics = MyMapView.GraphicsOverlays[0].Graphics;
graphics.Add(pointGraphic);
graphics.Add(textGraphic);

Text symbol with angle defined

Picture symbols

Picture symbols, such as PictureMarkerSymbol, allow you to use an image to symbolize a feature. The image may be stored locally, or come from an online source. The size of the image can be specified in your platforms device independent units in the same way as your other application resources.

Picture marker symbols can be created from an image on disk, such as a JPEG file, or from the URL to an image on a remote machine accessible without security. Remote images are downloaded once per application and cached for future use; for this reason they are loadable resources.

Picture marker symbols created from a variety of sources (file, app resource and URL).

There are various ways to create picture marker symbols. For example:

You can create a picture marker symbol from a URL:

// create a new PictureMarkerSymbol with an image file stored online (.png, .jpg, .bmp)
var picUrl = @"http://sampleserver6.arcgisonline.com/arcgis/rest/services/Recreation/FeatureServer/0/images/e82f744ebb069bb35b234b3fea46deae";
PictureMarkerSymbol picMarkerSym = new PictureMarkerSymbol(new Uri(picUrl));


// apply the symbol to a new graphic and add it to a graphics overlay in the map view
var graphic = new Graphic(location, picMarkerSym);
MyMapView.GraphicsOverlays[0].Graphics.Add(graphic);

You can create a picture marker symbol from a resource in the project:

// create a new PictureMarkerSymbol with an image resource in the project
var stream = Helpers.ResourceLoader.GetEmbeddedResourceStream(Assembly.GetAssembly(typeof(Helpers.ResourceLoader)), "campsite.png");
var pictureMarkerSym = await PictureMarkerSymbol.CreateAsync(stream);

// apply the symbol to a new graphic and add it to a graphics overlay in the map view
var graphic = new Graphic(location, pictureMarkerSym);
MyMapView.GraphicsOverlays[0].Graphics.Add(graphic);

You can create a picture marker symbol from a raw Json string:

// create a new PictureMarkerSymbol from a Json string
var picJson = "{\"type\":\"esriPMS\"," + 
    "\"imageData\":\"iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABHNCSVQICAgIfAhkiAAAAldJREFUWIXtl" +
    "81O20AQx/dL6ZYcQpCsRBhQVLxxiWxz4IDKoRwIL8CJcw48RpA4BUGUiAOQhEbm0IAQkht4qxzKG/DvoWLJAhHFBCykjrQHyzM" +
    "7v50Ze2cI+ciyubmJjY0NXF9d492dl9fK4JyDUYaVbyuxAURcw8FgQG5vbwkhhPy+uYm7DWFxDUEw/JAAAO69UpoAwLhkTBGIH" +
    "4KPGwFTEojA/yI0IpBECgxJPAVJALxpCg4ODl74d38eYG9v7/k9Ly4u4DgOOOewLAutVmukkeu6oJSCUgrfD0bq1et1TE5OgnM" +
    "O13VxeXk5GmR3dxdSSr2xZVkIw/BJg2GAwF98UqfZbCKTyWi9dDqNRqMxGiCKIvi+DyGENioUCmi324+MDIDgMUCtVkMulwNjD" +
    "JRSCCGwtLT0fBqOjo7huq6G4JxDKYXDw0PDuFgsaoDFBwA7OzuwbdtwHgQBTk9P/6222sdtzH+ZB2MMjDGdv2EIA2DxHmB7exszM" +
    "zPaOeccnueh1zt7WWF3u11MT0+DMQZCCIQQUErpwlRKPQKoVqvI5/PahjEGpRSiKIrXM/V+9jDxeUKfhjGGubk5bG1tYXZ21qiT" +
    "SqWCbDZr6OZz+dd3y+dn57BtG5xz7VAIoR3dOXv4vlQqja9VD8MQjuPowiSEaGcPVyr1CcvLy+OfE36cdLHwdcH4RIcXIQRSSq" +
    "x+X327IeWkcwLP84xw3y0pJcpr5befkDqdDkqlkgEhpcT6+vr7jWdhN4Qz//fOSKVSrzp57Hu0/6uP/lWfTE1Nkf39/Vd0BAnLH" +
    "3KRNn8UVI54AAAAAElFTkSuQmCC\"," +
    "\"contentType\":\"image/png\"," +
    "\"width\":0,\"height\":0,\"angle\":0," +
    "\"xoffset\":0,\"yoffset\":0," + 
    "\"xscale\":1,\"yscale\":1}";
// pass the URI to the image to the symbol constructor
var pictureMarkerSym = Symbol.FromJson(picJson);


// apply the symbol to a new graphic and add it to a graphics overlay in the map view
var graphic = new Graphic(location, pictureMarkerSym);
MyMapView.GraphicsOverlays[0].Graphics.Add(graphic);

Multilayer (advanced) symbols

Multilayer symbols are based on a subset of ArcGIS Pro's symbology model. These symbols have multiple layers and can contain different symbol types within each layer with definable behaviors to get advances cartographic effects. You can use ArcGIS Pro to author these complex symbol types and share them through feature services using the Use Advanced Symbology property, which by default is set to true. Multilayer symbols are also used in mobile map packages, mobile style files, and the dictionary renderer.

The MultilayerSymbol base class lets you get and set the color of your symbol. How the color value is returned or applied depends on how the symbol was authored.

The MultilayerPointSymbol class allows you to change the angle of the symbol and the angle alignment. Setting the angle will affect all symbol layers, but the resulting rotation will depend on how the symbol was authored. The default value for the angle alignment property also depends on how the symbol was authored, but can be changed.

The MultilayerPointSymbol class has a size property, and MultilayerLineSymbol has a width property. Changing these will affect all layers of the symbol proportionally.

Applying a symbol to a graphic

Graphics are in-memory features that provide a basic way to display geometry on the map. Graphics are unique in that they can be symbolized using a renderer for the overlay that contains them (described later in this topic) or by applying a symbol directly to the graphic. For a description of how to work with graphics, see Add graphics and text to graphics overlays.

The following example shows how to create a point graphic, apply a symbol, then display it on the map.

// define a map point using Web Mercator coordinates
var point = new MapPoint(-226773, 6550477, SpatialReferences.WebMercator);

// create a red circle marker symbol
var markerSym = new SimpleMarkerSymbol
{
    Style = SimpleMarkerSymbolStyle.Circle,
    Color = System.Drawing.Color.Red,
    Size = 12
};

// create a graphic with the map point and the symbol
var pointGraphic = new Graphic(point, markerSym);

// add the graphic to a graphics overlay in the map view
MyMapView.GraphicsOverlays[0].Graphics.Add(pointGraphic);

Note:

A symbol applied directly to the graphic overrides any symbols applied through the layer's renderer.

Working with simple and multilayer symbols

Simple symbology is the symbology of the web map. When authoring maps in ArcGIS Pro as web maps, it is important to note that your symbols will be converted to simple symbols. In general, point symbols are converted to picture marker symbols optimized for the web, and line and polygon symbols will be simplified while representing the original symbol as closely as possible.

If your app works primarily with web maps that you want to look the same throughout the platform, then your app should use the simple symbols API. If you use multilayer symbols and try to save your map as a web map, the save will fail, and forcing it to be saved will drop the symbols.

If your maps are used only with ArcGIS Runtime and ArcGIS Pro, then you can use multilayer symbols. Multilayer (advanced) symbols are vectorized in these environments, thereby scaling better on devices with high resolution screens.

Renderers

As the name implies, a renderer is an object that determines how features or graphics in a layer should be rendered (drawn) on the display. The renderer then draws them using symbols. A renderer includes logic for applying the appropriate symbol to each feature in a layer or each graphic in an overlay. There are a variety of renderer types, each designed to use a different rendering logic. Most renderers use attribute values to determine which symbol should be applied.

In a typical workflow, renderers are used to symbolize features in a feature layer, where the features are all of same geometry type. It's up to you to create a renderer with symbols that can be applied to the geometry type of the layer (as listed the table above). A renderer can also be applied to a graphics overlay, but should not be used for an overlay that has graphics of mixed geometry types. For such a scenario, applying a symbol to each graphic as it's created is the preferred workflow.

There are several types of renderers you can create using the Runtime API including simple renderers and unique value renderers. Each is described below.

Simple renderer

A simple renderer uses one symbol for all features in a layer (or all graphics in an overlay) regardless of attribute values.

Unique value renderer

A unique value renderer symbolizes features in a layer (or graphics in an overlay) differently based one or more of their attribute values. It's particularly useful when symbolizing features based on an attribute whose values represent names or categories, usually referred to as nominal data. Unlike graphics, features do not have a symbol property and therefore cannot be assigned an individual symbol. However, you can use a unique value renderer to set symbology on a layer based on each feature's attribute values. (You can do this for graphics, too.)

Note:

ArcGIS map services allow up to three fields to be used for unique value renderers. An ArcGIS feature service allows only one. As a developer, you can specify as many fields as you like, ensuring that the order of the fields you specify corresponds to the order of the values you specify.

Caution:

When applying a renderer that uses attribute values on a feature layer which is bound to a service feature table, you must ensure the required fields are specified in the tables outfields. When instantiating a service feature table in code, by default only the minimum set of fields required to render the features are requested (object id, geometry and renderer fields). When loading service feature tables from a map, by default all fields are requested. Be sure to override these defaults by setting the outfields before the table is loaded.

The example below creates a unique value renderer that displays US states with different symbols according to the value of their state abbreviation attribute. Since only California, Nevada, and Arizona have been defined explicitly in the renderer's UniqueValueInfoCollection, features with any other value for the state abbreviation attribute ( STATE_ABBR) display with the default (transparent) symbol.

// create a new service feature table using the USA States url
var statesFeatureTable = new ServiceFeatureTable(new System.Uri("https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3"));
// add the "STATE_ABBR" field to the outfields, will be used to render polygons in the layer
statesFeatureTable.OutFields.Add("STATE_ABBR");
// create a new feature layer using the service feature table
var statesLayer = new FeatureLayer(statesFeatureTable);

// create a new unique value renderer
var stateRenderer = new UniqueValueRenderer();
// add the "STATE_ABBR" field to the renderer
stateRenderer.FieldNames.Add("STATE_ABBR");
            
// define distinct fill symbols for a few states (use a null outline symbol)
var nevadaFillSymbol = new SimpleFillSymbol(SimpleFillSymbolStyle.Solid, System.Drawing.Color.Blue, null);
var arizonaFillSymbol = new SimpleFillSymbol(SimpleFillSymbolStyle.Solid, System.Drawing.Color.Green, null);
var californiaFillSymbol = new SimpleFillSymbol(SimpleFillSymbolStyle.Solid, System.Drawing.Color.Red, null);

// add values to the renderer: define the label, description, symbol, and attribute value for each
stateRenderer.UniqueValues.Add(new UniqueValue("Nevada", "Nevada", nevadaFillSymbol, "NV"));
stateRenderer.UniqueValues.Add(new UniqueValue("Arizona", "Arizona", arizonaFillSymbol, "AZ"));
stateRenderer.UniqueValues.Add(new UniqueValue("California", "California", californiaFillSymbol, "CA"));
            
// set the default state fill symbol (transparent with no outline) for regions not explicitly defined in the renderer
var defaultFillSymbol = new SimpleFillSymbol(SimpleFillSymbolStyle.Null, Colors.Transparent, null);
stateRenderer.DefaultSymbol = defaultFillSymbol;
stateRenderer.DefaultLabel = "Other";

// apply the unique value renderer to the states layer
statesLayer.Renderer = stateRenderer;
// add the new layer to the map
MyMapView.Map.OperationalLayers.Add(statesLayer);

Unique value renderer applied to some US states
Note:

Features whose attribute value falls outside the classes defined for the renderer are symbolized with the default symbol. If a default symbol is not defined, those features won't display.

Styles

Some layers that don’t support symbols & renderers offer styles as an alternative.

ArcGIS vector tiled layer styles

An ArcGIS vector tile layer consumes vector tiles and an associated style for drawing them. Because the style is separate from the underlying data, you can easily customize the style of an existing basemap layer. There are layers in many styles available through ArcGIS Online.

You can create your own style with the online style editor. Your customized vector layers can then be saved to and read from ArcGIS Online.

WMS styles

Styles are predefined options for how content is displayed. For example, WMS servers provide clients with a list of supported styles for each layer. At run time, you can choose which style the WMS server uses to render map images. In general, styles are predefined and cannot be changed or added to.

The styles property of the WmsLayerInfo class can be inspected to determine if there are styles available. The current style property of a WMS sublayer can be set to select a specific style.

// Search for and apply a specific style on sublayers that support it
foreach(WmsSublayer sublayer in _myWMSLayer.Sublayers)
{
    if (sublayer.SubLayerInfo.Styles.Contains("ArcGIS"))
    {
        // Set the style
        sublayer.CurrentStyle = "ArcGIS";
    }
}

Related topics