Developing with geometry

ArcGIS Mobile is based on the location of features, and those locations are represented as geometry in our databases. The ArcGIS Mobile SDK includes a set of geometry components that you can use to create and update the positions 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 a map or a local map 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.

Geometries in maps

The spatial reference, extent and the precision of the geometry that you create and manage in ArcGIS Mobile 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.

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.

Coordinate storage, precision and calculating extents

The ArcGIS Mobile SDK manages geometries in double-precision coordinates, but internally geometry coordinates are stored as integer units. 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 meter).

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

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 will create 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 
  // 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);
 }

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].GetExtent().GetCenter();
mp.AddCoordinate(ccord);
ccord = map1.MapLayers[0].GetExtent().GetUpperLeft();
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.

map1.CurrentMapAction = addVertexSketchTool1;
sketchGraphicLayer1.Geometry = new Polygon();
//after using the mouse to create a polygon you can save the geometry in a featureclass
FeatureDataTable fTable = editlayer.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.SaveInFeatureLayer();

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 just a line.

map1.CurrentMapAction = addVertexSketchTool1;
sketchGraphicLayer1.Geometry = new Polyline();
//after using the mouse to create a polygon you can save the gemetry in a featureclass
FeatureDataTable fTable = editlayer.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.SaveInFeatureLayer();

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.SetExtent(map1.GetExtent().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 mapextent
Coordinate coordinate = map1.GetExtent().Resize(0.1).GetUpperLeft();
coordinateCollection.Add(coordinate);
coordinate =  map1.GetExtent().Resize(0.1).GetUpperRight();
coordinateCollection.Add(coordinate);
coordinate = map1.GetExtent().Resize(0.1).GetBottomRight();
coordinateCollection.Add(coordinate);
coordinate = map1.GetExtent().Resize(0.1).GetBottomLeft();
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.GetExtent().Resize(0.05).GetUpperLeft();
coordinateCollection.Add(coordinate);
coordinate = map1.GetExtent().Resize(0.05).GetUpperRight();
coordinateCollection.Add(coordinate);
coordinate = map1.GetExtent().Resize(0.05).GetBottomRight();
coordinateCollection.Add(coordinate);
coordinate = map1.GetExtent().Resize(0.05).GetBottomLeft();
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;

The above 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 GPS or digitizer. The multipart geometry also supports a variety of edit operations; such as removeholeatindex, removehole, and getnearestcoordinate.