/********************************************************************************/
//Developing mobile applications with the Mobile SDK
//Working with geometry
//
/********************************************************************************/
The ArcGIS Mobile SDK includes a set of Geometry components that you can use to create and update the shape of features, perform spatial selections, and draw graphics on the map display. The geometry components are responsible for handling the shape of features stored in a map or a local mapca cache . Geometry types available in the Mobile SDK include Point, Multipoint, Polyline, Polygon and Envelope. This topic briefly（简短地；简略地） discusses how geometry is managed with the ArcGIS Mobile SDK and then illustrates how to use it with numerous examples.
ArcGIS Mobile SDK 包括一系列的Geometry组成部分，你可以使用它们创建和更新features(要素)的形状，执行空间选择，在展示的地图上面绘制图形。 Geometry部件负责处理存储在地图上的features的形状，或者本地mapca缓存。 Mobile SDK中可以获取的Geometry类型有point（点），multipoint(多点)，polyline（多边线）,以及polygon(多边形)和envelope。这个题目简单的讨论了Geometry和MobileSDK是如何管理的，然后在多个例子中介绍如何使用它们。
Maps, Spatial Reference, and Extents
The spatial reference, extent and the precision of the geometry that you create and manage in the Mobile SDK is stored in the schema（. 图解, 计划, 模式, 纲要） of the map cache and is determined by properties of the map document that you publish. A map document can contain one or more maps or data frames. When you publish a map document, you are actually publishing one of the maps in that document and need to choose which map you want to work with. By default, the active data frame or focus map is chosen.
地图、空间参考系、和范围
空间参考系、范围以及你在Mobile SDK中创建并更新的geometry的精度，这些都保存在Map缓存的图表中，并且它们都由你发布的地图文档的属性决定。一个地图我能当可以包含一个或者多个地图或者数据架构。 当你发布一个地图文档， 实际上是发布了文档中一个地图并且需要选择一个你想要使用的地图。默认情况下，选择有效的数据框架或者焦点地图。
A focus map contains the following information that is important to how you work with geometry in the Mobile SDK:
Spatial Reference - the map has a spatial reference than can differ from that of the layers' data source. When you create a map cache, the geometry is stored using the spatial reference of the map and just like ArcGIS Desktop, you create and work with geometry in the projection of the map.
Extent - the extent of the map itself determines how precise(.精确的，准确的；严谨的) you can store coordinates using the geometry components. It is important that you consider extent if you are building an editing application or if you need to display GPS locations with high accuracy.
焦点地图包含一下的信息，这些信息对于如何在Mobile SDK中使用Geometry是非常重要的。
控件参考系:地图有一个空间按参考系，她可以和图层的数据源的空间参考系不同。 当你创建一个地图缓存，geometry使用地图的空间参考储进行储存，就像ArcGIS Desktop一样，在地图的投影下，你创建和使用Geometry。
范围(extent):地图自身的范围决定了你使用geoemtry成分存坐标的精度。 当你正在创建一个编辑的应用程序或者你需要对GPS位置进行高精度的展示，那么对范围的考虑对你来说就非常重要了。
Coordinate Storage, Precision（n.精确(性)，精密(度)） and Calculating Extents
The ArcGIS Mobile SDK manages geometries in double-precision coordinates, but it stores geometry coordinates as integer units internally. The main reason is that windows mobile devices do not have math co-processors causing floating point arithmetic to be much slower than manipulating integers. As a result, precision（精度） might be degraded（降低身份，有辱人格；使降解） if the map used by the Mobile service has a very large extent and the data source has low precision. Given the resolution of your data you can calculate the maximum extent you can work with and maintain your accuracy requirements. When you choose a coordinate system, the default resolution is set to 1/10th of a millimeter (0.0001).
ArcGIS Mobile SDK 使用双精度坐标管理geometry，但是它以内在的整型数据存储geometry坐标。 主要的原因是：Windows Mobile设备没有含有数学处理器，导致浮点型运算对于整型运行来说非常的慢。 所有，如何mobile Service 使用的地图有一个非常大的范围并且数据源的精度较低，那么总的精度将会降低。建于你的资料的分辨率，你可以计算你可以使用的最大的范围并维持你当前的要求。当你选择了一个坐标系统，默认的结果方案是设置为0.0001。
To calculate the maximum height or width for the map extent in order to preserve（保护，维持；保存） resolution use the following equation（方程）:
Maximum Extent = 2,147,438,647 * resolution
So for example, if the data resolution is set to 0.001 meter (1 millimeter), the maximum height or width that you can set the map extent to and preserve millimeter accuracy is approximately 2,147 kilometers (2,147,438,647 * 0.001 = 2,147,438 meters).
为了计算地图范围的最大高度和最大宽度，以及为了维护resolution，使用下面的方程。
Maximum Extent = 2,147,438,647 * resolution
比如：如何数据的resolution设置为0.001米，你可以设置地图范围并且保持millimeter级精度的最大高度和宽度是：2,147 公里
Geometry architecture（结构）
A point geometry is zero-dimensional object that represents a real world location in a two dimensional plane. The following example will create a point at a particular lat, long coordinate.
一个点geometry 是一个零维的对象，它在一个二维的平面表示一个真实世界的位置。下面的例子将会一个特殊的经度、维度坐标创建一个point。
[C#]
///
/// Contains（包含、容纳、控制 ） a point geometry
///
private ESRI.ArcGIS.Mobile.Geometries.Point m_point;
private void button1_Click(object sender, EventArgs e)
{
CreatePoint();
}
private void CreatePoint()
{
// Creates a new instance（实例） of a Point using some lat/lon coordinates
// Latitud value
double lat = 34.058247;
// Longitud value
double lon = -117.198104;
// Converts a WGS84 coordinate to a Mobile coordinate
Coordinate coordinate = mobileService1.SpatialReference.FromWgs84(lon, lat);
m_point = new ESRI.ArcGIS.Mobile.Geometries.Point(coordinate);
// Redraws the client area
map1.Invalidate();
}
//重新绘制地图
private void map1_Paint(object sender, ESRI.ArcGIS.Mobile.MapPaintEventArgs e)
{
if (m_point == null || m_point.IsEmpty)
return;
// Draws the point geometry（几何(学)）
e.Display.DrawPoint(Pens.Blue, Brushes.LightBlue as SolidBrush, 50, m_point);
}
This code will create and draw a point in the Map as shown.
A multipoint geometry is an ordered collection of points, and it can be constructed as follows:
一个multipoint geometry 是一个有序的点的集合，她可以使用下面的方法构建
[C#]
///
/// Contains a multipoint geometry
///
private Multipoint m_mpoint;
private void button1_Click(object sender, EventArgs e)
{
CreateMultipoint();
}
private void CreateMultipoint()
{
// creates an instance of a multipoint
m_mpoint = new Multipoint();
// adds a coordinate
Coordinate coordinate = mobileService1.SpatialReference.FromWgs84(-117.198104, 34.058247);
m_mpoint.AddCoordinate(coordinate);
// adds another coordinate
coordinate = mobileService1.SpatialReference.FromWgs84(-117.198104, 34.057247);
m_mpoint.AddCoordinate(coordinate);
// redraw the client area
map1.Invalidate();
}
private void map1_Paint(object sender, ESRI.ArcGIS.Mobile.MapPaintEventArgs e)
{
if (m_mpoint == null || m_mpoint.IsEmpty)
return;
// Draws the multipoint geometry
e.Display.DrawMultipoint(Pens.Blue, Brushes.LightBlue as SolidBrush, 50, m_mpoint);
}
This code will create and draw a multipoint in the Map as shown.
A polygon is a collection of rings or parts that are ordered by their containment(容积) relationship. Each ring or part is a coordinate collection that has an orientation（方向，目标、趋向）: clockwise（顺时针） is a shell and counterclockwise（逆时针方向） is a hole. It requries a minimum of three (3) points in order to construct a valid（有效） polygon.
A polygon can be constructed as follows:
一个多边形是一个圆环或者部件的集合，并且它们根据他们容积关系进行排序。每一个圆环或者部件都是一个坐标集合，他们有一个趋向，顺时针方法是一个面，而逆时针方向是一个洞。为了构建一个有效的多边形它需要最少三个点。
以下方法可以创建一个多边形：
[C#]
///
/// Contains a coordinate collection captured（.俘虏，捕获；夺得，占领 n.俘获，捕获） when map mouse up
///
private CoordinateCollection m_coordinateCollection;
// contains a polygon geometry
private Polygon m_polygon;
private void map1_MouseUp(object sender, ESRI.ArcGIS.Mobile.MapMouseEventArgs e)
{
// If collection is null then creates a new instance
if (m_coordinateCollection == null)
m_coordinateCollection = new CoordinateCollection();
// Adds coordinates to the collection when map mouse up
// e.MapCoordinate直接获取鼠标当前单击位置的作保，这个点已经转换为地图的空间参考系
m_coordinateCollection.Add(e.MapCoordinate);
// Counts coordinates
int count = m_coordinateCollection.Count;
// Create the polygon when coordinate collection has sizelements
if (count == 6)
{
// creates a polygon using the 6 coordinates ：使用坐标点的集合创建一个多边形
m_polygon = new Polygon(m_coordinateCollection);
// Redraws the client area
map1.Invalidate();
// Cleans the coordinate collection
m_coordinateCollection = null;
return;
}
// Redraws the client area
map1.Invalidate();
}
private void map1_Paint(object sender, ESRI.ArcGIS.Mobile.MapPaintEventArgs e)
{
// Draws the coordinate collection to provide some feedback
if (m_coordinateCollection != null)
e.Display.DrawPolyline(Pens.Red, m_coordinateCollection);
if (m_polygon == null || m_polygon.IsEmpty)
return;
// Draws the polygon geometry
e.Display.DrawPolygon (Pens.Blue, Brushes.LightBlue as SolidBrush, m_polygon);
}
This code will draw a feedback polyline and in the sixth map mouse up a polygon will be created and drawn as shown.
这些代码将会绘制一个反馈的线，当鼠标第六次谈起的的时候，将会创建一个多边形，绘制效果如下所示：
A polyline is an ordered collection of parts. Each part is itself a collection of coordinates, and it can be constructed as follows:
折线是parts的有序的集合。每一个部分本身就是坐标的集合，它可以以以下方式构造
[C#]
///
/// Contains a coordinate collection, captured when map mouse up
///
private CoordinateCollection m_coordinateCollection;
// contains a polyline geometry
private Polyline m_polyline;
private void map1_MouseUp(object sender, ESRI.ArcGIS.Mobile.MapMouseEventArgs e)
{
// If collection is null then creates a new instance
if (m_coordinateCollection == null)
m_coordinateCollection = new CoordinateCollection();
// Adds coordinates to the collection when map mouse up
m_coordinateCollection.Add(e.MapCoordinate);
// Counts coordinates
int count = m_coordinateCollection.Count;
// Create the polygon when coordinate collection has sizelements
if (count == 6)
{
// creates a polygon using the 6 coordinates
//m_polygon = new Polygon(m_coordinateCollection);
m_polyline = new Polyline(m_coordinateCollection);
// Redraws the client area
map1.Invalidate();
// Cleans the coordinate collection
//情况坐标集合
m_coordinateCollection = null;
return;
}
private void map1_Paint(object sender, ESRI.ArcGIS.Mobile.MapPaintEventArgs e)
{
// Draws the coordinate collection to provide some feedback
if (m_coordinateCollection != null)
e.Display.DrawPolyline(Pens.Red, m_coordinateCollection);
if (m_polyline == null || m_polyline.IsEmpty)
return;
// Draws the polygon geometry
e.Display.DrawPolyline (Pens.Blue, m_polyline);
}
This code will create and draw a polyline on in the Map as shown.
An envelope（矩形） is an integer rectangle that contains the location and size of a rectangular region with sides parallel to the coordinate system. and it can be constructed as follows:
Envelope是一个整型的矩形，它包含一个矩形区的位置和大小，这个矩形的两边平行于坐标系统。 它可以用一下方式绘制：
[C#]
///
/// Constains the map coordinate when a map mouse is down
///
private Coordinate m_mousedownCoordinate;
private void map1_MouseDown(object sender, ESRI.ArcGIS.Mobile.MapMouseEventArgs e)
{
// Gets the map mouse down coordinate in map space
m_mousedownCoordinate = e.MapCoordinate;
// Redraws the client area
map1.Invalidate();
}
private void map1_Paint(object sender, ESRI.ArcGIS.Mobile.MapPaintEventArgs e)
{
if (m_mousedownCoordinate == null || m_mousedownCoordinate.IsEmpty)
return;
// Converts a 20 pixel screen distance into map space distance
int delta = map1.ToClient(20);
// Creates a new instance of an Envelope, using the map mouse down coordinate
// and a width and height
Envelope envelope = new Envelope(m_mousedownCoordinate, delta, delta);
// Draws the envelope's geometry
e.Display.DrawEnvelope(Pens.Blue, Brushes.LightBlue as SolidBrush, envelope);
}
This code will create and draw a envelope in the Map as shown.
Working with parts
Multipoint, polyline and polygon geometry can contain a collection of parts, and each part is a collection of coordinates. The following example shows how to create a multipart polygon conformed(遵守，适应) by a shell and a hole.
Creating a multipart polygon. The following example shows how to create a polygon geometry that contains a shell and a hole.
Multipoint, polyline and polygon geometry可以包含一个parts的结合，并且，每一个parts都是一个坐标的集合。 下面的例子展示了如何创建一个遵守面和洞的multipart 多边形。
创建一个multipart多边形。 下面的例子展示如何创建一个包含一个面和一个洞的多边形。
[C#]
///
/// Contains an polyline geometry
///
ESRI.ArcGIS.Mobile.Polygon m_polygon;
private void button1_Click(object sender, EventArgs e)
{
CreateMultipartPolygon();
}
private void CreateMultipartPolygon()
{
// Creates a new empty instance of a polygon.
m_polygon = new ESRI.ArcGIS.Mobile.Polygon();
// Creates an instance of a coordinate collection
CoordinateCollection coordinateCollection = new CoordinateCollection();
// Creates a new coordinate
Coordinate coordinate = new Coordinate(-400702006.0, 27709784.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-304035434.0, 28847038.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-305172688.0, 66376413.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-360898123.0, 69788174.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-360898123.0, 95945011.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-399564752.0, 95945011.0);
coordinateCollection.Add(coordinate);
// This creates a shell and if coordinates are counter clockwise, the AddShell
// constructor will make sure to reverse them
m_polygon.AddShell(coordinateCollection);
// Creates an instance of a coordinate collection
coordinateCollection = new CoordinateCollection();
// Creates a new coordinate
coordinate = new Coordinate(-358623616.0, 35670560.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-357486362.0, 59552890.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-317682480.0, 59552890.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-317682480.0, 37945068.0);
coordinateCollection.Add(coordinate);
coordinate = new Coordinate(-358623616.0, 35670560.0);
coordinateCollection.Add(coordinate);
// This creates a hole and if coordinates are clockwise, the AddHole
// method will reverse them
m_polygon.AddHole(coordinateCollection);
// Redraws the client area
map1.Invalidate();
}
private void map1_Paint(object sender, ESRI.ArcGIS.Mobile.MapPaintEventArgs e)
{
if (m_polygon == null || m_polygon.IsEmpty)
return;
// Draws the polygon's geometry
e.Display.DrawPolygon(Pens.Blue, Brushes.LightBlue as SolidBrush, 4, m_polygon);
}
This code will create and draw a multipart polygon in the Map as shown.
这些代码将创建并在地图上绘制一个multipart多边形，如下所示：
Removing parts from a geometry. Reusing the creating a multipart polygon example, the following code shows how to remove a part either by removing the part using its index or by removing a hole for a particular shell.
从geomtry中移除部分。 重新使用【创建一个multipart多边形的例子】，下面的代码展示了如何移除部分：通过使用它们的index来移除部分或者通过从一个特殊的面中移除一个洞。
[C#]
private void button2_Click(object sender, EventArgs e)
{
RemoveHoleAtIndex();
// Redraws the client area
map1.Invalidate();
}
private void RemoveHoleAtIndex()
{
// Removes the part index 1 for a given multipart polygon
// In this case the hole will be removed
m_polygon.RemovePartAt(1);
}
or
private void RemoveHole()
{
// Removes the hole for the shell indexed 0 and the hole indexed 0
m_polygon.RemoveHolesAt(0,0);
}
This code will create a multipart polygon and it will delete the hole part in the geometry as shown.
Finding a part in geometry. Reusing the previous example, first create the geometry and with the following code shows how to find a part using the map mouse down.
查询geometry中的一部分。 重新使用上一步的例子，首先创建geometry，下面的代码展示了使用地图鼠标单击如何查找geometry的一部分。
[C#]
private void map1_MouseDown(object sender, ESRI.ArcGIS.Mobile.MapMouseEventArgs e)
{
// Constains the nearest geometry coordinate found based on the input coordinate
Coordinate outCoordinate = new Coordinate();
// Contains the square distance betewen the in coordinate and the out coordinate
double squareDistance = 0.0;
// Part index, and closest vertex index
int part = -1, vertex = -1;
// Retrieves the polygon's geometry
Geometry geometry = m_polygon as Geometry;
// Finds the closest geometry coordinate based on the input coordinate
geometry.GetNearestCoordinate(e.MapCoordinate, outCoordinate, ref part, ref vertex, ref squareDistance);
// Gets the found part coordinate collection
CoordinateCollection coordinateCollection = new CoordinateCollection(m_polygon.GetPart(part));
// Flashes the found part
map1.FlashGeometry(Pens.Green, Brushes.LimeGreen as SolidBrush, 5, 300, 3, new Polygon(coordinateCollection));
}
This code will create a multipart polygon and in map mouse down the found part will be highlighted as shown.
Sketch（概述） map action
The Sketch map action is a helper component that you can levererage to create tools to create and edit geometry. It encapsulates（装入、包含） most editing tasks such as creating new features and deleting vertices from existent geometries. For more information see Using the sketch map action.
Sketch map action 是一个帮助组件，你可以影响他创建工具，然后用工具创建以及编辑geometry。它包含大所数的编辑任务比如：创建新的要素、从已有的geometry中删除节点。 更过消息，请查看Using the sketch map action.