Symbols and renderers

This topic describes the symbology and rendering options available with the ArcGIS Runtime SDK for Java. 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 layers or feature layers. You can then set the renderer on the layer to symbolize all the features or graphics in the layer. Renderers allow you to symbolize features differently based on one or more of their attribute values.

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 is specific to a geometry type (point, line, or polygon). 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. The following is a table of the symbols available in the API with the compatible geometry types and a brief description:

Symbol/ClassGeometryDescription

SimpleMarkerSymbol

Point, MultiPoint

Symbolizes points with basic shapes.

PictureMarkerSymbol

Point, MultiPoint

Symbolizes points with images.

SimpleLineSymbol

Polyline

Symbolizes lines with pre-defined styles.

SimpleFillSymbol

Polygon

Fills polygons with a color and pre-defined styles.

PictureFillSymbol

Polygon

Fills polygons with a tiled image.

TextSymbol

Point, MultiPoint, Polyline, Polygon

Displays text.

CompositeSymbol

Point, MultiPoint, Polyline, Polygon

A collection of other symbols applied in order (first to last) to produce a layering of symbols.

Depending on the type of geometry you want to symbolize, you will 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 may also choose to symbolize points or polygons using the appropriate picture symbol: PictureMarkerSymbol or PictureFillSymbol. Finally, a CompositeSymbol may be used to build more complex symbols for any type of geometry by layering a group of symbols together.

Some 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). 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 or with composite symbols (described in a following section) where you may need to arrange several symbols to represent a feature.

Text symbol with rotation and x/y offsets defined

Simple symbols

The simple symbol types (SimpleMarkerSymbol, SimpleLineSymbol, and SimpleFillSymbol) give you the ability to quickly create a symbol by choosing a predefined style, 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 PictureMarkerSymbol and PictureFillSymbol, 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, and for picture fill symbols, will be repeated (tiled) as necessary to fill the polygon it represents.

Picture marker symbols (PictureMarkerSymbol class) and picture fill symbols (PictureFillSymbol class) at version 10.2 or later can be created from an image on disk, such as a JPEG file, or from the URL to an image on a remote public machine. Remote images are downloaded once per application and cached for future use. If a URL cannot be found, an IOException is thrown from the symbol's constructor.

PictureFillSymbols are created from an image that's suitable for tiling. For example, an image of a tree can be used to create a PictureFillSymbol so that a filled polygon looks like a forest when symbolized. As you zoom in, fewer trees display in the forest since the map scale is getting closer to the image size. In a graphics layer, a minimum of four tiles are used to represent any one polygon even at the most zoomed-in level.

Note:

In a graphics layer in the default Dynamic rendering mode, images are not tiled neatly at each polygon boundary, meaning the images look disjoint across boundaries. With a graphics layer set to the Static rendering mode, images are tiled across the whole texture for a layer. Consequently, images are not disjoint across polygon boundaries.

A polygon symbolized with a repeating image using PictureFillSymbol

Composite symbols

A composite symbol is nothing more than a collection of other symbols applied in order (first to last) to produce a layering of symbols. A composite symbol can be used to symbolize any type of geometry, as long as the proper symbol types exist in its collection (fill symbols for polygons, for example).

At version 10.2 or later, composite symbols (CompositeSymbol class) allow you to apply more than one symbol to a single geometry. For example, you can apply both a SimpleMarkerSymbol and a TextSymbol to a point. A composite symbol contains a list of symbols, and symbols are drawn in the order in which they appear in the list. A composite symbol has no significant properties of its own. This means, for example, to offset a composite symbol relative to a geometry, the offset must be applied to each symbol in the list. A composite symbol can contain other CompositeSymbols but cannot contain itself.

The following examples illustrate how various composite symbols would be applied to different geometry types.

Composite symbol contentsGeometryResult

SimpleMarkerSymbol, PictureMarkerSymbol, TextSymbol

Point

All symbols are applied to the point in order. If no offsets were applied to the individual symbols, the picture marker may cover the simple marker beneath it (depending on the size of the symbols). By default, the text symbol displays using the point as the lower left of the text string, and will likely overlap with the marker symbols beneath.

