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.
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 type||Description||Example of use|
A single point location
Location of survey monument
An ordered collection of zero or more point locations in one geometry
Locations of multiple bore holes at a drilling site
A single two-vertex line
The shortest path from one point to another
One or more lines, each with two or more vertices
A road centerline
An area, possibly multipart, whose parts may have interior holes
A group of islands
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.
- 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.
- 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.
The GeometryEngine performs geometric operations, such as measuring distance, determining spatial relationships, and altering geometries, all locally on the client. Each of the geometry engine methods are static, which means they can be called directly on the class (without instantiating an object variable).
var bufferPolygon = Esri.ArcGISRuntime.Geometry.GeometryEngine.Buffer(inputPoints, 200);
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 Length and Area methods.
double lineLength = Esri.ArcGISRuntime.Geometry.GeometryEngine.Length(myPolyline); double polyArea = Esri.ArcGISRuntime.Geometry.GeometryEngine.Area(myPolygon);
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.
- NearestVertex —The vertex on the boundary of a line or polygon that is nearest to the specified point.
- NearestCoordinate —The coordinate on the boundary of a line or polygon that is nearest to the specified point. This coordinate need not be a vertex.
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.
- Equals—True if two input geometries are the same. False if either are null, have different geometry types, or are 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.
// This returns true ... bool contains = Esri.ArcGISRuntime.Geometry.GeometryEngine.Contains(europePolygon, belgiumPolygon); // This returns false ... bool contains = Esri.ArcGISRuntime.Geometry.GeometryEngine.Contains(belgiumPolygon, europePolygon);
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 a new geometry by projecting an existing point // define the output spatial reference (Web Mercator) var webMercatorSpatialRef = new Esri.ArcGISRuntime.Geometry.SpatialReference(102100); // call Project on the GeometryEngine, pass in the geometry to project and the out spatial reference var myWebMercPoint = Esri.ArcGISRuntime.Geometry.GeometryEngine.Project(myGeographicPoint, webMercatorSpatialRef);
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.
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.