【ArcGIS Runtime SDK for Android-08】Geometries

几何图形通过在特定地理位置定义形状（shape）来表示现实世界中的对象。它们在整个API中用于表示要素（features）和图形（graphics）的形状、图层范围、视点（viewpoints）和GPS位置。它们还可作为空间分析和地理处理操作的输入和输出，以及测量距离和面积等用途。

Geometry类提供了所有类型的几何体所共有的功能。 Point, Multipoint, Polyline, Polygon和Envelope都继承了Geometry，并表示不同类型的形状。

以下是常见的几何特征:

• Geometries have a spatial reference indicating the coordinate system used by its coordinates.
• Geometries can be empty, indicating that they have no specific location or shape.
• Geometries can have z-values and/or m-values.
• Geometries can be converted to and from JSON to be persisted or to be exchanged directly with REST services.

1、几何图形是不可变的

大多数几何图形都是创建的，并且在其生命周期中不会更改，包括创建用于存储在地理数据库中或从不可编辑（non-editable）图层读取的要素，以及从空间查询、地理编码操作、网络追踪或地理处理任务等任务返回的要素。不可变的几何图形( immutable geometries)为您的应用程序提供了一些重要的好处。它们本质上是线程安全（thread-safe）的，有助于防止意外更改，并且允许某些性能优化。

虽然不可变的几何图形似乎会为编辑现有的几何图形带来问题，但这些问题可以通过使用几何构造器（geometry builders）来解决。几何构造器被设计成在允许修改的同时表示正在构建的几何的状态，从而支持编辑工作流。

2、Envelope

包络几何图形（Envelope geometries）表示具有与坐标系的x或y轴平行的边的矩形。最常见的是，它们表示图层或其他几何图形的空间范围，或为任务（tasks）定义感兴趣的区域。它们可以用作图形（graphics）的几何形状和许多几何操作，尽管它们不能用作要素（features）的几何形状。

Envelope 的新实例通过指定最小和最大x坐标、最小和最大y坐标以及空间参考来定义。可以选择指定最小和最大z值来定义Envelope 的深度。

// create an Envelope using minimum and maximum x,y coordinates and a SpatialReference
Envelope envelope = new Envelope(-123.0, 33.5, -101.0, 48.0, SpatialReferences.getWgs84());

定义Envelope的另一种方法是使用两点。最小和最大的x,y坐标是从这两个点计算出来的。

// minimum and maximum x and y will be calculated from points passed
Envelope envelopePoints = new Envelope(pointOne, pointTwo);

3、Point

点几何图形表示单个点、放置（place）或位置（location），如社区中的地理编码的家庭地址或水表在水务网络中的位置。较大的地理实体，如城市，可以用小比例尺地图上的点来表示。点可以用作要素（features）和图形（graphics）的几何形状，通常用于帮助构造其他几何形状。它们也用于视点（Viewpoints）。

点存储一组单独的x、y坐标，它们表示位置的坐标(例如经度和纬度)和一个空间参考。还可以选择包含z值(例如表示海拔等)。Point的实例可以使用构造函数创建，构造函数在单个调用中定义完整的几何图形。

// create a Point using x,y coordinates and a SpatialReference
Point pt = new Point(34.056295, -117.195800, SpatialReferences.getWgs84());

// create a Point with a z-value as well
Point ptWgs84 = new Point(34.056295, -117.195800, 414, SpatialReferences.getWgs84());
Log.i(TAG, String.format("Point hasZs: %B", ptWgs84.hasZ())); // hasZ=TRUE

提示：

在处理具有地理空间参考的点实例时，x坐标是经度(东或西)，y坐标是纬度(北或南)。当地理坐标用字符串表示时，通常使用“(纬度、经度)”形式编写，其中y坐标在x坐标之前。赤道以南的纬度值和本初子午线以西的经度值用负数表示。

您可以使用CoordinateFormatter将纬度、经度格式的字符串直接转换为点，还可以从现有点返回纬度、经度格式的字符串。还支持其他坐标符号，如军事网格参考系统(MGRS)和美国国家网格(USNG)。

