【ArcGIS Runtime SDK for Android-06】Symbols, styles, and renderers

符号定义图形或要素的外观的所有非地理方面，包括颜色（color）、大小（ size,）、边框（border）和透明度（transparency）。在创建单个图形（graphics）时，可以直接将符号应用于它们。您还可以使用符号为图形覆盖（graphics overlays ）或要素图层（ feature layers）创建渲染器（renderer）。

有了渲染器，你可以：

• Use one symbol for all features in a layer (or all graphics in an overlay), regardless of attribute values
• Symbolize features in a layer (or graphics in an overlay) differently based on one or more of their attribute values

在要素上设置符号的唯一方法是使用渲染器。一些图层类型不支持符号和渲染器，例如：WMS。基于这种情况，可以选择使用样式（styles），样式为内容的呈现方式提供了选项。

1、符号（Symbols）

每个符号类型都可以用来表示特定的几何类型。无论是将符号直接应用到图形上，还是使用符号创建渲染器，都要确保被符号化的图形或要素的几何类型与你想要使用的符号兼容。

ArcGIS Runtime根据数据源和访问数据源的方式而使用两种不同的符号模型（symbol models）。

• The simple symbol classes follow the web map specification. You access these symbols through the simple symbology API, or get these symbols from web maps and feature services when advanced symbology is turned off.
• Advanced symbols, accessed through multilayer symbol classes, follow the ArcGIS Pro symbol model. These symbols come from feature services, mobile style files, the dictionary renderer, and mobile map packages.

（1）Simple (web) symbols

以下是API中兼容几何类型的符号列表和简要说明:

根据您想要符号化的几何类型，有不同的选择来定义符号。点、线和面都有一个可以使用的基本符号:SimpleMarkerSymbol、SimpleLineSymbol和SimpleFillSymbol；此外，还可以使用一个PictureMarkerSymbol来对点数据进行符号化。

所有的标记符号（marker symbols）都提供了设置旋转符号角度的能力。这可能对显示方向（direction）之类的东西有用(例如，对于风的测量或移动的车辆)。此外，标记符号具有一个角度对齐属性，该属性指定在地图旋转时标记符号是保持屏幕对齐（screen-aligned）还是地图对齐（map-aligned）。所有标记符号的默认值都是屏幕对齐的，这意味着标记不会随地图旋转。将角度对齐属性设置为地图对齐，符号将随地图旋转。当符号的角度表示地图上的方向时，这一点非常重要。您还可以定义x或y偏移量，这意味着符号与它所表示的要素的位置之间存在指定的距离。这在处理文本（text）时尤其有用。

简单的符号类型(SimpleMarkerSymbol、SimpleLineSymbol和SimpleFillSymbol)使您能够通过选择样式(例如：多边形的实线或交叉阴影填充;折线的实线或虚线;为点设置方形或圆形标记)，设置颜色，并为标记定义大小或为线设置宽度。对于标记和填充，还可以定义轮廓符号(使用行符号)。

（2）Picture symbols

图像符号（Picture symbols），例如PictureMarkerSymbol，允许您使用图像来符号化某个要素。图像可以存储在本地，也可以来自在线源。图像的大小可以在平台设备独立单元中指定，方法与其他应用程序资源相同。

可以从磁盘上的图像(如JPEG文件)创建图像标记符号，也可以根据远程服务器上的图像的URL来创建。每个应用程序下载一次远程图像并缓存以备将来使用;因此，它们是可加载的资源。

有不同的方式来创建图像标记符号，例如：

• 使用本地文件系统上的图像来创建图像标记符号；

//Create a picture marker symbol from a file on disk
BitmapDrawable pinBlankOrangeDrawable = (BitmapDrawable) Drawable.createFromPath(mPinBlankOrangeFilePath);
final PictureMarkerSymbol pinBlankOrangeSymbol = new PictureMarkerSymbol(pinBlankOrangeDrawable);
//Optionally set the size, if not set the image will be auto sized based on its size in pixels,
//its appearance would then differ across devices with different resolutions.
pinBlankOrangeSymbol.setHeight(20);
pinBlankOrangeSymbol.setWidth(20);
//Optionally set the offset, to align the base of the symbol aligns with the point geometry
pinBlankOrangeSymbol.setOffsetY(10); //The image used has not buffer and therefore the Y offset is height/2
pinBlankOrangeSymbol.loadAsync();

• 使用图像的URL来创建图像标记符号；

//Create a picture marker symbol from a URL resource
//When using a URL, you need to call load to fetch the remote resource
final PictureMarkerSymbol campsiteSymbol = new PictureMarkerSymbol(
  "http://sampleserver6.arcgisonline.com/arcgis/rest/services/Recreation/FeatureServer/0/images/e82f744ebb069bb35b234b3fea46deae");
//Optionally set the size, if not set the image will be auto sized based on its size in pixels,
//its appearance would then differ across devices with different resolutions.
campsiteSymbol.setHeight(18);
campsiteSymbol.setWidth(18);
campsiteSymbol.loadAsync();

