|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface IProportionalSymbolRenderer
Provides access to members that control the drawing of varying size symbols for each feature, each sized in proportion to a field value.
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.
| 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 |
|---|
String getField()
throws IOException,
AutomationException
The name of the numeric field used to determine the size of the symbol drawn for each feature on the map.
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setField(String field)
throws IOException,
AutomationException
field - The field (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
String getNormField()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setNormField(String field)
throws IOException,
AutomationException
field - The field (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setMaxDataValue(double rhs1)
throws IOException,
AutomationException
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.
rhs1 - The rhs1 (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setMinDataValue(double rhs1)
throws IOException,
AutomationException
rhs1 - The rhs1 (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
ISymbol getMinSymbol()
throws IOException,
AutomationException
This is the symbol used to display the data. This can be a marker or line symbol.
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setMinSymbol(ISymbol sym)
throws IOException,
AutomationException
sym - A reference to a com.esri.arcgis.display.ISymbol (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
int getValueUnit()
throws IOException,
AutomationException
This property specifies the real world distance units that the data in Field represent.
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setValueUnit(int unit)
throws IOException,
AutomationException
unit - A com.esri.arcgis.system.esriUnits constant (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
int getValueRepresentation()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setValueRepresentation(int rep)
throws IOException,
AutomationException
rep - A com.esri.arcgis.carto.esriValueRepresentations constant (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
boolean isFlanneryCompensation()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setFlanneryCompensation(boolean flag)
throws IOException,
AutomationException
flag - The flag (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
int getLegendSymbolCount()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setLegendSymbolCount(int num)
throws IOException,
AutomationException
num - The num (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IFillSymbol getBackgroundSymbol()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setBackgroundSymbol(IFillSymbol sym)
throws IOException,
AutomationException
sym - A reference to a com.esri.arcgis.display.IFillSymbol (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void createLegendSymbols()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||