SimpleMarkerSymbol, SimpleLineSymbol, SimpleFillSymbol

Point

Only the SimpleMarkerSymbol can be applied to the point. While no exceptions are thrown, line and fill symbols will not be applied.

PictureMarkerSymbol, SimpleLineSymbol

Polyline

All symbols are applied to the line, with the PictureMarkerSymbol applied to each of the line's vertices. Since they are applied before the line symbol, the marker symbols appear under the line symbol.

TextSymbol, SimpleLineSymbol, SimpleFillSymbol, PictureFillSymbol

Polygon

All symbols are applied to the polygon. Because they are applied in order, the simple fill will be covered by the picture fill (unless transparency has been set). The text symbol will be anchored at the center of the polygon's extent beneath both of the fill symbols.

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 layer 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 the Add graphics and text topic.

Note:

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

Renderers

As the name implies, a renderer is an object that determines how features in a layer are drawn (rendered) on the display. A renderer is like a collection of symbols that includes logic for applying the appropriate symbol to each feature in a layer. 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 to which features.

In a typical workflow, renderers are used to symbolize features in a feature layer, where the features will all be of the 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 (pursuant to the table above). A renderer can also be applied to a graphics layer, but should not be used for a layer 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 Java API: simple renderers, unique value renderers, and class break renderers. Their class diagram is pictured here and each is described below.

Renderer types

Simple renderer

A simple renderer (SimpleRenderer class) uses just one symbol such that all features are symbolized with the same symbol regardless of the feature's attribute values.

The following code snippet shows how to create a simple renderer for a point feature layer using a simple marker symbol:

// create a simple marker symbol for a point feature layer
SimpleMarkerSymbol sms = new SimpleMarkerSymbol(Color.BLUE, 5, STYLE.CROSS);
// create a simple renderer with the symbol created above
SimpleRenderer simpleRenderer = new SimpleRenderer(sms);
// set the renderer for the feature layer
featureLayer.setRenderer(simpleRenderer);

Unique value renderer

A unique value renderer (UniqueValueRenderer class) is used to symbolize features differently based on the value of up to three attributes. It is particularly useful when symbolizing features based on an attribute whose values represent names or categories, usually referred to as nominal data.

Caution:

When applying a renderer that uses attribute values, such as unique value or class breaks renderers, you must include the required fields in the layer's out fields. By default, only the object id and geometry fields are returned for a feature layer.

For example, the following code snippet creates a unique value renderer that assigns one symbol to cities that are state capitals (red diamonds) and another symbol to cities that are not state capitals (green circles):

// create symbols for capital, non-capital cities
SimpleMarkerSymbol SYM_CAPITAL = new SimpleMarkerSymbol(
    Color.RED, 14, Style.DIAMOND); 
SimpleMarkerSymbol SYM_NON_CAPITAL = new SimpleMarkerSymbol(
    Color.GREEN, 9, Style.CIRCLE);
 
// create renderer using these symbols
UniqueValueRenderer uvRenderer = new UniqueValueRenderer(); 
// features where attribute CAPITAL's value is Y are capitals, N are non-capitals
uvRenderer.setAttributeName1("CAPITAL");
uvRenderer.addValue(new UniqueValueInfo(new Object[] {"Y"}, SYM_CAPITAL));
uvRenderer.addValue(new UniqueValueInfo(new Object[] {"N"}, SYM_NON_CAPITAL));
 
// set the renderer on the 'cities' feature layer
citiesLayer.setRenderer(uvRenderer);

Note:

If a default symbol is not defined for a unique value renderer, only features with attribute values defined in the value collection display.

Class breaks renderer

A class breaks renderer (ClassBreaksRenderer class) is the most flexible of the renderers and is used to symbolize features based on an attribute with numerical values. Features with attribute values in the same range have the same symbol. You can manually create a class breaks renderer by crafting the desired breaks. A break can be constructed using the minimum and maximum value of the interval, and the symbol to use if the feature's attribute value falls in this interval. Breaks cannot overlap, and the range of each break includes the minimum value but does not include the maximum value.

