# Geometry operations

Geometry operations let you create geometries (shapes with locations) that represent real-world objects and let you compare and relate those shapes.

The term "geometry" in ArcGIS refers to the location and shape of a real-world object or a geometric construct such as an area of interest or a buffer area around an object.

For example, you may want to measure the area of a polygon representing a lake or district. Perhaps you have multiple geometries, and you want to know their relationship to one another. Geometry is the fundamental element for performing spatial analysis. With ArcGIS Runtime SDKs, you can perform spatial analysis by relating geometries in a near-endless number of ways. Additional examples are as follows:

• At a clicked point on the map, display the land area's vegetation type.
• Verify that all the building polygons in a layer lie completely within one of the parcel polygons in another layer.
• Determine whether a proposed school site is within 300 meters of any liquor store.

The API includes two ways to perform geometric operations on your geometry objects: the geometry engine and the geometry Service task.

## Create geometry

Geometries come in different types. A point may represent a light pole, a polyline may represent a street centerline, or a polygon may represent a parcel of land. In addition to single points, polylines, or polygons, there are multipart types as well.

The API includes a geometry class. This base class represents a geometry of any type. There are also classes derived from the geometry class to be used when the geometry type is explicit.

Geometry typeDescriptionExample of use

Point

A single point location

Location of survey monument

Multipoint

An ordered collection of zero or more point locations in one geometry

Locations of multiple bore holes at a drilling site

Line

A single two-vertex line

The shortest path from one point to another

Polyline

One or more lines, each with two or more vertices

Polygon

An area, possibly multipart, whose parts may have interior holes

A group of islands

Envelope

A 4-sided polygon with sides aligned to the x and y axes

An area of interest

A geometry object contains a single geometry. The geometry class also has methods to operate on geometry objects. You can create geometries in some task results by using methods that return geometry objects, and by invoking a class constructor. Examples are as follows:

• A find task finds features in a service using a text search, returning the geometry in the results. The geometry is constructed for you by the API using data returned by the find task.
• You can use an operation such as buffer to create a new geometry from another geometry plus a buffer distance.
• You can call a constructor to create points, polygons, and so on, providing the necessary information for that specific geometry type.

You can create new geometries from existing geometries by performing operations such as these:

• Buffer—Buffer a geometry at a specified distance, creating a buffer polygon.
• Clip—Create a geometry by clipping a geometry with an envelope.

• Cut—Split the input polyline or polygon where it crosses a cutting polyline.

• Densify—Create a densified copy of the input geometry by adding vertices between existing vertices.

• Difference—Create a geometry that is the topological difference of two geometries.

• Offset—Create an offset version of the input geometry.

• Union—Create a geometry that is the union of two or more geometries.

``let modifiedGeometry = geometryEngine.unionGeometries(geometries)``
• Intersection—Create a geometry that is the topological intersection of two geometries.

• Symmetric Difference—Create a geometry that is the topological symmetric difference of two geometries.

• Simplify

## Geometry engine

The geometry engine performs geometric operations, such as measuring distance, determining spatial relationships, and altering geometries, all locally on the device. The geometry engine is a singleton class much like UIApplication. A singleton is a class for which there exists only a single instantiated object. Thus, each time you invoke defaultGeometryEngine, you are returned a reference to the same instance.

``let geometryEngine = AGSGeometryEngine.defaultGeometryEngine()``

### Measuring distance

Often, you want to know the length or area of a geometry. You may want to know the length of a river or the area of a county. There are a number of ways to measure length and area using the geometry engine. You can measure simple distances and areas using the lengthOfGeometry: and areaOfGeometry: methods.

``````let length = geometryEngine.lengthOfGeometry(polyline)
let area = geometryEngine.areaOfGeometry(polygon)``````

However, if you're measuring large areas or distances that need to take into account the curvature of the earth, use the geodesicLengthOfGeometry:inUnit: or shapePreservingAreaOfGeometry:inUnit: method.

Disjoint geometries can be compared as to their distance from one another as follows:

• distanceFromGeometry—The 2-D planar distance between two geometries at their closest points of approach.
• nearestVertexInGeometry—The vertex on the boundary of a line or polygon that is nearest to the specified point.
• nearestCoordinateInGeometry—The coordinate on the boundary of a line or polygon that is nearest to the specified point. This coordinate need not be a vertex.

### Spatial relationships

When you have multiple geometries on a map, you may want to know their relationship to each other. For example, you may want to know if a polyline representing a creek crosses through a polygon representing your property. Given two geometry objects, the geometry engine can tell you whether a given spatial relationship is true of those geometries. The spatial relationship is determined by whether the boundaries or interiors of a geometry intersect. The meaning of boundary and interior are well defined for each basic geometry type.

• Boundary—For lines, the line's endpoints, or the endpoints of each line in a multipart line. For polygons, the line that circumscribes the interior area or areas (for multipart polygons) or circumscribe any interior holes.
• Interior—Points are entirely interior and have no boundary. For lines and polygons, the interior is any part of the geometry that is not part of the boundary.

The basic relationships the geometry engine supports are as follows:

• Contains—The base geometry completely contains the comparison geometry.

• Crosses—The geometries share some interior area, but not all interior area.

• Disjoint—No part of the base geometry intersects the comparison geometry.

• Intersects—Not disjoint.
• Overlaps—The intersection of two points, lines, or polygons is also a point, line, or polygon, respectively.

• Touches—The boundaries of the geometries intersect, but not their interiors.

• Within—The base geometry lies completely within the comparison geometry.

For each spatial relationship, there is a method that returns a Boolean value indicating whether that relationship is true of the two geometries. For spatial relationships that are true of one geometry but not the other, such as Within or Contains, the geometry engine considers the order of the geometries entered.

