ArcGIS Runtime SDK for iOS

Symbol types

This topic describes the available types of symbols in ArcGIS Runtime. The following topics describe other aspects of working with symbols:

A symbol defines display properties for features and graphics (collectively referred to as geoelements). A geoelement has a geometry (location and shape), and optional descriptive information. For features and graphics to appear on a map, they must be assigned a symbol. ArcGIS Runtime uses two different models for defining symbols in your map: Simple and advanced. In general, simple symbols are single-layer symbols that provide basic symbols, such as marker, line, fill, text, or picture. Advanced symbols are composed of one or several layers that can be defined individually and combined to create complex cartographic representations. Both of these are more fully described as follows:

  • Simple symbols follow the web map specification and you can create and work with them through the simple symbol classes in the API. These are also the symbols you get from web maps or from feature services when advanced symbology is turned off. Simple symbols can be created for points (marker symbols), lines (line symbols), and polygons (fill symbols). Each of the simple symbol types provides an enumeration of pre-defined styles that can be applied to the symbol.
  • Multilayer (advanced) symbols, accessed through multilayer symbol classes, follow the ArcGIS Pro symbol model. These symbols come from feature services (that use advanced symbology), mobile style files, the dictionary renderer, and mobile map packages. You can also build your own multilayer symbols for points, lines, and polygons in the map, as described in this topic.
A map that uses a variety of simple and multilayer symbols

Simple symbology is the symbology of the web map. When authoring maps in ArcGIS Pro as web maps, your multilayer 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 are simplified while representing the original symbol as closely as possible. If you're authoring a feature service from ArcGIS Pro or ArcGIS Desktop, however, both the original symbols and the simplified symbols are stored. This allows clients that support advanced symbols to render the features as originally symbolized, while those that do not support advanced symbols (such as ArcGIS Online Map Viewer) can use the simple symbols for display. Having both sets of symbols allows you to retain the advanced symbology where available and still share the feature service as widely as possible.

If your app works primarily with web maps that you want to look the same throughout the platform, your app should use the simple symbols API. Otherwise, make sure your users understand that multilayer symbols render slightly differently on clients that don't support advanced symbology.

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

Note:

You can set UseAdvancedSymbology on the map's LoadSettings to control whether the map uses advanced symbols (when available) or always renders with simple symbols.

Multilayer (advanced) symbols

Multilayer symbols are based on a subset of the ArcGIS Pro symbology model. These symbols are composed of one or more symbol layers and can contain different symbol types within each layer with definable behaviors to get advanced cartographic effects. You can modify properties of individual symbol layers, or use properties of the symbol itself to apply a value (color or size, for example) to all the symbol layers it contains. With some exceptions and minor differences in behavior and appearance, these symbols can be used in both 2D (maps) and 3D (scenes).

Symbols used by web scenes are also multilayer but use a different specification than the ArcGIS Pro and ArcGIS Runtime symbols. When you read symbols from a web scene in your ArcGIS Runtime app, you get an ArcGIS Runtime representation of the multilayer symbol.

You can use ArcGIS Pro to author these complex symbol types and share them through feature services (if the service setting Use Advanced Symbology is true), mobile map packages, or mobile style files. The same multilayer symbols and the components used to build them are available in ArcGIS Runtime, allowing you to programmatically create and modify these symbols and apply them to geoelements (features or graphics) in your map.

Note:

Symbol layers in an ArcGIS Runtime multilayer symbol are in reverse order of how they appear in the JSON representation from the server.

The following summarizes features of multilayer symbology:

  • Multilayer symbols are containers for (one or more) symbol layers.
  • Each symbol layer uses a single geometry type (point, line, or polygon).
  • When applied to a geoelement, invalid symbol layers for a particular geometry type are ignored.
  • Symbol layers behave differently depending on the type of geometry they are rendering. When symbolizing a polygon feature, for example, a StrokeSymbolLayer defines the symbol for the polygon outline.
  • Each multilayer symbol class includes helper functions to change common properties (such as color and size) without having to iterate through all the layers the symbol contains.
  • Multilayer symbols share the same base class as the simple symbols (Symbol) and can be used interchangeably in your ArcGIS Runtime SDK apps.

