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. You can perform spatial analysis by relating geometries in a near-endless number of ways. Some examples include:
- 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 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 Geometry 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 (Point) | A single point location | Location of survey monument |
Multipoint (Multipoint) | An ordered collection of zero or more point locations in one geometry | Locations of multiple bore holes at a drilling site |
Segment (Segment) | A single two-point line | The shortest path from one point to another |
Polyline (Polyline) | One or more lines, each with two or more vertices | A road centerline |
Polygon (Polygon) | An area, possibly multipart, whose parts may have interior holes | A group of islands |
Envelope (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 (PolygonBuilder to work with Polygon, for example).
Geometry engine
The GeometryEngine 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 are 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 GeometryEngine 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 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(of:) and area(of:) methods.
However, if you're measuring large areas or distances that need to take into account the curvature of the earth, use the geodeticLength(of:lengthUnit:curveType:) or geodeticArea(of:unit:curveType:) 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 GeometryEngine 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 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.
- 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 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 GeometryEngine 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.