``````// Returns TRUE if geometry1 contains geometry2
let contains = geometryEngine.geometry(geometry1, containsGeometry: geometry2)``````

### Projecting to different spatial references

There may be times when you have geometries in a map or service with a particular spatial reference and want to display them on a map with a different spatial reference. The geometry engine allows you to do this with a simple method call. When projecting, similar to modifying geometry objects, the instance of the geometry object passed in is not actually changed; rather, a new geometry object is returned. When projecting, you can apply a specific transformation. Different transformations are suitable for different areas of the world or different spatial references. Some Runtime SDKs support a common set of datum transformations and some support grid-based transformations. Grid-based transformations require additional files to be deployed or provisioned.

``````// Create new geometry by projecting old geometry from old to new spatial reference
let sr = AGSSpatialReference.wgs84SpatialReference()
let newGeometry = geometryEngine.projectGeometry(oldGeometry, toSpatialReference: sr)``````

There may be some cases where the geometry engine does not provide support for all the operations you want to do, for example, performing a convex hull operation, or projecting to an uncommon spatial reference that is not supported by the geometry engine. See Spatial references for a list of spatial reference systems supported by the geometry engine.

In such cases, you can use the geometry service task. The device must be able to connect to the network to perform a geometry service task. The geometry service task takes a URL to a geometry service, for example, http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer.

``````let serviceTask = AGSGeometryServiceTask(URL: serviceTaskURL)

Once you create an instance of a service task, you must set the class that will receive its results to be its delegate. Usually this is self. This class must implement the geometry service class protocol. After an operation is performed, it provides its results in its respective return method or provides an error through its failure method.

``````func geometryServiceTask(geometryServiceTask: AGSGeometryServiceTask!, operation op: NSOperation!, didReturnConvexHullGeometry geometry: AGSGeometry!) {
//Do something with geometry
}

println("Error : \(error)")
}``````

## Geodetic and planar lines

In a geometry the path of the line connecting ordered vertices is implied, not stored. Along what path do these lines run? When you view a map on a device, you usually see the vertices connected with straight line segments. As long as the distances are short, such as between corners of a small building, the visual path of the line closely approximates the real location of the edge of the building.

What if the vertices of a line are farther apart? What if one vertex was near the center of Reykjavik, Iceland, and the other near the center of Oslo, Norway? The following map uses the projected coordinate system WGS 84 Web Mercator (auxiliary sphere) to display a map of such a line:

The line appears straight when drawn on the plane of the map surface, passing through the Faroe Islands. On the map surface, this line is the closest path between the points. But in the real world, the Earth is round. The shortest distance between points on the surface of the Earth follows a geodesic path. The geodesic path would appear straight to an observer on the ground. However, the line is curved with respect to the projected coordinate system used in the map.

It is important to remember that in both maps used here, the lines are approximations. When a map is projected onto a 2-D map surface from a 3-D Earth image, the 2-D map cannot perfectly represent all the features on the map. Some objects are distorted, including the path and length of lines, the area of polygons, and the relative position of points. This behavior is normal. The reason there are many coordinate systems is that they are designed to reduce different types of distortion in different areas of the Earth. Keep this in mind when choosing a coordinate system and whether to use the geodetic version of some geometry methods.

## Geometry contents

At its core, a geometry is a collection of one or more vertices (locations) that may be connected, one to the next, in a linear order. A geometry does not store the lines that connect the vertices, such as those that represent the boundary of a polygon. Instead, it stores the vertices in linear order along a polyline’s path or around a polygon. The lines between the vertices are implied by this ordering.

Coordinates are used to denote the location of the vertices. Coordinates can represent 2-D (x,y) or 3-D (x,y,z) locations. The meaning of the x,y,z-coordinates is determined by a coordinate system. The vertices and coordinate system together allow your app to translate a real-world object from its location on the Earth to its location on your map.

Coordinate systems, also known as map projections, provide a common basis for communication about a particular place or area on the Earth's surface. When data sets have the same coordinate system, they can be integrated within a map that uses that coordinate system. Geometries with a coordinate system different from the map’s can be reprojected (translated) to the map’s coordinate system for display. In addition to integrating data sets within maps, coordinate systems allow you to perform various integrated analytical operations such as overlaying data layers that come from different sources.

In the API, a spatial reference class represents a coordinate system. It contains a coordinate system and helper methods to access and use it. The spatial reference class is associated with several other API classes that need a coordinate system to function. For example, layers have an associated spatial reference. Some task parameters, such as those for the query task and the local routing task, are spatial reference objects.

To use the contents of a geometry object, you must know the associated spatial reference. It's meaningless to compare two geometry objects or determine their spatial relationship if they have different spatial references. To display a geometry in a map layer, the geometry must have either the same spatial reference as the layer or be projected to the layer's spatial reference. To use two objects together, if those objects each have a spatial reference, they should have the same spatial reference.

When working with geometry operations, it's important that you understand the basics of spatial references (the different types of coordinate systems there are, when you have to know about spatial references, and so on) that are outlined in Spatial references.

Z-coordinates represent the vertical aspect of a vertex, such as elevation for a location. Z-coordinates may be associated with a vertical coordinate system. Generally, they are not used when drawing the geometry on a 2-D map display.

In some cases, vertex coordinates include measure values, often called m-values. M-values are used in linear referencing to calculate values between polyline vertices. M-values are not used when drawing a geometry. A geometry can contain m-values without containing z-coordinates.

Geometry classes include methods to determine whether the object includes z-coordinates or m-values. Some task parameters, such as those for the find task, allow you to choose whether z-coordinates or m-values should be returned in the result geometries.