Using Renderer Elements

Using ArcXML Renderers

Introduction
SIMPLERENDERER
GROUPRENDERER
SIMPLELABELRENDERER
SCALEDEPENDENTRENDERER
VALUEMAPRENDERER
- Creating multipart symbols
- VALUEMAPRENDERER inside a SCALEDEPENDENTRENDERER
VALUEMAPLABELRENDERER
A Case Study

Introduction

The ArcXML renderers provide the framework for feature symbolization and labeling. You have already been using ArcXML renderers if you have used ArcIMS Author. The output from ArcIMS Author is a map configuration file in ArcXML format. This document assumes you are familiar with ArcIMS Author and the basic structure of a map configuration file. All the examples in this document demonstrate how to use renderers with a map configuration file. The syntax and usage are the same if you want to use the renderers in a request.

Renderers are valid only with Feature and Image Servers. They are not used with the ArcMap Server. However, symbols can be used in requests to the ArcMap Server when they are included in acetate layers.

Each ArcXML renderer includes either a symbol or a label, depending on the renderer. Only one symbol or label is allowed within a renderer. In a generalized form, the relationship between a renderer and a symbol in ArcXML is:

      <RENDERER>
        <SYMBOL />
      </RENDERER>

Six renderers are available with ArcIMS:

VALUEMAPRENDERER and VALUEMAPLABELRENDERER also have three child elements used to create value maps:

Only one symbol or label can be used inside a renderer, but the renderers can be used in different combinations to create complex symbols at different scales. The different symbols that can be used inside SIMPLERENDERER and VALUEMAPRENDERER are as follows:

Point layers
Line layers
- All the symbols valid for point layers
- HASHLINESYMBOL
- SIMPLELINESYMBOL
Polygon layers
- All the symbols valid for point and line layers
- GRADIENTFILLSYMBOL
- RASTERFILLSYMBOL
- SIMPLEPOLYGONSYMBOL

Symbols that can be used inside of SIMPLELABELRENDERER and VALUEMAPLABELRENDERER are:

In the examples below, each renderer is briefly defined, and the examples show how the renderer can be used in a map configuration file. The same concepts can be applied to renderers in requests since the syntax is the same.

The examples used in this document build on the same set of data. Two shapefiles are used: CNTRY94 (polygon) and CITIES (point). Each example is an addition or modification to the previous example.

After each renderer has been described, a section is included covering a case study using a set of shapefiles of New York City. This study is a good example of a map configuration file using all the renderers.

SIMPLERENDERER

SIMPLERENDERER is used to provide the framework for filling polygons, drawing lines, and displaying points in a layer using one symbol.

In the following example, a SIMPLERENDERER is used to describe how polygons in CNTRY94 are drawn. The symbol instructions are inside SIMPLEPOLYGONSYMBOL. In this case, a SIMPLEPOLYGONSYMBOL is used with a solid filltype and a light yellow fillcolor.

Using SIMPLERENDERER:

The resulting map shows all countries rendered in light yellow.

GROUPRENDERER

GROUPRENDERER is required when two or more renderers are used to describe a layer. For example, if you want to create a multipart symbol, you can use GROUPRENDERER to group together two SIMPLERENDERERS. Another common use for GROUPRENDERER is when both symbols and labels are applied to a layer (discussed in the next section).

In the next example, a GROUPRENDERER is used to create a multipart symbol. Inside the GROUPRENDERER are two SIMPLERENDERERS using SIMPLEPOLYGONSYMBOL. The underlying filltype is solid with a cross filltype on top. Note that the renderers and symbols are processed in the order they are read. Since the solid SIMPLEPOLYGONSYMBOL is first, it is the bottom layer.

Using SIMPLERENDERERs inside a GROUPRENDERER:

The resulting map shows all countries rendered first in light yellow with a cross pattern on top.

SIMPLELABELRENDERER