Symbol layers

Symbol layers are the fundamental component used to build multilayer symbols. Similar to how a collection of map layers are overlaid to display a map, symbol layers in a multilayer symbol are overlaid to display a symbol. The available types of symbol layers correspond to the geometry type they are designed to render: marker layers for point, stroke layers for line, and fill layers for area. Each layer type has a unique set of properties to control its display.

A symbol can contain one or several symbol layers of the same or different type. A symbol used to render polygons, for example, might contain a fill symbol layer to render the polygon interior, a stroke symbol layer for rendering the polygon outline, and a marker symbol layer to render polygon vertices. A symbol to render a polyline might contain several stroke layers of varying widths. If a symbol contains a symbol layer that is invalid for the type of geometry it's rendering (a fill layer on a polyline, for example), that symbol layer is ignored.

The following table lists symbol types and symbol layers:

Symbol typeTypical symbol layersRole

Point symbol

Marker layers

Draw relative to the point geometry

Polyline symbol

Marker layers

Draw at specified locations relative to the line geometry

Stroke layers

Draw relative to the line geometry

Polygon symbol

Marker layers

Draw relative to the polygon outline or in the interior, depending on placement setting

Stroke layers

Draw relative to the polygon outline

Fill layers

Draw relative to the polygon interior

The following examples from ArcGIS Pro illustrate the use of marker, stroke, and fill layers to build symbols. A marker symbol is used in each example, participating in the symbols for points, lines, and polygons.

Point symbolPolyline symbolPolygon symbol
This point symbol is composed of three marker symbol layers.This polyline symbol is composed of two stroke symbol layers and one marker symbol layer.This polygon symbol is composed of a fill symbol layer, two stroke symbol layers, and a marker symbol layer.

Marker symbol layer

Marker symbol layers draw a shape or picture at a specific location relative to point geometry. They are most often used in point symbols, but they can also be included in polyline and polygon symbols to draw a symbol at locations along lines and outlines or within areas (the center of a polygon, for example).

ArcGIS Runtime includes the following types of marker symbol layers:

  • Vector marker symbol layer—Vector geometry defines the shape and appearance of the marker.
  • Picture marker symbol layer—Uses an image file (specified using a URI or image data) to define the marker.
  • Model symbol layer (scenes only)—Uses a true three-dimensional graphical model to define the marker. The model used is derived from a URI to a model in a supported Open Asset Import Library (Assimp) format.

Should you use a character marker symbol or a vector marker symbol? While a simple text symbol (AGSTextSymbol) can be used to display a character as a marker, proper display is dependent on the referenced font being available on the machine or device running the app. If the exact font is not found, which is likely to occur on many mobile devices, a fallback mechanism is used to find the best available font to use. A character marker symbol authored from ArcGIS Pro, however, is represented by a vector marker symbol. This symbol stores the geometry that represents the character, is not dependent on the font to render the shape of the marker, and displays as expected on all devices.

Line symbol layer

Line symbol layers define the appearance of a (2D or 3D) line. They might include effects to provide a dash pattern or define properties for the line end cap style. For display in a scene, they can define the 3D rendering style, such as tube, strip, or wall appearance. At version 100.5.0, AGSStrokeSymbolLayer is the only type of line symbol layer.

Stroke symbol layers draw lines and outlines using a solid or dashed symbol. They are most often used in line symbols or in polygon symbols as outlines.

Fill symbol layer

Fill symbol layers are components of symbols that cover areal geometries. They are most often used in polygon symbols.

ArcGIS Runtime includes the following types of fill symbol layers:

  • Solid fill symbol layer—Fills polygonal geometry with a single solid color (that may have a level of transparency applied).
  • Picture fill symbol layer—Uses an image file (specified using a URI or image) to define the fill.
  • Hatch fill symbol layer—Defines a pattern of uniform parallel lines.
  • Material symbol layer—Material fills are only available in mesh symbols that are applied to 3D objects. The color applied to the object is based on the specified material mode.

