Spatial reference and data analysis

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

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 the SDK, you can perform spatial analysis by relating geometries in a near-endless number of ways. Some examples include:

• Determine whether a proposed business site is within 300 meters of any competitors.
• Find the homes that are closest to a fire perimeter.
• Calculate the total length of paved roads within the city boundary.

Create geometry

The API includes a ArcGISGeometry base class. The following table summarizes the classes that inherit from this class. See the Geometry topic for details.

Geometry type	Description	Example 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 boreholes at a drilling site
Segment	A single two-point line	The shortest path from one point to another
Polyline	One or more lines, each with two or more vertices	A road centerline
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

Geometry builders

Geometries are immutable. Immutable geometries (geometries that cannot be changed) offer some important benefits to your app. They are inherently thread-safe, they help prevent inadvertent changes, and they allow for certain performance optimizations.

While immutable geometries appear to present problems for editing existing geometries, those problems are solved by using geometry builders. Geometry builders are designed to represent the state of a geometry under construction while allowing modifications, thus enabling editing workflows.

Use the appropriate builder to work with existing geometries of each type (ArcGISPolygonBuilder to work with ArcGISPolygon, for example).

Geometry engine

The ArcGISGeometryEngine can be used to perform geometric operations, measure geometries, evaluate spatial relationships, and project geometries to a new spatial reference, all locally on the client. Each of the geometry engine methods is static, which means they can be called directly on the class (without instantiating an object variable).

Project geometries to a new spatial reference

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

See the spatial references topic for more details about working with spatial references.

Measuring distance

Often, you want to know the length or area of geometry. You may want to know the length of a river or the area of a county. There are several ways to measure length and area using the geometry engine. You can measure simple distances and areas using the ArcGISGeometryEngine.Length and ArcGISGeometryEngine.Area methods.

However, if you're measuring large areas or distances that need to take into account the curvature of the earth, use the ArcGISGeometryEngine.LengthGeodetic() or ArcGISGeometryEngine.AreaGeodetic() method.

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

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

Geometry operations

You can use the ArcGISGeometryEngine to 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.
• Densify: Create a densified copy of the input geometry by adding vertices between existing vertices.
• Difference: Create a geometry that is the topological difference between two geometries.
• Offset: Create an offset version of the input geometry.
• Union: Create a geometry that is the union of two or more 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: Makes geometry topologically consistent according to the geometry type. For instance, it rectifies polygons that may be self-intersecting or contain incorrect ring orientations.

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 circumscribes 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 ArcGISGeometryEngine supports are as follows:

• Contains: The base geometry completely contains the comparison geometry.
• Crosses: The geometries share some interior areas, but not all interior areas.
• 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.
• Equals: True if two input geometries are the same. False if either is null, has different geometry types, or is geometrically distinct.

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.