SIMPLELABELRENDERER is used to label the features in a layer using data from a specified field in the database. In this next example, SIMPLELABELRENDERER is added to the CNTRY94 layer. The field used for labeling is NAME.

In order to both label and symbolize a layer, you must use a GROUPRENDERER. The two SIMPLERENDERER elements from the previous example are grouped together with SIMPLELABELRENDERER using a GROUPRENDERER.

Using SIMPLERENDERER and SIMPLELABELRENDERER:

In the returned map, labels are included as part of the rendering for each country.

If you want a layer to be labeled without any symbology, you can do this by including only a SIMPLELABELRENDERER for the layer. In this case you do not need SIMPLERENDERER or GROUPRENDERER. The following example uses only SIMPLELABELRENDERER for the CNTRY94 layer.

Using only SIMPLELABELRENDERER:

The returned map includes only labels. In the following figure, the country boundaries are included for reference only.

SCALEDEPENDENTRENDERER

Setting scales for displaying data is a very important part of designing a map configuration file. There are two ways to use scale to control the display of features. The first way is to set a scale factor to turn a layer on and off depending on the scale. The scale factor is set in LAYER using minscale and maxscale attributes. Setting this factor is particularly important for layers with detailed data. In the following example, a Cities layer has been added to the map configuration file. This layer does not display until the scale is less than 1:50000000.

The second way to use scale is to use a SCALEDEPENDENTRENDERER to change the symbology of a layer when a specified scale is met. The layer always displays, but as you zoom in the symbology changes. For example, in the first SCALEDEPENDENTRENDERER below, in the Cities layer, when the scale is between 1:25000000 and 1:50000000, the location of the city is marked with a circle using SIMPLEMARKERSYMBOL inside a SIMPLERENDERER. In the second SCALEDEPENDENTRENDERER, when the scale threshold is less than 1:25000000, the markers change to a larger star.

A third SCALEDEPENDENTRENDERER is used to turn on labeling for Cities when the scale is 1:25000000. TEXTSYMBOL is used inside a SIMPLELABELRENDERER. The three SCALEDEPENDENTRENDERERS must be grouped inside a GROUPRENDERER.

Using SCALEDEPENDENTRENDERER:

The following figures show a map at two different scales. The map on the left is 1:50000000 and shows each city with a circle. The map on the right is at 1:25000000 and shows each city with a star and label.

VALUEMAPRENDERER

VALUEMAPRENDERER is used to classify features in a layer according to values in a specified field in the database. Based on this field, features in different classifications can be rendered differently. Value maps can be categorized using:

RANGE for graduated symbols maps. With RANGE, a range of values is used to define the category.
EXACT for unique symbols maps. With EXACT, the values in the specified field must match exactly.
OTHER, for a catch-all category for features that do not fit in any other RANGE or EXACT category. OTHER is optional to use in a value map and, if it is not used, symbols that do not fall into one of the categories are not drawn.

In the following example, the Cities layer (which does not display until the scale is less than 1:50000000) is broken into three RANGE categories using VALUEMAPRENDERER with lookupfield set to POPULATION. When assigning symbols, it is permissible to use different symbol elements within the same value map. The following example uses both SIMPLEMARKERSYMBOL and TRUETYPEMARKERSYMBOL.

The first RANGE category is for cities with fewer than 500,000 in population and uses a circle for the SIMPLEMARKERSYMBOL. The second RANGE category is for a population between 500,000 and 1,000,000 and uses a square marker. The third RANGE category is for a population greater than 1,000,000, and the marker for this category is a TRUETYPEMARKERSYMBOL.

Using VALUEMAPRENDERER:

The resulting map shows the three categories of cities based on population.

Creating multipart symbols

Multipart symbols can be created for one or more categories of a value map. To do this, additional VALUEMAPRENDERERs are used with only the RANGE or EXACT categories you are interested in. In the next example, the marker for cities with a population less than 500,000 is a three-part symbol:

The base part is a large blue circle.
The middle part is a yellow star.
The top part is a small red circle.