• 使用Android Drawable中的资源来创建图像标记符号；

//Create a picture marker symbol from an app resource
BitmapDrawable pinStarBlueDrawable = (BitmapDrawable) ContextCompat.getDrawable(this, R.drawable.pin_star_blue);
final PictureMarkerSymbol pinStarBlueSymbol = new PictureMarkerSymbol(pinStarBlueDrawable);
//Optionally set the size, if not set the image will be auto sized based on its size in pixels,
//its appearance would then differ across devices with different resolutions.
pinStarBlueSymbol.setHeight(40);
pinStarBlueSymbol.setWidth(40);
//Optionally set the offset, to align the base of the symbol aligns with the point geometry
pinStarBlueSymbol.setOffsetY(
    11); //The image used for the symbol has a transparent buffer around it, so the offset is not simply height/2
pinStarBlueSymbol.loadAsync();

（3）Multilayer (advanced) symbols

Multilayer symbols是基于ArcGIS Pro符号模型的一个子集。这些符号有多个图层，可以在每一层中包含不同的符号类型，具有可定义的行为，以获得高级的制图效果。可以使用ArcGIS Pro创建这些复杂的符号类型，并使用Use Advanced Symbology属性(默认设置为true)通过要素服务共享它们。Multilayer symbols还用于移动地图包、移动样式文件和字典渲染器中（dictionary renderer）。

MultilayerSymbol基类允许您获取和设置符号的颜色。颜色值如何返回或应用取决于符号如何编写。

MultilayerPointSymbol类允许您更改符号的角度和角度对齐方式。设置角度将影响所有的符号图层，但最终的旋转将取决于符号是如何编写的。角对齐属性的默认值还取决于符号是如何编写的，但可以更改。

MultilayerPointSymbol类具有size属性，MultilayerLineSymbol具有width属性。改变这些将按比例影响符号的所有图层。

（4）Applying a symbol to a graphic

图形是内存中的要素，提供了在地图上显示几何图形的基本方法。图形的独特之处在于可以使用包含它们的覆盖图层的渲染器进行符号表示，或者直接将符号应用于图形。对于如何使用图形的描述，可以参考Add graphics and text to graphics overlays.

下面的例子展示了如何创建一个点图形，应用一个符号，然后在地图上显示它。

//create a simple marker symbol
SimpleMarkerSymbol symbol = new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.CIRCLE, Color.RED, 12); //size 12, style of circle

//add a new graphic with a new point geometry
Point graphicPoint = new Point(-226773, 6550477, SpatialReferences.getWebMercator());
Graphic graphic = new Graphic(graphicPoint, symbol);
graphicsOverlay.getGraphics().add(graphic);

（5）Working with simple and multilayer symbols

简单符号是网络地图的符号。当在ArcGIS Pro中将地图编辑为web地图时，重要的是要注意您的符号将被转换为简单的符号。一般情况下，将点符号转换为针对web优化的图像标记符号，在尽可能接近地表示原始符号的情况下，对线和多边形符号进行简化。

如果你的应用程序主要与web地图交互工作，同时希望在整个平台上符号风格看起来相同，那么你的应用程序应该使用simple symbols API。如果使用多层符号（multilayer symbols）并试图将地图保存为web地图，则保存将失败，强制保存将删除符号。

如果你的地图只与ArcGIS Runtime和ArcGIS Pro一起使用，那么您可以使用多层符号。在这些环境中，多层(高级)符号是矢量化（vectorized ）的，因此在具有高分辨率屏幕的设备上可以更好地扩展。

2、渲染器（Renderers）

顾名思义，渲染器是一个对象，它决定图层中的要素或图形如何被渲染显示。然后渲染器使用符号来绘制它们。渲染器包含的逻辑是将适当的符号应用于图层中的每个要素或叠加中的每个图形。ArcGIS Runtime中有多种渲染器类型，每种类型都设计为使用不同的渲染逻辑。大多数渲染器使用属性值来决定应该应用哪个符号。

在典型的工作流中，渲染器用于符号化要素图层中的要素，其中的要素都是相同的几何类型。由您来创建一个带有可应用于图层的几何类型的符号的渲染器。渲染器也可以应用于图形叠加，但不应该用于具有混合几何类型图形的叠加。对于这样的场景，在创建每个图形时应用符号是首选的工作流。

（1）Simple renderer

一个简单的渲染器对一个图层中的所有要素(或覆盖层中的所有图形)使用一个符号，而不考虑属性值。下面的代码片段展示了如何创建一个简单的渲染器的图形覆盖只包含点使用一个简单的标记符号:

//create a simple symbol for use in a simple renderer
SimpleMarkerSymbol symbol = new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.CROSS, Color.RED, 12); //size 12, style of cross
SimpleRenderer renderer = new SimpleRenderer(symbol);

//apply the renderer to the graphics overlay (so all graphics will use the same symbol from the renderer)
graphicOverlay.setRenderer(renderer);

（2）Unique value renderer