The following code snippet creates a class breaks renderer based on the population density attribute of the feature layer. A feature with a population density of 50, in this case, falls into the second break and is symbolized using the midColor colored symbol.

// classification renderer based on population density (attribute POP07_SQMI)
ClassBreaksRenderer stateRenderer = new ClassBreaksRenderer(null, "POP07_SQMI"); 
Color midColor = new Color(128, 128, 128, 200); 
Color lighter = new Color(182, 182, 182, 200); 
Color darker = new Color(85, 85, 85, 200); 

// add breaks using min, max, and symbol for the interval
stateRenderer.addBreak(0, 50, new SimpleFillSymbol(lighter, SYM_STATE_BORDER));
stateRenderer.addBreak(50, 200, new SimpleFillSymbol(midColor, SYM_STATE_BORDER));
stateRenderer.addBreak(200, 50000, new SimpleFillSymbol(darker, SYM_STATE_BORDER));
censusByStateLayer.setRenderer(stateRenderer);

Note:

As with UniqueValueRenderer, 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 will not display.

Dictionary renderer

The dictionary renderer is a renderer that works in conjunction with a symbol dictionary for displaying specialized symbols (military, for example) in a message layer. More information about working with specialized symbols can be found in the Display military messages topic.

Change rendering for a dynamic layer

With ArcGIS for Server version 10.1 or greater, dynamic layers provide the ability to change rendering on the client for data coming from an ArcGIS for Server (non-cached) map service. Setting layer definitions and draw options on a dynamic layer allows you to control the content and the display of sub-layers within the service.

Generate a renderer on the server

For feature layers from services created with ArcGIS for Server version 10.1 or later, you can use a GenerateRendererTask to generate and return either a class breaks or a unique value renderer. The generated renderer can then be applied to the corresponding feature layer or dynamic layer in your map.

Creating a unique value renderer using the task gives you the ability to specify a color ramp from which a unique color can be retrieved for each unique symbol in the renderer. Generating a renderer for a feature layer with several unique values using GenerateRendererTask is more efficient than writing code to explicitly define each class in the renderer.

Generating a class breaks renderer with the task gives you the ability to use statistical classification methods to determine your class ranges. Rather than manually coding the minimum and maximum values for your class breaks, you can specify the number of breaks desired and use one of the following classification methods to determine the values for each break: Natural Breaks, Equal Interval, Quantile, or Standard Deviation. You can also choose to normalize your data by percent of the total, the value of another field, or by log.

The available classification methods are described briefly below.

  • Natural breaks—Creates classes based on natural groupings inherent in the data. Class breaks are identified that best group similar values and that maximize the differences between classes. The features are divided into classes whose boundaries are set where there are relatively big differences in the data values. This classification is based on the Jenks' Natural Breaks algorithm. For further information, see Univariate classification schemes in Geospatial Analysis-A Comprehensive Guide, 3rd edition; © 2006-2009; de Smith, Goodchild, Longley.
  • Equal Interval——Divides the range of attribute values into equal-sized subranges. This allows you to specify the number of intervals, and have the class breaks determined based on the value range. For example, if you specify three classes for a field whose values range from 0 to 300, this method creates 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 shows that a store is part of the group of stores that make up the top one-third of all sales.
  • Quantile—Assigns an equal number of features to each class. A quantile classification is well suited to linearly distributed data. Because features are grouped in equal numbers in each class using Quantile classification, the resulting map can often be misleading. Similar features can 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—Classification shows you how much a feature's attribute value varies from the mean for all features. Class breaks are created with equal value ranges that are a proportion of the standard deviation, at the chosen interval of 1, ½, ⅓, or ¼ standard deviations using mean values and the standard deviations from the mean. A standard deviation classification displayed with a two-color ramp, for example, can illustrate values above the mean (perhaps shown in blue) and values below the mean (shown in red).

The following image shows a class breaks renderer with 5 class breaks, using the natural breaks classification method. The class breaks renderer is for a US States layer and the classification field is the state population in the year 2000.

A class breaks renderer applied to a US States layer to show classes of population.

In this topic
  1. Symbols
  2. Renderers