To make this symbol, three VALUEMAPRENDERERs are used. In the first one, the blue circle is rendered. The other RANGE categories are also included for cities with a population between 500,000 and 1,000,000 and with a population greater than 1,000,000. In the second and third VALUEMAPRENDERERs, the only RANGE included is for a population less than 500,000. All three VALUEMAPRENDERERs are grouped inside a GROUPRENDERER.

Using VALUEMAPRENDERER to create a multipart symbol:

The resulting map shows cities with a multipart symbol for cities with a population less than 500,000 plus the two additional categories of cities between 500,000 and 1,000,000 and cities greater than 1,000,000.

VALUEMAPRENDERER inside a SCALEDEPENDENTRENDERER

A VALUEMAPRENDERER can be used inside of a SCALEDEPENDENTRENDERER. In the following example, the Cities layer is divided into two SCALEDEPENDENTRENDERERs. When the scale is between 1:25000000 and 1:50000000, all cities are rendered with a blue circle using a SIMPLERENDERER. When the scale is less than 1:25000000, the value map from the previous example is used for rendering each city. City symbols are categorized by population. GROUPRENDERER is used around both SCALEDEPENDENTRENDERER elements and to group the VALUEMAPRENDERER elements.

Using VALUEMAPRENDERER inside a SCALEDEPENDENTRENDERER:

The following two figures show the same map at two scales. The first map is at 1:30000000 and shows all cities with a small circle. The second map is at 1:12000000 and symbolizes cities based on population.

SCALEDEPENDENTRENDERER with VALUEMAPRENDERER

VALUEMAPLABELRENDERER

VALUEMAPLABELRENDERER applies label formats based on different classifications in a field in a database. Labels can be categorized using RANGE, EXACT, or OTHER, similar to VALUEMAPRENDERER for feature symbolization.

In the following example, the Cities layer (which does not display until the scale is less than 1:50000000) is labeled based on three RANGEs. The RANGEs are cities with a population less than 500,000, a population of 500,000 to 1,000,000, and a population greater than 1,000,000. For each category, TEXTSYMBOL is used, but instructions for labeling are different. Small cities use the Tahoma font. Medium-sized cities use an italic Arial font with glow. Large cities use a bold italic Times New Roman font with glow and shadow.

All cities are rendered with a circle using SIMPLEMARKERSYMBOL inside a SIMPLERENDERER. Both the SIMPLERENDERER and VALUEMAPLABELRENDERER are grouped inside a GROUPRENDERER.

Using VALUEMAPLABELRENDERER:

In the resulting map, all cities are identified by a blue marker. Based on the population of the city, one of three label formats is used.

Using VALUEMAPRENDERER and VALUEMAPLABELRENDERER together

VALUEMAPRENDERER and VALUEMAPLABELRENDERER can be used within the same GROUPRENDERER. In the next example, VALUEMAPRENDERER replaces the SIMPLERENDERER information for the Cities layer. The following symbology and labels are used based on city population:

City Population Range	Symbol	Label
Less than 500,000	Circle	Tahoma font
500,000 to 1,000,000	Square	Italic Arial font with glow
Greater than 1,000,000	TrueType symbol	Bold italic Times New Roman font with glow and shadow

Using VALUEMAPRENDERER and VALUEMAPLABELRENDERER together:

In the resulting map, the marker and label assigned to each city are based on the population.

VALUEMAPLABELRENDERER with VALUEMAPRENDERER

Limiting labels to a subgroup of features

VALUEMAPLABELRENDERER can also be used to limit labeling to a subgroup of features. In the next example, only cities with a population greater than 1000000 are labeled. To do this, only one RANGE category is used inside the VALUEMAPLABELRENDERER. If a city's population does not fall within this range, then it is not labeled.

Using VALUEMAPLABELRENDERER to label a subgroup of features:

In the resulting map, only cities with a population greater than 1000000 are labeled.

VALUEMAPLABELRENDERER with cities over 1,000,000 in population

