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.
For an overview of geometry analysis, see Introduction to geometry analysis in the developer guide.
Create geometry
Geometries are immutable. Most geometries are created and not changed for their lifetime. Examples include feature geometry created for storage in a geodatabase, read from a non-editable layer, or returned from tasks such as spatial queries, geocode operations, network traces, or geoprocessing. Immutable geometries (geometries that cannot be changed) offer some significant benefits to your app. They are inherently thread-safe, help prevent accidental changes, and 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). See the Geometry topic for more information about types of available geometry.
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
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.
val wgsPoint = Point(x = -122.411445, y = 37.773017, spatialReference = SpatialReference.wgs84())
val projectedPoint = GeometryEngine.projectOrNull(wgsPoint, SpatialReference.webMercator())
?: return logErr("GeometryEngine unable to project.")
Measure 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() and area() methods.
However, if you're measuring large areas or distances that need to take into account the curvature of the earth, use the lengthGeodetic() or 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.
Different types of unit of measurement can be used throughout this API. Projected coordinate systems define coordinates using linear measurements, for example using meters or miles, which are represented by LinearUnit. Linear units are also used to return distance measurements, for example by some members of GeometryEngine. Geographic coordinate systems define coordinates using angular measurements, for example using degrees or radians, which are represented by AngularUnit. Methods that calculate the size of areas, for example in acres or square kilometers, use area units. These are represented by AreaUnit. Linear, angular, and area units can be defined by using enumerations of the most common units of measurement. They can also be defined by Well-Known ID (WKID) or Well-Known Text (WKT).
Topological 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.
Evaluate 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.
Convert to and from JSON
Geometries can be serialized and de-serialized to and from JSON. The ArcGIS REST API documentation describes the JSON representation of geometry objects. You can use this encoding and decoding mechanism to exchange geometries with REST Web services or to store them in text files.
Converting to or from JSON can add points to multipart geometries if the geometry has insufficient points to construct a segment.
// Return a polygon as json-formatted text.
val jsonString = coloradoPoly.toJson()
// Re-create the polygon from json using the fromJson() companion object method on Geometry
val newPoly = Geometry.fromJsonOrNull(jsonString) ?: return logErr("Unable to return json from the geometry")
True curves
Sometimes, shapes that appear as curves on a map are really a series of connected linear segments that approximate a curve. For many use cases (and depending on the accuracy you require for the data), this is an acceptable way to represent curved features. ArcGIS can also store and display geometry using segments that accurately represent curvilinear geometry. Curved segments are represented with instances of the EllipticArcSegment or CubicBezierSegment classes. These segments are referred to as true curves.
You can use GeometryEngine.densifyOrNull() to create an approximated curve from a true curve based on several linear segments. Such a curve is often referred to as a densified curve.
By default, ArcGISEnvironment.serviceCurveGeometryMode is ServiceCurveGeometryMode.TrueCurveClient, meaning that as well as fetching curves when requesting existing geometries from the feature services, your app also indicates to the service that it is a true curve client when making updates. Use ArcGISEnvironment.serviceCurveGeometryMode to change this default behavior. Curve geometries stored in services where ArcGISFeatureServiceInfo.onlyAllowTrueCurveUpdatesByTrueCurveClients is true can be updated by default, and you must ensure your app correctly handles curve segments in geometries throughout feature geometry editing workflows. If you cannot ensure curves are maintained throughout editing workflows, set ArcGISEnvironment.serviceCurveGeometryMode to ServiceCurveGeometryMode.DensifyCurves. You must do this before any calls to services are made, as it cannot be changed after making the first request.