Introduction to geometry operators

Basic usage

The ArcGIS Maps SDK for JavaScript ArcGIS Maps SDK for JavaScript, previously known as ArcGIS API for JavaScript, is a developer product for building mapping and spatial analysis applications for the web. Learn more provides a variety of capabilities for performing client-side geometric operations on points, multipoints, lines, polygons and extents. Geometry operators are modular functions that perform specific geometric operations.

Here is an example of calculating a buffer around a polyline:

import { bufferExecute } from "@arcgis/core/geometry/operators/bufferOperator.js";

// Calculate the buffer of a polyline geometry
const buffer = bufferExecute(polyline, 1000, { unit: "feet" });

Some operators load dependencies on demand. These operators provide *IsLoaded() functions to check their loaded state and *Load() functions to load the required dependencies.

For example, geodesicBufferOperator uses additional resources to perform geodetic calculations. Before creating a geodesic buffer, check geodesicBufferIsLoaded() and, if necessary, await geodesicBufferLoad():

import {
  geodesicBufferIsLoaded,
  geodesicBufferLoad,
  geodesicBufferExecute
  } from "@arcgis/core/geometry/operators/geodesicBufferOperator.js";

if (!geodesicBufferIsLoaded()) {
  await geodesicBufferLoad();
}

// Calculate the geodesic buffer of a polyline geometry
const bufferGeometry = geodesicBufferExecute(polyline, 1000, { unit: "feet" });

Refer to the API reference for each operator to determine whether it requires loading.

Categories

The geometry operators are grouped into functional categories: bounding, densify and generalize, feature to point, linear referencing, linear transformations, measurements, projection, nearest, spatial relationships, and topological operations.

Bounding

Bounding operators determine an enclosing shape around a geometry. The resulting geometry can be used for operations such as quickly identifying potential intersections or overlaps. The result geometry can be used to significantly improve the performance of spatial analysis.

• alphaShapeOperator
• boundaryOperator
• convexHullOperator
• minimumBoundingCircleOperator

Densify and generalize

Densifying a multipart geometry adds more vertices at regular intervals. Generalizing a multipart geometry simplifies it by removing vertices while preserving its general shape.

• densifyOperator
• generalizeOperator
• geodeticDensifyOperator

Feature to point

Feature to point operations are used to locate a specific interior point in a polygon or extent.

• centroidOperator
• labelPointOperator

Linear referencing

Linear referencing is a method for determining geographic locations as relative positions between or along a measured line feature.

locateBetweenOperator

Linear transformations

Linear transformations alter the location, shape, or orientation of geometries by manipulating their coordinates, such as by flipping or scaling them.

affineTransformOperator

Measurements

Measurement operations are for determining the dimensions of geometric shapes.

• areaOperator
• distanceOperator
• geodeticAreaOperator
• geodeticDistanceOperator
• geodeticLengthOperator
• geodeticUtilsOperator
• lengthOperator

Nearest

Nearest operations are for determining aspects of the physical closeness of one geometry to another.

• geodesicProximityOperator
• isNearOperator
• proximityOperator

Projection

Projection operations involve transforming the vertices of geometries from one spatial reference to another.

• projectOperator
• shapePreservingProjectOperator

Spatial relationships

Spatial relationships are about understanding where geometries are in relation to each other to define their arrangement and interactions.

• containsOperator
• crossesOperator
• disjointOperator
• equalsOperator
• intersectsOperator
• overlapsOperator
• relateOperator
• touchesOperator
• withinOperator

Topological

Topological operations create new geometries by modifying, combining, or analyzing the spatial structure of input geometries.

• autoCompleteOperator
• bufferOperator
• clipOperator
• cutOperator
• differenceOperator
• geodesicBufferOperator
• graphicBufferOperator
• extendOperator
• integrateOperator
• intersectionOperator
• multiPartToSinglePartOperator
• offsetOperator
• polygonOverlayOperator
• reshapeOperator
• linesToPolygonsOperator
• polygonSlicerOperator
• simplifyOGCOperator
• simplifyOperator
• symmetricDifferenceOperator
• unionOperator