Symbol and layer property interaction

Most AGSSymbolLayer properties are only accessible on the symbol layer. There are some properties, however, that are also exposed for the symbol as a whole. Properties such as Color and Size, for example, can be modified either for an individual symbol layer, or for the symbol itself. For such properties, the value provided for the symbol may have an effect on the corresponding property for the symbol layers it contains. Similarly, the property value for a multilayer symbol might be determined from the values of the individual symbol layers it contains.

Some common symbol properties and their behavior in a multilayer symbol are described in the following sections. Examples are provided for each property to help illustrate how these properties interact between individual symbol layers and the symbol that contains them.

Note:

There are no notifications from a symbol or symbol layer when a property has been changed. If your app needs to respond to property changes in a symbol—as a result of a propagated change, for example— you will need to reread property values to identify changes.

Color

Most symbol layers have some type of color property that can be set directly or through the same property on the symbol that contains them. Marker, stroke, and fill symbol layers have a color property, and picture symbol layers have a tint color. Tint color is applied as a tint to the entire image in a picture symbol layer.

When getting the color (or tint color) from a symbol, the consensus value is reported. If there is no consensus (one or more layers have different colors), a null value is reported for the color. Likewise, setting a value for color on a symbol will apply that color to all layers the symbol contains.

If you don't want changes to the symbol color to propagate to some of the symbol layers it contains, you can lock the color (or tint color) for those layers. If a symbol layer is color-locked, changes to the parent symbol will not affect the symbol layer. This also means that the layer will not be considered when determining a consensus color for the symbol as a whole.

