ArcGIS API for JavaScript

GeometryEngine part 1: Testing spatial relationships and editing

This is the first post in a three-part series exploring GeometryEngine in the ArcGIS API for JavaScript. This series will cover the following topics:

Overview

Earlier this year GeometryEngine and its asynchronous counterpart GeometryEngineAsync were released (beta) in versions 3.14 and 4.0 beta 1 of the ArcGIS API for JavaScript. These modules each provide more than 30 methods for measuring, overlaying, and testing spatial relationships between geometries in web applications. GeometryEngine includes functions such as buffer, intersect, and offset for calculating proximity, spatial relationships, and measurements of area and length. This sounds a lot like GeometryService, so what’s the big deal? What sets GeometryEngine apart is that it does all of its work client-side.

That’s right. No network requests are made when using any GeometryEngine functions. This means that using GeometryEngine in favor of GeometryService can significantly enhance the performance of web applications, particularly if they make frequent requests with GeometryService or deal with a large number of geometries.

Testing spatial relationships in editing applications

Working client-side makes GeometryEngine particularly powerful when used in web applications designed for editing geometries. Functions that test intersections, feature selections, containment, equality, touching, and other relationships can enhance the integrity of data edits and improve user experience while editing. Without GeometryEngine, many of these functions could not be done without sending many server requests or writing lengthy custom JavaScript modules.

What once required clunky workflows using either GeometryService or a custom geoprocessing task, is now simple with the help of GeometryEngine. For example, the following is an editing sample that demonstrates several GeometryEngine methods including cut, geodesicArea, union, and difference. But it’s the testing functions (offset, disjoint, equals, within, intersects, and crosses) that allow this application to perform the proper cutting, merging, deleting and creating of new features.

Click to open the editing app showcasing GeometryEngine

Open the app and select the polygon. Then proceed to draw a line from one end of the polygon to the other. Notice that once the line completely crosses the polygon, the polygon is immediately cut and the area of each of the resulting polygons is printed at their centroids. Prior to attempting the cut, however, a check is made to see if the first click and the current mouse position are disjoint with the selected polygon; the crosses function is then used to check if the line crosses the selection. These tests ensure the cut operation and area calculations are not performed unless the input parameters will produce a valid cut. These calculations are done each time the mouse is moved.

Similar tests on spatial relationships are done for the other operations, including “Add Features”, which checks if the added geometry is not contained by existing geometries. If a new geometry overlaps existing geometries, the difference of the two is retained. This functionality is useful for ensuring new features are topologically correct.

Performance compared to GeometryService

If GeometryService were used to attempt all of these operations, each of the methods and calculations would require separate requests each time the mouse is moved. The sheer number of requests made to the server (between two and seven per mouse-move) would slow down the app and frustrate the user. However, GeometryEngine removes GeometryServer requests altogether, allowing developers to create apps that would not be usable with GeometryService.

Bypassing server requests also speeds things up when analysis functions are used, such as buffer, intersect, and union. To illustrate the differences in performance between the two modules, check out the following sample (built using the 4.0 beta 1 version of the API) that compares the time it takes to buffer 500 points with GeometryEngine versus GeometryService.

Click to open app comparing GeometryEngine's performance vs GeometryService

In this scenario, GeometryEngine can buffer all 500 points in about two or three seconds, while GeometryService takes longer than 30 seconds to do the same work because all 500 geometries are sent in a server request. The time it takes GeometryEngine and GeometryService to produce results will vary depending on the method, number and complexity of geometries, network speed, and browser; in most cases, however, GeometryEngine will perform faster.

Keep in mind that GeometryEngine isn’t the solution to all problems and it certainly doesn’t replace GeometryService. GeometryService contains several methods that are not part of GeometryEngine. Some of those include project, fromGeoCoordinateString, simplify, and trimExtend.

Stay tuned for additional posts that explore GeometryEngine’s measurement and overlay methods.

About

Kristian is a Product Engineer for the ArcGIS API for JavaScript, focusing on mapping and visualization.

Connect:

Next Article

Web AppBuilder for ArcGIS v2.1 Developer Edition Now Available!

Read this article