4、Multipoint

Multipoint几何图形表示点的有序集合。它们可以用作要素和图形的几何形状，也可以用作几何操作的输入或输出。对于由大量共享相同属性值集的点组成的要素，与使用多个点要素（features）相比，Multipoint要素在地理数据库中存储和分析可能更有效。激光雷达（LIDAR）是一个可以使用Multipoint数据的例子。

Multipoint由一个只读的点集合组成。您可以通过调用构造函数并传入一组可迭代的点来创建一个新的Multipoint。

// create a Multipoint from a PointCollection
PointCollection stateCapitalsPST = new PointCollection(SpatialReferences.getWgs84());
stateCapitalsPST.add(-121.491014, 38.579065); // Sacramento, CA
stateCapitalsPST.add(-122.891366, 47.039231); // Olympia, WA
stateCapitalsPST.add(-123.043814, 44.93326); // Salem, OR
stateCapitalsPST.add(-119.766999, 39.164885); // Carson City, NV
Multipoint multipoint = new Multipoint(stateCapitalsPST);

要访问现有Multipoint中的每个点，请遍历getPoints返回的ImmutablePointCollection。

// iterate the Points in the ImmutablePointCollection from a Multipoint
for (Point pt : multipoint.getPoints()) {
  Log.i(TAG, String.format("Point x=%f,y=%f, z=%f",  pt.getX(), pt.getY(), pt.getZ()));
}

使用MultipointBuilder一次构建一个多点，或者修改现有的Multipoint。

5、Polyline

Polyline（折线）几何图形表示线性要素的形状和位置，例如，公路网中的街道或炼油厂中的管道。它们可以用作要素和图形的几何形状，也可以用作任务或地理处理操作的输入或输出，如网络追踪的输出。

Polyline是由一系列连接的线段（segments）组成的，每个线段（segments）在起点和终点之间定义一条连续的线（line）。您还可以使用基于点的辅助方法来处理Polyline。

例如，使用构造函数从点集合创建新的折线。这将创建一系列连接指定点的直线。

// create a Polyline from a PointCollection
PointCollection borderCAtoNV = new PointCollection(SpatialReferences.getWgs84());
borderCAtoNV.add(-119.992, 41.989);
borderCAtoNV.add(-119.994, 38.994);
borderCAtoNV.add(-114.620, 35.0);
Polyline polyline = new Polyline(borderCAtoNV);

Polyline可以有多个部分（multiple parts）。每个部分（part）都是一系列连接的段（segments），但是这些部分（parts）可以彼此分离。例如，在折线中表示有未完成部分的不连续高速公路。部分（parts）也可以相交于一个或多个顶点，例如，在表示河流及其支流的折线中。Polyline类继承自Multipart, Multipart提供了用于遍历折线中每个部分（part）的段（segments）和点的成员。

若要一次构建一个折线点，或修改现有折线，请使用PolylineBuilder。

6、Polygon

Polygon（多边形）几何图形表示区域的形状和位置，例如国家或湖泊。它们可以用作要素和图形的几何形状，或者用作任务或地理处理操作的输入或输出，例如驱动时间（drive-time ）分析或缓冲区操作的输出。

多边形与折线相似，它们也由一系列相连的段（segments）组成。然而，多边形定义了封闭区域，因此最后一段（segments）的端点始终与第一个段的起点在同一位置，形成了封闭边界。与折线一样，您可以使用基于点的辅助方法来处理多边形段（segments）的顶点（vertices）。

例如，使用构造函数从现有的PointCollection创建一个新的多边形，创建一系列连接这些点的线（LineSegments）。

// create a Polygon from a PointCollection
PointCollection coloradoCorners = new PointCollection(SpatialReferences.getWgs84());
coloradoCorners.add(-109.048, 40.998);
coloradoCorners.add(-102.047, 40.998);
coloradoCorners.add(-102.037, 36.989);
coloradoCorners.add(-109.048, 36.998);
Polygon polygon = new Polygon(coloradoCorners);