VALUEMAPLABELRENDERER inside a SCALEDEPENDENTRENDERER

VALUEMAPLABELRENDERER can be used inside a SCALEDEPENDENTRENDERER. In the next example, only cities with a population greater than 1000000 are labeled when the scale is between 1:25000000 and 1:50000000. When the scale is less than 1:25000000, all cities are labeled according to their population. A GROUPRENDERER is used around the two SCALEDEPENDENTRENDERER elements.

The following table summarizes the labels used at different scales:

	City Population Range	Label
When scale is greater than 1:25000000:
	Greater than 1,000,000	Bold italic Times New Roman font with Glow and Shadow
When scale is less than 1:25000000:
	Less than 500,000	Tahoma font
	500,000 to 1,000,000	Italic Arial font with glow
	Greater than 1,000,000	Bold italic Times New Roman font with Glow and Shadow

Using VALUEMAPLABELRENDERER inside a SCALEDEPENDENTRENDERER:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>
      <LOCALE country="US" language="en" variant="" />
      <UIFONT color="0,0,0" name="Arial" size="12" style="regular" />
    </ENVIRONMENT>
    <MAP>
      <PROPERTIES>
        <ENVELOPE minx="-180" miny="-90" maxx="180" maxy="90" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-6" directory="C:\ESRIDATA\WORLD" />
      </WORKSPACES>
      <LAYER type="featureclass" name="CNTRY94" visible="true" id="0">
        <DATASET name="CNTRY94" type="polygon" workspace="shp_ws-6" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL fillcolor="255,255,204" filltype="solid" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Cities" visible="true" id="1" maxscale="1:50000000">
        <DATASET name="CITIES" type="point" workspace="shp_ws-6" />
        <GROUPRENDERER> 
          <SCALEDEPENDENTRENDERER lower="1:25000000" > 
            <GROUPRENDERER>
              <SIMPLERENDERER>
                <SIMPLEMARKERSYMBOL color="0,0,190" width="6" type="circle" />
              </SIMPLERENDERER>

              
              <VALUEMAPLABELRENDERER lookupfield="POPULATION" labelfield="NAME" >
                <RANGE lower="1000001" upper="23620001" >
                  <TEXTSYMBOL font="Times New Roman" fontstyle="bold" fontsize="14" glowing="255,255,0" shadow="0,0,0" />
                </RANGE>
              </VALUEMAPLABELRENDERER>
            </GROUPRENDERER>
          </SCALEDEPENDENTRENDERER>

          <SCALEDEPENDENTRENDERER upper="1:25000000" >
            <GROUPRENDERER>
              
              <VALUEMAPRENDERER lookupfield="POPULATION">
                <RANGE lower="0" upper="500000" label="Less than 500000">
                  <SIMPLEMARKERSYMBOL color="0,0,255" width="16" type="circle" />
                </RANGE>
                <RANGE lower="500001" upper="1000000" label="500001 - 1000000">
                  <SIMPLEMARKERSYMBOL color="85,0,170" width="7" type="square" />
                </RANGE>
                <RANGE lower="1000001" upper="23620001" label="Greater than 1000000">
                   <TRUETYPEMARKERSYMBOL fontstyle="regular" character="169" font="Arial" fontcolor="255,0,0" fontsize="20"  />
                </RANGE>
              </VALUEMAPRENDERER>

              <VALUEMAPRENDERER lookupfield="POPULATION">
                <RANGE lower="0" upper="500000" label="Less than 500000">
                  <SIMPLEMARKERSYMBOL color="255,255,0" width="16" type="star" />
                </RANGE>
              </VALUEMAPRENDERER>

              <VALUEMAPRENDERER lookupfield="POPULATION">
                <RANGE lower="0" upper="500000" label="Less than 500000">
                  <SIMPLEMARKERSYMBOL color="255,0,0" width="4" type="circle" />
                </RANGE>
              </VALUEMAPRENDERER>

              
              <VALUEMAPLABELRENDERER lookupfield="POPULATION" labelfield="NAME" >
                <RANGE lower="0" upper="500000" >
                  <TEXTSYMBOL font="Tahoma" fontstyle="regular" fontsize="10" />
                </RANGE>
                <RANGE lower="500001" upper="1000000" >
                  <TEXTSYMBOL font="Arial" fontstyle="italic" fontsize="12" glowing="125,125,125" />
                </RANGE>
                <RANGE lower="1000001" upper="23620001" >
                  <TEXTSYMBOL font="Times New Roman" fontstyle="bolditalic" fontsize="14" glowing="255,255,0" shadow="0,0,0" />
                </RANGE>
              </VALUEMAPLABELRENDERER>
            </GROUPRENDERER>
          </SCALEDEPENDENTRENDERER>
        </GROUPRENDERER>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