The following example illustrates the behavior of the color property for a multilayer polygon symbol:

  1. A multilayer polygon symbol has two symbol layers: layer A is a picture marker symbol with a blue tint color, and layer B is a solid fill symbol layer with a blue color. Neither layer is color-locked.
  2. The polygon symbol reports a color of blue, since both layers are blue.
  3. A tint color of red is set for the picture marker symbol layer. Since there is no longer a consensus for layer colors, the polygon symbol reports null for the color.
  4. The picture marker symbol layer is color-locked. The polygon symbol now reports a color of blue, since that is the consensus color for all color-unlocked layers.
  5. The polygon symbol color is set to green. The fill symbol layer color updates to green, and (because it's locked) the picture marker symbol layer remains red. The polygon symbol now reports a color of green.
The symbol reports its color as green since the red layer is color-locked.

Setting a color for a symbol will propagate that color to all color-unlocked symbol layers it contains, regardless of the number of nested levels of symbols and layers there are. Similarly, all nested symbols and layers are considered when determining a consensus color for a symbol.

Size

When getting the size from a multilayer point symbol, the value reported is the largest size of all the symbol layers it contains. The symbol size is updated when its symbol layer sizes change (if there is a new largest layer size). When setting a new size at the point symbol level, the size of the largest symbol layer is given the provided value, and all the smaller layers are sized proportionately. An individual symbol layer can be given a specific size without affecting the other layers.

The following example illustrates the behavior of the size property for a multilayer point symbol:

  1. A multilayer point symbol has two marker symbol layers: layer A and layer B. Both have a size of 10.
  2. The point symbol reports a size of 10 (the largest size for all layers).
  3. The size property on the symbol is set to 15. Both layers in the symbol now have a size of 15.
  4. The size of marker symbol layer A is set to 10. The size of marker symbol layer B is unchanged (15). The size for the symbol also remains 15, since that is the largest size for the layers.
  5. The size of the symbol is set to 20. The largest marker symbol layer (layer A) updates from 15 to 20. Marker symbol layer B is updated from the current value of 10 using the same proportion: 10 * (1 + 1/3) = 13.333.

Layers resize proportionately using the delta of the last and updated size values.

This behavior does not apply to nested symbols. You can have a point symbol, for example, that has a vector marker symbol layer that in turn contains a point symbol with its own set of marker symbol layers. The size of the nested point symbol (and any additional layers it may contain) is not affected by changes to the size at the top level point symbol. Likewise, changes to the size of the nested point symbol are not communicated to the top level symbol for determining the top level symbol size.

Angle

Angle for multilayer point symbols and heading for marker symbol layers is measured in degrees counterclockwise from the east, from 0 to 360. The angle for a multilayer point symbol defaults to 0. Marker symbol layers can have a separate heading value defined (which is also 0 by default). Setting a heading for a marker symbol layer does not affect the angle of the point symbol. When an angle value is set for the point symbol, however, that value is applied cumulatively to all the marker symbol layers it contains. The heading for individual symbol layers must be re-fetched in order to see the updated value.

The following example illustrates the behavior of the angle property for a multilayer point symbol:

  1. A multilayer point symbol contains a single marker symbol layer. The symbol and marker symbol layer both have the default value of 0 for angle and heading respectively.
  2. The marker symbol layer heading is set to 90. The angle value reported by the point symbol is unchanged (0).
  3. An angle of -45 is applied to the point symbol. The marker symbol layer heading is updated with the delta of the current marker symbol layer heading and the point symbol angle: 90 -45 = 45.
  4. When the symbol is rendered, the marker symbol layer will be rotated 45 degrees counterclockwise.

Width

The behavior of width for a polyline symbol (and the stroke symbol layers it contains) is identical, in most instances, to the behavior described previously for size with a point symbol. When getting the width from a multilayer polyline symbol, the value reported is the largest width of all the symbol layers it contains. The symbol width is updated when its symbol layer widths change (if there is a new largest layer width). When setting a new width at the polyline symbol level, the width of the largest symbol layer is given the provided value, and all the smaller layers are sized proportionately. An individual symbol layer can be given a specific width without affecting the other layers.

Width and size properties can have crossover effects for some symbols that contain both marker and stroke layers as follows:

  • Polyline symbol with vector marker symbol layers and solid stroke symbol layers
    • Symbol width is equal to the maximum value for marker size and stroke width.
    • Setting the symbol width adjusts the width of stroke symbol layers as well as the size of marker symbol layers.
  • Point symbol with vector marker symbol layers and solid stroke symbol layers
    • Setting the symbol size adjusts the size of marker symbol layers and the width of stroke symbol layers.
    • Symbol size is equal only to the maximum size of all marker symbol layers; stroke symbol layer width is not considered.

Unknown symbol layers or properties

The multilayer symbol specification is complex and continues to evolve outside of ArcGIS Runtime. The potential exists that some symbol layers (or properties) will not expose an API or will not be known by ArcGIS Runtime. Depending on the problem encountered, ArcGIS Runtime will handle this situation in one of the following ways:

  • If ArcGIS Runtime reads a symbol that it can render, but for which no public API is exposed, the base class for the appropriate symbol layer is returned in the layer collection.
  • The multilayer symbology specification for an existing symbol layer type might be updated to include properties that are not recognized by ArcGIS Runtime. When reading such a symbol layer, ArcGIS Runtime attempts to create it with the properties it understands. The symbol layer renders, but properties that cannot be identified are ignored.
  • In the event that a new (unrecognized) symbol layer is encountered by ArcGIS Runtime, the symbol is ignored and is not added to the symbol layer collection.

Simple (web) symbols

Depending on the type of geometry you want to symbolize, there are options available for defining your symbol. Points, lines, and polygons all have a basic symbol you can use: AGSSimpleMarkerSymbol , AGSSimpleLineSymbol , and AGSSimpleFillSymbol, respectively. You can also symbolize points using an AGS PictureMarkerSymbol and polygons with AGSPictureFillSymbol.

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

Symbol/Class Geometry Description

AGS SimpleMarkerSymbol

point, multipoint

Symbolizes points or multipoints with basic shapes

AGS PictureMarkerSymbol

point, multipoint

Symbolizes points or multipoints with images

AGS SimpleLineSymbol

polyline

Symbolizes polylines with predefined styles

AGS SimpleFillSymbol

polygon, envelope

Fills polygons or envelopes with a color and predefined styles

AGS PictureFillSymbol

polygon, envelope

Symbolizes polygons with tiled images

AGS TextSymbol

point, multipoint, polyline, polygon

Displays text

All marker symbols provide the ability to set an angle for rotating the symbol. This may be useful for showing things such as 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. When you set 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 useful when working with text.

The simple symbol types (AGSSimpleMarkerSymbol , AGSSimpleLineSymbol , and AGSSimpleFillSymbol) allow you to quickly create a symbol by choosing a style (for example, solid or cross hatched fill for polygons, solid or dashed line for polylines, and 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).

Picture symbols

Picture symbols, such as AGSPictureMarkerSymbol and AGSPictureFillSymbol, allow you to use an image to symbolize a feature. The image can be stored locally, or originate from an online source. The size of the image can be specified in your platform's device independent units (DIPs) 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 to represent traffic signals.

You can create picture marker symbols in the following ways:

  • From an image on the file system
  • Use a URL to an image
  • With a raw JSON string that defines an image
  • From an asset (resource) in your project

See Symbolize data for examples of creating picture marker symbols.

3D-specific symbols

Graphics in a scene view graphics overlay can use the same (2D) symbols discussed in this topic. ArcGIS Runtime also provides 3D-specific symbols for graphics in a scene view.

  • Simple marker scene symbols—Cone, Cube, Cylinder, Diamond, Sphere, and Tetrahedron
  • Stroke symbol layer 3D line styles—Strip, Tube
  • Model 3D symbols—Displays a 3D model file

3D symbols

Simple marker scene symbols provide a variety of styles (shapes) that can be applied. You can also set the size, color, and anchor position used for the symbol. To further control 3D display, you can also set heading, pitch, and roll.

Lines can be rendered in a scene view using a stroke symbol layer with either a Strip or Tube 3D line style. A strip displays a line that conforms to the surface of the scene, and a tube draws as a cylinder.

Note:

The dimensions of simple marker scene symbols are defined in meters. For 3D lines, strip style lines are defined using device-independent pixels (DIPs) and tubes are defined in meters.

A model symbol provides a realistic three-dimensional visualization to symbolize scene features. These models define the geometry and surface textures of real-world items such as aircraft. Create a AGSModelSceneSymbol using a 3D model file, passing the path to the file and a scale factor to the model symbol constructor. The supported model file types include Collada (.dae), 3D Max (.3ds), Blender 3d (.blend), and the formats listed in the Open Asset Import Library (Assimp). Depending on the model file's default orientation, you may have to rotate the symbol to get your model in the desired orientation.

Note:

Model scene symbols cannot be used with a static graphics rendering mode.

See Create 3D symbols for examples of creating graphics with 3D symbols.

Distance composite symbols

A distance composite symbol is a collection of several symbols. It determines which symbol to display based on the current camera distance to the graphic. While model symbols can accurately represent real-world objects when viewed close up, they may not be visible when viewed at a distance (unless the size of the object is exaggerated). A distance composite symbol allows you to display a different symbol based on the camera distance to the graphic. They are commonly used to show more simple symbols at a great distance and more complex symbols when the camera approaches the graphic, as illustrated by the following images.

When the camera is far away from the point, a red simple marker symbol displays.

A simple point is displayed when the camera is far away

As you zoom closer to the point, the symbol renders as a cone pointing in the aircraft's direction of travel.

A cone symbol shows heading at intermediate camera distance

When viewed even closer, the point displays as a model symbol, which is appropriate at this distance from the camera.

A model symbol displays at the nearest camera distance

See Create 3D symbols for examples of creating graphics with 3D symbols, including distance composite symbols.