多边形与折线相似，可以有多个部分（multiple parts ），但与多部分折线（ multipart polylines）的规则不同。多部分多边形的每个部分（part）都是由一系列连接的部分（segments）组成的闭合环。各部分（part）不得与任何其他部分交叉，但可以完全位于另一部分的内部或外部。例如，一个代表夏威夷州的多边形将由八个互不相连的部分组成，每个部分代表一个岛屿。一个完全包围莱索托飞地的南非国家的多边形将包括两个部分，一个包含在另一个之中。Polygon类也继承自Multipart。

7、Multipart (Polygon and Polyline)

多边形和折线继承自Multipart, Multipart又继承自Geometry。Multipart提供了对几何图形的ImmutablePartCollection的访问。集合中的每个ImmutablePart都是段（Segment）对象的集合。您可以遍历每个部分（part）中的段（segments）或点。

// iterate each Part of a Polyline
ImmutablePartCollection parts = polyline.getParts();
for  (ImmutablePart part : parts)
{
  // iterate the collection of Points representing vertices of the ImmutablePart
  for (Point pt : part.getPoints())
  {
    Log.i(TAG, String.format("Point: x=%f,y=%f, z=%f", pt.getX(), pt.getY(), pt.getZ()));
  }
  // iterate each Segment - ImmutablePart is a collection of segments
  for (Segment seg : part) {
    Log.i(TAG, String.format("Segment: (%f, %f) to (%f %f)",
        seg.getStartPoint().getX(), seg.getStartPoint().getY(),
        seg.getEndPoint().getX(), seg.getEndPoint().getY()));
  }
}

一种基于点的简便方法可以在一个步骤中遍历表示所有部分（parts）顶点（vertices）的点。

// get the combined set of Points from every ImmutablePart of a Polyline
for  (Point pt : polyline.getParts().getPartsAsPoints())
{
  Log.i(TAG, String.format("Point: x=%f,y=%f, z=%f",
      pt.getX(), pt.getY(), pt.getZ()));
}

就像多边形和折线是不可变的一样，Multipart返回的集合也是不可变的——ImmutablePartCollection, ImmutablePart和ImmutablePointCollection.。然而，在创建多边形和折线时，您使用可变的等价——PartCollection, Part, and PointCollection。基于点的辅助方法在可变类和不可变类上都可用。

8、Segments

Segments（段）描述开始位置和结束位置之间的连续线（line）。多部分几何中的每个部分（part）都是段的集合，其中一个段的结束与下一个段的开始位于完全相同的位置。ArcGIS系统同时支持直线段和曲线段，但是在当前版本中，ArcGIS Runtime SDK只支持直线段。Multipart几何图形可以组成和分解成段，如果需要;在完全支持真实曲线之前，使用基于点的方法提供了相同的功能。

因为一个位置是由相邻的段共享的，所以在遍历部分（part）中的点时，使用一个单点（single Point）对象来表示共享位置。因此，当迭代折线部分中的点时，同一部分中的点比段数多一个。

// iterate each Part of a Polyline
for  (ImmutablePart part : polyline.getParts())
{
  // find the number of Points representing vertices of the ImmutablePart
  Log.i(TAG, String.format("Number of Points: %d", part.getPointCount()));

  // find the number of Segments - ImmutablePart is a collection of segments
  Log.i(TAG, String.format("Number of Segments: %d", part.size()));

}

与它们组成的几何图形类似，段是不可变的。

9、Other aspects of geometries

（1）Spatial references

几何中坐标的意义是由几何的空间参考决定的。顶点（vertices）和空间参考允许你的应用程序将现实世界中的对象从它在地球上的位置转换到地图上的位置。

在某些情况下，可能不设置几何图形的空间参考。没有空间参考的图形（graphics）使用与绘制它们的MapView相同的空间参考绘制。当使用几何构建器（geometry builder）从点几何创建折线或多边形几何时，在将每个点添加到构建器之前，不需要设置每个点的空间参考，因为将为其添加到的构建器分配空间参考。在大多数其他情况下，例如在几何操作中使用几何图形或编辑要素表时，必须设置几何图形的空间参考。

