ArcGIS Runtime SDK for Windows Mobile - Developing with geometry

ArcGIS Runtime SDK for Windows Mobile is based on the location of features, and those locations are represented as geometries in your databases. The ArcGIS Runtime SDK for Windows Mobile includes a set of geometry components you can use to create and update the position and 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 the local map cache or maintained separately (that is, a live traffic feed). Available geometry types include point, multipoint, polyline, polygon, and envelope. This topic discusses how geometry is managed with ArcGIS Runtime SDK for Windows Mobile and illustrates how to use it in various examples.

Geometries in maps

The spatial reference, extent, and the precision of the geometry you create and manage is stored in the schema of the map cache and is determined by properties of the map document that you publish or from which you extract mobile cache. 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 to work with. The default is the active data frame or focus map.

A focus map contains the following information, which is important to how you work with geometry in the software development kit (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, as with ArcGIS for 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's important that you consider extent if you're building an editing application that requires high accuracy data.

Coordinate storage, precision, and calculating extents

ArcGIS Runtime SDK for Windows Mobile manages geometries in double-precision coordinates; however, internally, geometry coordinates are stored as integer units. The main reason is that Windows mobile devices do not have math co-processors, which causes floating-point arithmetic to be slower than manipulating integers. As a result, precision may 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 meter).

To calculate the maximum height or width of the map extent to preserve resolution, use the following equation:

Maximum Extent = 2,147,438,647 * resolution

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).

Point geometry

A point geometry is a zero-dimensional object that represents a real world location in a two-dimensional plane. The following example creates a point at a particular lat, long coordinate:

private ESRI.ArcGIS.Mobile.Geometries.Point m_point;

private void CreatePoint() 
{ 
  // Creates a new instance of a Point using some lat/lon coordinates 
  // Latitude value 
  double lat = 34.058247; 

  // Longitude value 
  double lon = -117.198104; 

  // Converts a WGS84 coordinate to a Mobile coordinate 
  Coordinate coordinate = mobileCache1.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.WinForms.MapPaintEventArgs e) 
  {
    if (m_point == null || m_point.IsEmpty) 
      return; 

    // Draws the point geometry
    e.MapSurface.DrawPoint(Pens.Blue, Brushes.LightBlue as SolidBrush, 50, m_point);
  }

Multipoint geometry

A multipoint geometry is an ordered collection of points, and it can be constructed as follows:

Multipoint mp = new Multipoint();

//add coordinate from center of view area
Coordinate ccord = map1.MapLayers[0].InitialExtent.Center;
mp.AddCoordinate(ccord);

ccord = map1.MapLayers[0].InitialExtent.UpperLeft;
mp.AddCoordinate(ccord);

sketchGraphicLayer1.Geometry = mp;

Polygon geometry

A polygon is a collection of rings or parts 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 requires a minimum of three points to construct a valid polygon.

Two polygon geometries showing a shell and a shell with a hole, and their associated coordinate collection orientation.

map1.MapAction = addVertexSketchTool1;
sketchGraphicLayer1.Geometry = new Polygon();

//after using the mouse to create a polygon you can save the geometry in a featureclass
FeatureDataTable fTable = editsource.GetDataTable();

// creates a new row
DataRow editedFeature = fTable.NewRow();

//sets the new geometry to the feature layer data table
fTable.Rows.Add(editedFeature);

//sets the new geometry to the geometry field
editedFeature[editsource.GeometryColumnIndex] = sketchGraphicLayer1.Geometry;

// updates the feature layer data table
fTable.SaveInFeatureSource();

Polyline geometry

A polyline is an ordered collection of parts, and each part can be a collection of coordinates. It differs from a polygon since it does not form a closed loop, and it is more complex than a line.

map1.MapAction = addVertexSketchTool1;
sketchGraphicLayer1.Geometry = new Polyline();

//after using the mouse to create a polygon you can save the geometry in a featureclass
FeatureDataTable fTable = editsource.GetDataTable();

// creates a new row
DataRow editedFeature = fTable.NewRow();

//sets the new geometry to the feature layer data table
fTable.Rows.Add(editedFeature);

//sets the new geometry to the geometry field
editedFeature[editlayer.GeometryColumnIndex] = sketchGraphicLayer1.Geometry;

// updates the feature layer data table
fTable.SaveInFeatureSource();

Envelope geometry

An envelope is a rectangle region with side parallel to the coordinate system. It is used extensively in the system to define extents.

//use the resize method on the envelope to zoomin on the map display
map1.Extent = map1.Extent.Resize(0.5);

Working with geometry parts

Multipoint, polyline, and polygon geometry are a collection of parts, and each part is a collection of coordinates. While most development will not require this detailed functionality, it is possible. The following example shows how to create a multipart polygon conformed by a shell and a hole:

// Creates a new empty instance of a polygon.
  Polygon m_polygon = new Polygon();

  // Creates an instance of a coordinate collection
  CoordinateCollection coordinateCollection = new CoordinateCollection();

  // Creates a new coordinate
  //autogenerate coordinates from map extent
  Coordinate coordinate = map1.Extent.Resize(0.1).UpperLeft;
  coordinateCollection.Add(coordinate);
  coordinate = map1.Extent.Resize(0.1).UpperRight;
  coordinateCollection.Add(coordinate);
  coordinate = map1.Extent.Resize(0.1).BottomRight;
  coordinateCollection.Add(coordinate);
  coordinate = map1.Extent.Resize(0.1).BottomLeft;
  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 = map1.Extent.Resize(0.05).UpperLeft;
  coordinateCollection.Add(coordinate);
  coordinate = map1.Extent.Resize(0.05).UpperRight;
  coordinateCollection.Add(coordinate);
  coordinate = map1.Extent.Resize(0.05).BottomRight;
  coordinateCollection.Add(coordinate);
  coordinate = map1.Extent.Resize(0.05).BottomLeft;
  coordinateCollection.Add(coordinate);

  // This creates a hole and if coordinates are clockwise, the AddHole
  // method will reverse them
  m_polygon.AddHole(coordinateCollection);
  sketchGraphicLayer1.Geometry = m_polygon;

This code uses the map extent to create a new polygon with a hole; however, the coordinate collection can be from different sources such as a Global Positioning System (GPS) or digitizer. The multipart geometry also supports a variety of edit operations, such as RemoveHolesAt() and GetNearestCoordinate().

1/7/2015