com.esri.arcgis.carto
Interface IProportionalSymbolRenderer

All Superinterfaces:
Serializable
All Known Implementing Classes:
ProportionalSymbolRenderer

public interface IProportionalSymbolRenderer
extends Serializable

Provides access to members that control the drawing of varying size symbols for each feature, each sized in proportion to a field value.

Remarks

You can use this interface to set up proportional symbol rendering for point, line, or area data. For example, if you have map tree locations as points, and an attribute reflecting the radius of the tree canopy, you can use proportional circles to depict the actual ground area covered by each tree.

If you have a feature layer of US States, you can create a population map of proportional marker symbols where there area of each symbol reflects the population for each state.

If you have a line layer representing rivers, you can symbolize these with line symbols with width proportional to the flow in each particular river line feature.

Known vs. Unknown Data Units

There are really two uses of proportional symbol rendering:

First, you can have a data field that represents an actual distance in the real world, such as the radius of a tree canopy in meters, or the width (actually diameter) of a water main in inches. In this case your units are known and you can use a ProportionalSymbolRenderer to draw a symbol on your map for each feature such that the area occupied by the feature on the map represents the actual area occupied in the real world.

Second, you may have a data field that represents a non-distance quantitiy, for example you might have county data and know the population of each county. This value does not represent a real world distance so the units are said to be unknown. In this case you can use the ProportionalSymbolRenderer to represent the relative population of each county. This is done by mapping a minimum symbol size, specified by MinSymbol, to the minimum data value of the population field. The MinSymbol is then scaled up proportionally based on the relative difference between the minimum population value and the value for a given county feature.

To learn more, see IProportionalSymbolRenderer::ValueUnit and IProportionalSymbolRenderer::ValueRepresentation.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.


Method Summary
 void createLegendSymbols()
          Creates the legend.
 IFillSymbol getBackgroundSymbol()
          Background fill symbol used when proportional marker symbols are draw on polygon features.
 String getField()
          Value field.
 int getLegendSymbolCount()
          Number of symbols displayed in the TOC and legend.
 ISymbol getMinSymbol()
          Symbol used to draw feature with the normalized minimum data value.
 String getNormField()
          Normalization field.
 int getValueRepresentation()
          Representation type of the value field.
 int getValueUnit()
          Units of the value field.
 boolean isFlanneryCompensation()
          Indicates if Flannery Compensation is applied.
 void setBackgroundSymbol(IFillSymbol sym)
          Background fill symbol used when proportional marker symbols are draw on polygon features.
 void setField(String field)
          Value field.
 void setFlanneryCompensation(boolean flag)
          Indicates if Flannery Compensation is applied.
 void setLegendSymbolCount(int num)
          Number of symbols displayed in the TOC and legend.
 void setMaxDataValue(double rhs1)
          Normalized maximum data value.
 void setMinDataValue(double rhs1)
          Normalized minimum data value.
 void setMinSymbol(ISymbol sym)
          Symbol used to draw feature with the normalized minimum data value.
 void setNormField(String field)
          Normalization field.
 void setValueRepresentation(int rep)
          Representation type of the value field.
 void setValueUnit(int unit)
          Units of the value field.
 

Method Detail

getField

String getField()
                throws IOException,
                       AutomationException
Value field.

Description

The name of the numeric field used to determine the size of the symbol drawn for each feature on the map.

Remarks

The ProportionalSymbolRenderer can only draw features with with field values greater than zero. If Field contains values less than or equal to zero, you should use IDataExclusion to exclude these features from drawing.

To use normalization specify a field name for NormField.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The field
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setField

void setField(String field)
              throws IOException,
                     AutomationException