The following two figures are the same map at two scales. The scale for the first map is 1:40000000. At this scale, only cities with a population greater than 1,000,000 are labeled. The scale for the second map is 1:8000000. All cities are labeled based on population.

SCALEDEPENDENTRENDERER with VALUEMAPLABELRENDERER

A Case Study

The following case study uses New York City street data to apply a combination of renderers for displaying these roads with different rendering at different scales. The map configuration file is shown here in its entirety. Take a look at this file to get a general overview. Each of the layers is discussed below.

Entire map configuration file:

The following three figures show the New York City roads displayed at different scales. Depending on the scale, the street and freeway symbols change. The first map is at 1:200000, the second is at 1:30000, and the third is at 1:20000.

There are six layers in this map configuration file. Each of the layers has been assigned an alias name as shown in the following table. The alias names are what appear in the legend.

Layer Alias Name as Seen in Legend	Shapefile Name
Background	nyc_back
City Limits	nyc_bound
Parks	nyc_parks
Water	nyc_water
Roads	nyc_roads
Roads	nyc_mainroads

Nyc_back, nyc_bound, nyc_parks, nyc_water layers

Nyc_back, nyc_bound, nyc_parks, and nyc_water use the same SIMPLERENDERER format. The nyc_back layer is shown here as an example.

Nyc_back Layer:

Nyc_mainroads

The nyc_mainroads and nyc_roads layers display at different scales, and only one of the two layers is included at any given scale. In the legend, both layers are labeled "Roads".

When the ArcIMS service is first loaded, nyc_mainroads displays. It continues to display until the scale is less than 1:35000. As a user zooms in to a scale of 1:35000, the nyc_mainroads layer turns off and the nyc_roads layer turns on.

The nyc_mainroads layer in the map configuration file is included below. First, the minscale in LAYER is set to 1:35000. This allows the layer to display only if the scale is greater than 1:35000. Second, for the rendering of this layer, a VALUEMAPRENDERER is used to divide the roads into Freeway, Secondary, and Primary roads based on the value in the field ROAD_TYPE. The road types are categorized using EXACT and are symbolized as follows:

Road Type	Symbol
Freeway	Uses a multipart line symbol of a red line with a width of two pixels on top of a black line with a width of four pixels.
Secondary	Uses a blue line symbol with a width of one pixel.
Primary	Uses a red line symbol with a width of one pixel.

The layer contains two VALUEMAPRENDERERs. The first VALUEMAPRENDERER includes Primary, Secondary, and the black line for Freeway. The second VALUEMAPRENDERER includes only the red line for the Freeway category. The VALUEMAPRENDERERs are grouped together by a GROUPRENDERER.

Nyc_mainroads layer:

The figure below shows nyc_mainroads at a scale of 1:200000. Note that in the legend the layer is listed as "Roads".

New York City main roads at a scale of 1:200000

Nyc_roads

The nyc_roads layer contains all the streets for New York City and the surrounding area. In the map configuration file, the LAYER maxscale is set to 1:35000 and does not turn on until a user zooms past a scale of 1:35000.