Working with spatial relationship operators

Dimensionality

For geometry operators, dimension describes whether a geometry represents a point, length, or area in the x-y plane. Spatial relationship operators use dimensionality to determine whether a relationship holds. Z- and m-coordinates do not affect a geometry’s dimension.

• 0 — Points and multipoints; has neither length nor area.
• 1 — Polylines; has length but no area.
• 2 — Extents and polygons; has area.

The dimension of an intersection can affect the result. For example, two polygons that intersect only at a point do not overlap because their intersection has dimension 0, not 2.

Acceleration

Acceleration is typically most beneficial when:

• A geometry contains thousands of vertices.
• The same geometry is reused in many relational operations.
• The geometry is compared against many other geometries.

Acceleration is usually unnecessary for:

• Small geometries.
• One-time comparisons.

If you perform spatial relationship operations repeatedly on the same polygon or polyline, consider accelerating the geometry to improve performance. Acceleration creates optimized data structures, such as a spatial index, that operators can use to execute more efficiently.

Accelerating a geometry takes time and uses additional memory, so it may not improve performance for a small number of operations. The performance benefit depends on the number of vertices and how often the geometry is reused. For geometries with more than 10,000 vertices, acceleration may provide a benefit with as few as ten operations. For geometries with fewer than 200 vertices, a benefit may not be noticeable until the geometry is used in 100 to 200 operations.

Acceleration does not affect the result of an operation. An accelerated geometry can also be passed to operators that do not support acceleration; these operators ignore the acceleration data. Acceleration is optional and applies only to certain operators, such as spatial relationship operators.

Use an accelerated geometry

Spatial relationship operators provide an *AccelerateGeometry() function that returns a boolean. When a geometry is passed to an acceleration function, it will return true if the geometry was successfully accelerated, or false if the acceleration isn’t useful for the input. For example, accelerating a point will always return false.

// Returns true if the polygon has been successfully accelerated in the containsOperator
const accelerated = containsAccelerateGeometry(polygon);

if (accelerated) {
  // Use the accelerated polygon in an iterative function
  const results = featuresSet.map((feature) => {
    const contained = containsExecute(polygon, feature.geometry);
    return {
      feature,
      contained,
    };
  });
}

Working with geodetic operators

Geodetic curve types

In a planar context, the interpretation of a segment connecting two vertices is unambiguously a straight line. In a geodetic context, however, two vertices are connected by a curve on the surface of a spheroid. The interpretation of a geometry’s segments is not embedded, so it must be provided as an option to the geodesy-aware operators.

The curveType option supports five values geodesic, great-elliptic, loxodrome, normal-section, and shape-preserving. The choice of curve type depends on how segments should be interpreted and can significantly affect performance.

• geodesic: A segment is defined as the shortest path between two points on the surface of a spheroid.

• great-elliptic: A segment is defined by the intersection of the spheroid with a plane that passes through the segment endpoints and the center of the spheroid. On a sphere, this is a great circle arc. Note that a great-elliptic path is not necessarily the shortest path between two points on a spheroid.

• loxodrome: A segment is defined as a path of constant bearing, or azimuth, between two points. It represents a rhumb-line path on the earth that crosses each meridian at a constant angle. Loxodromes appear as straight lines in the Mercator projection.

• normal-section: A segment is defined by the intersection of the spheroid with a plane that passes through the two segment endpoints and is perpendicular to the spheroid’s surface at the first point. A normal-section path is not necessarily the shortest path between two points.

• shape-preserving: A segment is defined as a straight line in the spatial reference where the geometry is defined.

The SDK supports these five curveTypes when working with the following operators:

• geodesicBufferOperator
• geodeticAreaOperator
• geodeticDensifyOperator
• geodeticDistanceOperator
• geodeticLengthOperator

See the Geodetic Distance Visualizer sample for an example of using these curve types.