Value field.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
field - The field (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getNormField

String getNormField()
                    throws IOException,
                           AutomationException
Normalization field.

Remarks

Similar to the ClassBreaksRenderer, the ProportionalSymbolRenderer you can specify a normalization field through the NormField property. This is exactly the same as setting the field via IDataNormalization::NormalizationField property. Data is normalized prior to caculating symbol sizes.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The field
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setNormField

void setNormField(String field)
                  throws IOException,
                         AutomationException
Normalization field.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
field - The field (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMaxDataValue

void setMaxDataValue(double rhs1)
                     throws IOException,
                            AutomationException
Normalized maximum data value.

Description

This property represents the largest possible value in the data. This property does not at all affect the map symbolization, but is only used to help determine the structure of the renderers entry in the table of contents and legend if applicable.

This property is only used if ValueUnit = esriUnknownUnits. In this case the set of symbols to be shown in the renderer legend entry is determined based on the values of these properties: MinSymbol/MinDataValue, MaxDataValue, and LegendSymbolCount which is the desired number of symbols to be shown in the legend entry. Be sure to set these properties before calling CreateLegendSymbol, which refreshes the renderer's legend entry.

If ValueUnit is some known data unit, then only the MinSymbol is shown in the legend and MaxDataValue is not used.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
rhs1 - The rhs1 (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMinDataValue

void setMinDataValue(double rhs1)
                     throws IOException,
                            AutomationException
Normalized minimum data value.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
rhs1 - The rhs1 (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMinSymbol

ISymbol getMinSymbol()
                     throws IOException,
                            AutomationException
Symbol used to draw feature with the normalized minimum data value.

Description

This is the symbol used to display the data. This can be a marker or line symbol.

Remarks

MinSymbol is the base symbol used by the proportional symbol renderer, and it can be a line or marker symbol. For each feature in the data, MinSymbol is resized and used to represent the data value in Field. The rules for resizing of MinSymbol are controlled by the settings for ValueUnit and ValueRepresentation.

Marker symbols can be used with both point and polygon data. In the polygon data case, markers are drawn at the center of each feature. BackgroundSymbol provides access to the fill symbol used to draw the actual shape of the underlying polygon features.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.display.ISymbol
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMinSymbol

void setMinSymbol(ISymbol sym)
                  throws IOException,
                         AutomationException
Symbol used to draw feature with the normalized minimum data value.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
sym - A reference to a com.esri.arcgis.display.ISymbol (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getValueUnit

int getValueUnit()
                 throws IOException,
                        AutomationException
Units of the value field.

Description

This property specifies the real world distance units that the data in Field represent.

Remarks

Known Units

If the data in Field represent an actual distance in the real world, and you know the units for the data, then you should set ValueUnit to these units. For example, for your tree point data you might have measured the radius of each tree canopy in meters and have this stored in the field "Canopy". In this scenario you should set ValueUnit = esriMeters and also set ValueRepresentation = esriValueRepRadius. See ValueRepresentation for more information about how symbols are scaled to data values. Also, in this case you do not need to set MinDataValue.

Unknown Units

If the data in Field does not represent an actual distance in the real world, then you should set ValueUnit = esriUnknownUnits. In this case you need to set MinDataValue to the data value corresponding to the size of the symbol set for MinSymbol.

In the marker symbol case, a feature with value that is twice the MinDataValue will have a symbol with an area twice as big as the MinSymbol. An assumption is made that the marker symbol is square for this calculation. Also, for marker symbols with unknown units, an appearance compensation factor can be applied by setting FlanneryCompensation = True. Empirical testing has shown that people tend to underestimate differences in area when visually comparing two marker symbols. Therefore, this factor increases the difference in area between a smaller symbol and a a larger symbol as the symbols get larger.

In the line symbol case, a feature with value that is twice the MinDataValue will have a width that is twice as wide as the MinSymbol.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.system.esriUnits constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setValueUnit

void setValueUnit(int unit)
                  throws IOException,
                         AutomationException
Units of the value field.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
unit - A com.esri.arcgis.system.esriUnits constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getValueRepresentation

int getValueRepresentation()
                           throws IOException,
                                  AutomationException
Representation type of the value field.

Remarks

ValueRepresentation together with ValueUnit specifies how data values are mapped to symbol sizes by the renderer. However, the way that ValueRepresentation affects this mapping is the same regardless of the ValueUnit:

Marker symbols can be proportional by radius or area. Note that marker symbols should be circular or square for these settings to correctly apply.

Line symbols can be proportional by width or distance from the center line (one half the width).

If ValueUnit = esriUnknownUnits, then marker symbols are proportional by area and line symbols are proportional by width.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.carto.esriValueRepresentations constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setValueRepresentation

void setValueRepresentation(int rep)
                            throws IOException,
                                   AutomationException
Representation type of the value field.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
rep - A com.esri.arcgis.carto.esriValueRepresentations constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isFlanneryCompensation

boolean isFlanneryCompensation()
                               throws IOException,
                                      AutomationException
Indicates if Flannery Compensation is applied.

Remarks

This property is only used if ValueUnit is some known set of units and MinSymbol is a marker symbol.

This property is a flag that indicates whether or not a Flannery compensation factor is applied to the marker symbol sizes calculated by the renderer. By setting this property to True you are enabling the application of this compensation factor.

Empirical testing has shown that people tend to underestimate differences in area when visually comparing two marker symbols. Therefore, the Flannery compensation factor increases the difference in area between a smaller symbol and a a larger symbol as the symbols get larger. It is generally accepted that this factor should be applied when sizing marker symbols proportionally or in a graduated fashion.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The flag
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setFlanneryCompensation

void setFlanneryCompensation(boolean flag)
                             throws IOException,
                                    AutomationException
Indicates if Flannery Compensation is applied.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
flag - The flag (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getLegendSymbolCount

int getLegendSymbolCount()
                         throws IOException,
                                AutomationException
Number of symbols displayed in the TOC and legend.

Remarks

The ProportionalSymbolRenderer does not use a fixed set of symbols, and so the legend information for the renderer must be refreshed by calling CreateLegendSymbols after changes are made to renderer properties.

This property represents the number of desired symbol sizes to be shown in the legend entry for the renderer. The property is onl used if ValueUnit = esriUnknownUnits. In this case the set of symbols to be shown in the table of contents, and legend if applicable is determined based on the values of these properties: MinSymbol/MinDataValue, MaxDataValue which is the largest possible value in the data, and LegendSymbolCount. Be sure to set these properties before calling CreateLegendSymbol.

If ValueUnit is some known data unit, then only the MinSymbol is shown in the legend and LegendSymbolCount is not used.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The num
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setLegendSymbolCount

void setLegendSymbolCount(int num)
                          throws IOException,
                                 AutomationException
Number of symbols displayed in the TOC and legend.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
num - The num (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getBackgroundSymbol

IFillSymbol getBackgroundSymbol()
                                throws IOException,
                                       AutomationException
Background fill symbol used when proportional marker symbols are draw on polygon features.

Description

This is the fill symbol used to draw the actual shape of polygon features when the renderer is applied to a polygon feature layer. In this situation, the MinSymbol is a marker symbol and is drawn at the center of each poylgon feature.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.display.IFillSymbol
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setBackgroundSymbol

void setBackgroundSymbol(IFillSymbol sym)
                         throws IOException,
                                AutomationException
Background fill symbol used when proportional marker symbols are draw on polygon features.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
sym - A reference to a com.esri.arcgis.display.IFillSymbol (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

createLegendSymbols

void createLegendSymbols()
                         throws IOException,
                                AutomationException
Creates the legend. Call after all properties have been set.

Remarks

The ProportionalSymbolRenderer does not use a fixed set of symbols, and so the legend information for the renderer must be refreshed by calling this method after changes are made to renderer properties.

If ValueUnit = esriUnknownUnits then a set number of symbols will be shown in the table of contents, and legend if applicable. This set will be determined based on several properties: MinSymbol/MinDataValue, MaxDataValue which is the largest possible value in the data, and LegendSymbolCount which is the number of symbols desired in the renderer's legend entry. Be sure to set these properties before calling CreateLegendSymbol.

If ValueUnit is some known data unit, then only the MinSymbol is shown in the legend.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.