Using SIMPLERENDERER:

<LAYER type="featureclass" name="Roads" visible="true" id="4" maxscale="1:35000">
<DATASET name="nyc_roads" type="line" workspace="shp_ws-0" />
...
</LAYER>

The nyc_roads layer is rendered two different ways depending on the current scale using SCALEDEPENDENTRENDERER. A broad overview of the use of SCALEDEPENDENTRENDERER in the layer is shown in the next example. At a scale between 1:21300 and 1:35000, the roads are rendered in a less detailed manner. When the scale is less than 1:21300, the road rendering becomes much more detailed. A third SCALEDEPENDENTRENDERER is used for labeling. The labels do not turn on until the scale is less than 1:25000. The SCALEDEPENDENTRENDERERs are grouped together inside a GROUPRENDERER.

Using SIMPLERENDERER:

    <LAYER�>
      <GROUPRENDERER>
        <SCALEDEPENDENTRENDERER lower="1:21300">
          �less detailed rendering�
        </SCALEDEPENDENTRENDERER>

        <SCALEDEPENDENTRENDERER upper="1:21300">
          �more detailed rendering�
        </SCALEDEPENDENTRENDERER>

        <SCALEDEPENDENTRENDERER upper="1:25000">
          �label rendering�
        </SCALEDEPENDENTRENDERER>
      </GROUPRENDERER>
    </LAYER>

The following figures show a snapshot of nyc_roads at two scales. The scale for the first map is 1:30000, and the roads are less detailed. The scale for the second map is 1:20000, showing more detail in the roads.

The first SCALEDEPENDENTRENDERER with the less detailed rendering has a minimum scale set to 1:21300 (lower="1:21300"). The VALUEMAPRENDERER divides the roads into two categories based on the value in the field ROAD_TYPE: Freeway and Street. The freeways are a thick red line, and the streets are a thin blue line.

Using SCALEDEPENDENTRENDERER for nyc_roads when the scale is greater than 1:21000:

The figure below shows the map at a scale of 1:30000.

New York City streets at a scale of 1:30000

When the scale passes 1:21300, the second SCALEDEPENDENTRENDERER with more detailed rendering becomes active. Inside this SCALEDEPENDENTRENDERER is a group of VALUEMAPRENDERERs.

The first VALUEMAPRENDERER uses the two categories of Street and Freeway. The streets are a thick solid white line eight pixels wide. The freeways are a multipart line symbol. The base level of the Freeway is included inside this renderer and is a black line nine pixels wide.
The remaining three VALUEMAPRENDERERs create the rest of the multipart freeway symbol: red as the second layer seven pixels wide, black as the third layer three pixels wide, and white as the top layer one pixel wide.

Using SCALEDEPENDENTRENDERER for nyc_roads when the scale is less than 1:21000:

The third SCALEDEPENDENTRENDERER is used to set the scale for labeling. In this layer, VALUEMAPLABELRENDERER becomes active when the scale is less than 1:25000. The streets and freeways both use TEXTSYMBOL, but the instructions for drawing the labels are different. Freeways use a bold Arial font with glow. Streets use a bold Arial font without the glow.

Labeling for nyc_roads:

The following figure shows the detailed streets and freeways at a scale of 1:20000. At this scale, the labels are also included.

New York City streets at a scale of 1:20000

This case study shows different ways to use the ArcXML renderers. In summary, the basic rules for using these renderers are:

Only one symbol can be used inside a renderer.
SIMPLERENDERER and SIMPLELABELRENDERER are used when an entire layer is symbolized or labeled the same way.
VALUEMAPRENDERER and VALUEMAPLABELRENDERER are used when different categories based on a value in a field are used to symbolize and label a layer.
Two or more renderers are grouped together using GROUPRENDERER.
Multiple GROUPRENDERERs can exist within other GROUPRENDERERs.
SCALEDEPENDENTRENDERER is used to set scales for changing a layer's symbolization and labeling.