（2）Linear, angular, and area units

在整个Runtime中可以使用不同类型的度量单位。投影坐标系使用线性测量（ linear measurements）来定义坐标，例如使用线性单位表示的米或英里（miles）。线性单位还用于返回距离测量值，例如由GeometryEngine的一些方法返回。地理坐标系统使用角度测量（angular measurements）来定义坐标，例如使用角度单位表示的度或弧度。计算面积大小的方法使用面积单位，例如以英亩（acres）或平方公里为单位。可以使用最常用的度量单位的枚举（ enumerations ）来定义线性、角度和面积单位。它们也可以由已知的ID (WKID)或已知的文本(WKT)定义，这些都列在坐标系统和转换中。

（3）Projection, topological, and other operations

改变几何图形的坐标，使其具有相同的形状和位置，并使用不同的空间参考来表示，这称为“投影”，有时也称为“重投影”。因为几何图形是不可变的，它们没有任何成员方法来投影、转换或以其他方式修改它们的内容。

GeometryEngine类提供了广泛的方法来读取几何图形的内容并修改该内容以创建新的几何图形。有投影、旋转、移动、剪切（cut）、变密（densify）和简化（generalize）几何图形的方法。当使用屏幕上的位置创建几何图形时，并且地图是一个环绕地图，在将其保存到geodatabase或在任务或其他操作中使用它之前，您可能还需要考虑对几何图形进行规范化（normalizing）。

（4）Converting to and from JSON

几何图形可以序列化，也可以从JSON序列化和反序列化。ArcGIS REST API文档描述了几何对象的JSON表示。您可以使用这种编码和解码机制与REST Web服务交换几何图形，或者将它们存储在文本文件中。

// convert a Polygon to a JSON representation
String polygonJson = polygon.toJson();
// create a new Polygon from JSON
Polygon polygonFromJson = (Polygon) Polygon.fromJson(polygonJson);

Converting to or from JSON can add points to multipart geometries if the geometry has insufficient points to construct a segment.

（5）Z-values and 3D

几何图形可以有z值，表示沿z轴的值，z轴与x轴和y轴正交。z值可以表示地表面以上的高度或地表面以下的深度，或绝对高程。例如，z值用于在SceneViews中绘制几何图形的位置。注意，几何图形并不是真正的3D形状，它们被覆盖在视图的表面上，或者在某些情况下，使用z值绘制在单个平面上。z值存储在Points和Envelopes上。因此，由于Multipoints, Polylines和 Polygons是由Points创建的，所以所有类型的几何图形都可以有z值。

几何图形是否具有z值是在创建几何图形时确定的;如果使用具有z值参数的方法，则新几何图形将具有z值(几何图形的hasZ为真)。如果您使用接受z值参数的构造函数创建几何图形，或者如果您传递给具有z值的构造函数点或段（segments），那么新的几何图形将具有z值。具有z值的几何图形有时称为z-aware几何图形。

可能不是所有的顶点都定义了z值。NaN是一个有效的z值，用于表示未知的z值。但是，默认z值是0。需要注意的是，当您从没有z值的几何图形中获得z值时，将返回默认值0。检查hasZ属性以确定z值为0是否意味着几何图形中没有z值，或者几何坐标中的z值是否为0。

有关编辑与z值相关的工作流的更多信息，请参见编辑几何图形。

（6）M-values

M值用于线性参考场景（linear referencing scenarios），和z值一样，每个几何图形都可以选择性地存储m值。默认的m值是NaN。如果在创建几何图形时将m值指定为参数，则新几何图形将具有m值(几何图形的hasM为true)。注意，当从几何图形中返回m值时，对于没有m值的顶点，将返回NaN的默认值(与z值的默认值不同)。具有m值的几何图形有时称为m-aware几何图形。有关编辑工作流和m值的更多信息，请参见编辑几何图形。

参考链接：

https://developers.arcgis.com/android/latest/guide/geometries.htm