一个唯一值渲染器基于一个或多个属性值，以不同的方式表示图层(或覆盖层中的图形)中的要素。当基于属性对要素进行符号化时，它尤其有用。与图形不同，要素不具有符号属性，因此不能为其分配单独的符号。但是，您可以使用唯一值渲染器根据每个要素的属性值在图层上设置符号。(你也可以对图形这样操作)

提示：

ArcGIS map services allow up to three fields to be used for unique value renderers. An ArcGIS feature service allows only one. As a developer, you can specify as many fields as you like, ensuring that the order of the fields you specify corresponds to the order of the values you specify.

When applying a renderer that uses attribute values on a feature layer which is bound to a service feature table, you must ensure the required fields are specified in the tables outfields. When instantiating a service feature table in code, by default only the minimum set of fields required to render the features are requested (object id, geometry and renderer fields). When loading service feature tables from a map, by default all fields are requested. Be sure to override these defaults by setting the outfields before the table is loaded.

例如：

// Create service feature table
ServiceFeatureTable serviceFeatureTable = new ServiceFeatureTable(getResources().getString(R.string.sample_service_url));

// Create the feature layer using the service feature table
FeatureLayer featureLayer = new FeatureLayer(serviceFeatureTable);

// Override the renderer of the feature layer with a new unique value renderer
UniqueValueRenderer uniqueValueRenderer = new UniqueValueRenderer();
// Set the field to use for the unique values
uniqueValueRenderer.getFieldNames().add("STATE_ABBR"); //You can add multiple fields to be used for the renderer in the form of a list, in this case we are only adding a single field

// Create the symbols to be used in the renderer
SimpleFillSymbol defaultFillSymbol = new SimpleFillSymbol(SimpleFillSymbol.Style.NULL, Color.BLACK, new SimpleLineSymbol(SimpleLineSymbol.Style.SOLID, Color.GRAY, 2));
SimpleFillSymbol californiaFillSymbol = new SimpleFillSymbol(SimpleFillSymbol.Style.SOLID, Color.RED, new SimpleLineSymbol(SimpleLineSymbol.Style.SOLID, Color.RED, 2));
SimpleFillSymbol arizonaFillSymbol = new SimpleFillSymbol(SimpleFillSymbol.Style.SOLID, Color.GREEN, new SimpleLineSymbol(SimpleLineSymbol.Style.SOLID, Color.GREEN, 2));
SimpleFillSymbol nevadaFillSymbol = new SimpleFillSymbol(SimpleFillSymbol.Style.SOLID,Color.BLUE, new SimpleLineSymbol(SimpleLineSymbol.Style.SOLID, Color.BLUE, 2));

// Set default symbol
uniqueValueRenderer.setDefaultSymbol(defaultFillSymbol);
uniqueValueRenderer.setDefaultLabel("Other");

// Set value for california
List<Object> californiaValue = new ArrayList<>();
// You add values associated with fields set on the unique value renderer.
// If there are multiple values, they should be set in the same order as the fields are set
californiaValue.add("CA");
uniqueValueRenderer.getUniqueValues().add(new UniqueValueRenderer.UniqueValue("California", "State of California", californiaFillSymbol, californiaValue));

// Set value for arizona
List<Object> arizonaValue = new ArrayList<>();
// You add values associated with fields set on the unique value renderer.
// If there are multiple values, they should be set in the same order as the fields are set
arizonaValue.add("AZ");
uniqueValueRenderer.getUniqueValues().add(new UniqueValueRenderer.UniqueValue("Arizona", "State of Arizona", arizonaFillSymbol, arizonaValue));

// Set value for nevada
List<Object> nevadaValue = new ArrayList<>();
// You add values associated with fields set on the unique value renderer.
// If there are multiple values, they should be set in the same order as the fields are set
nevadaValue.add("NV");
uniqueValueRenderer.getUniqueValues().add(new UniqueValueRenderer.UniqueValue("Nevada", "State of Nevada", nevadaFillSymbol, nevadaValue));

// Set the renderer on the feature layer
featureLayer.setRenderer(uniqueValueRenderer);

3、样式（Styles）

一些不支持符号和渲染器的图层提供了样式作为替代。

（1）ArcGIS vector tiled layer styles

An ArcGIS vector tile layer consumes vector tiles and an associated style for drawing them. Because the style is separate from the underlying data, you can easily customize the style of an existing basemap layer. There are layers in many styles available through ArcGIS Online.

You can create your own style with the online style editor. Your customized vector layers can then be saved to and read from ArcGIS Online.

（2）WMS styles

Styles are predefined options for how content is displayed. For example, WMS servers provide clients with a list of supported styles for each layer. At run time, you can choose which style the WMS server uses to render map images. In general, styles are predefined and cannot be changed or added to.

The styles property of the WmsLayerInfo class can be inspected to determine if there are styles available. The current style property of a WMS sublayer can be set to select a specific style.

// set the sublayer's current style
wmsLayer.getSublayers().get(0).setCurrentStyle(styles.get(0));

参考资料：

https://developers.arcgis.com/android/latest/guide/symbols-renderers-and-styles.htm