Find spatial relationships

Learn how to determine the spatial relationship between geometries.

A spatial relationship, also known as a spatial relation, is how one geometry is topologically associated with another geometry. The association is made based on their interiors, boundaries, and exteriors.

In this tutorial, you will use the geometryEngine to determine spatial relationships between two geometries. To determine if a spatial relationship exists, operations such as intersects, disjoint, and within are used. If the operation is successful, then true is returned.

Prerequisites

Steps

Create a new pen

To get started, either complete the Display a map tutorial or .

Get an access token

You need an access token with the correct privileges to access the location services used in this tutorial.

Go to the Create an API key tutorial and create an API key with the following privilege(s):
- Privileges
  - Location services > Basemaps

In CodePen, set esriConfig.apiKey to your API key..

Use dark colors for code blocks
esriConfig.apiKey = "YOUR_ACCESS_TOKEN";
const map = new Map({
  basemap: "arcgis/topographic" // basemap styles service
});

To learn about other ways to get an access token, go to Types of authentication.

Add modules

In the require statement, add the Graphic, GraphicsLayer, Sketch, and geometryEngine modules.

The ArcGIS Maps SDK for JavaScript is available as AMD modules and ES modules, but this tutorial is based on AMD. The AMD require function uses references to determine which modules will be loaded – for example, you can specify "esri/Map" for loading the Map module. After the modules are loaded, they are passed as parameters (e.g. Map) to the callback function where they can be used in your application. It is important to keep the module references and callback parameters in the same order. To learn more about the API's different modules visit the Overview Guide page.

Expand
Use dark colors for code blocks
        require([
            "esri/config",
            "esri/Map",
            "esri/views/MapView",

            "esri/Graphic",
            "esri/layers/GraphicsLayer",
            "esri/widgets/Sketch",
            "esri/geometry/geometryEngine"

        ], (esriConfig, Map, MapView, Graphic, GraphicsLayer, Sketch, geometryEngine) => {
Expand

Add HTML elements

Add <div> elements to display the spatial relationship between the two geometries in the view.

Using HTML, create div elements to display each spatial relationship to evaluate.

Expand
Use dark colors for code blocks
    <div id="viewDiv"></div>

    <div id="relationshipResults" class="esri-widget">
        <div><b>Spatial relationships</b></div>
        <div id="Contains"></div>
        <div id="Crosses"></div>
        <div id="Disjoint"></div>
        <div id="Equals"></div>
        <div id="Intersects"></div>
        <div id="Overlaps"></div>
        <div id="Touches"></div>
        <div id="Within"></div>
    </div>
Expand

Add relationshipResults to the bottom-right of the view's UI.

Expand
Use dark colors for code blocks
            const view = new MapView({
                map: map,
                center: [-118.80500, 34.02700], //Longitude, latitude
                zoom: 13,
                container: "viewDiv"
            });

            const relationshipDiv = document.getElementById("relationshipResults");
            view.ui.add(relationshipDiv, "bottom-right");
Expand

Add some CSS to format the relationshipResults <div>.

Expand
Use dark colors for code blocks
        #viewDiv {
            padding: 0;
            margin: 0;
            height: 100%;
            width: 100%;
        }

        #relationshipResults {
            width: 175px;
            padding: 10px;
        }
Expand

Create graphics

You need two geometries to execute a spatial relationship operation. Create a polyline and a polygon graphic that displays when the application runs.

Create a new GraphicsLayer and add it to the map.

Expand
Use dark colors for code blocks
            const view = new MapView({
                map: map,
                center: [-118.80500, 34.02700], //Longitude, latitude
                zoom: 13,
                container: "viewDiv"
            });

            const relationshipDiv = document.getElementById("relationshipResults");
            view.ui.add(relationshipDiv, "bottom-right");

            const graphicsLayer = new GraphicsLayer();
            map.add(graphicsLayer);

Expand

Create a polyline graphic and add it to the graphicsLayer.

Expand
Use dark colors for code blocks
            const view = new MapView({
                map: map,
                center: [-118.80500, 34.02700], //Longitude, latitude
                zoom: 13,
                container: "viewDiv"
            });

            const relationshipDiv = document.getElementById("relationshipResults");
            view.ui.add(relationshipDiv, "bottom-right");

            const graphicsLayer = new GraphicsLayer();
            map.add(graphicsLayer);

            const polyline = {
                type: "polyline",
                paths: [
                    [-13227000.704542402, 4032506.197638312],
                    [-13223540.698857695, 4034443.92109266],
                    [-13222135.94452635, 4032506.197638312],
                    [-13221470.479577951, 4033494.9524006792],
                    [-13221470.404932415, 4033494.9524006792]
                ],
                spatialReference: {
                    wkid: 102100
                }
            };
            const simpleLineSymbol = {
                type: "simple-line",
                width: 2
            };
            const polylineGraphic = new Graphic({
                geometry: polyline,
                symbol: simpleLineSymbol
            });
            graphicsLayer.add(polylineGraphic);

Expand

Create a polygon graphic and add it to the graphicsLayer.

Expand
Use dark colors for code blocks
            const view = new MapView({
                map: map,
                center: [-118.80500, 34.02700], //Longitude, latitude
                zoom: 13,
                container: "viewDiv"
            });

            const relationshipDiv = document.getElementById("relationshipResults");
            view.ui.add(relationshipDiv, "bottom-right");

            const graphicsLayer = new GraphicsLayer();
            map.add(graphicsLayer);

            const polyline = {
                type: "polyline",
                paths: [
                    [-13227000.704542402, 4032506.197638312],
                    [-13223540.698857695, 4034443.92109266],
                    [-13222135.94452635, 4032506.197638312],
                    [-13221470.479577951, 4033494.9524006792],
                    [-13221470.404932415, 4033494.9524006792]
                ],
                spatialReference: {
                    wkid: 102100
                }
            };
            const simpleLineSymbol = {
                type: "simple-line",
                width: 2
            };
            const polylineGraphic = new Graphic({
                geometry: polyline,
                symbol: simpleLineSymbol
            });
            graphicsLayer.add(polylineGraphic);

            // Create a polygon geometry
            const polygon = {
                type: "polygon",
                rings: [
                    [-13228098.704542402, 4035365.9427463487],
                    [-13226362.225451587, 4035365.9427463487],
                    [-13226362.225451587, 4032059.2948176656],
                    [-13228098.704542402, 4032059.2948176656],
                    [-13228098.704542402, 4035365.9427463487]
                ],
                spatialReference: {
                    wkid: 102100
                }
            };
            const simpleFillSymbol = {
                type: "simple-fill"
            };
            const polygonGraphic = new Graphic({
                geometry: polygon,
                symbol: simpleFillSymbol
            });

            graphicsLayer.add(polygonGraphic);

Expand

Add the graphics to the selectedGraphics array.

Expand
Use dark colors for code blocks
            graphicsLayer.add(polygonGraphic);

            let selectedGraphics = [polygonGraphic, polylineGraphic];
Expand

Run the code to verify that the graphics appear in the view.

Use the Sketch and GraphicsLayer classes to interactively create a graphic and add it to the view. An event handler will listen for a change from the sketch widget and update the spatial relationship accordingly.

Create the Sketch widget with configurations. Specify the layer as the graphicsLayer we defined earlier. This will allow you to move and update the line and polyline graphics created in the last step. Also, enable the snappingOptions on the Sketch widget. Lastly, set the visibleElements of the widget to remove the tools that are not needed.

Expand
Use dark colors for code blocks
            let selectedGraphics = [polygonGraphic, polylineGraphic];

            const sketch = new Sketch({
                view: view,
                layer: graphicsLayer,
                updateOnGraphicClick: true,
                snappingOptions: {
                    enabled: true,
                    featureSources: [{
                        layer: graphicsLayer
                    }]
                },
                visibleElements: {
                    createTools: {
                        point: false
                    },
                    selectionTools: {
                        "lasso-selection": false,
                        "rectangle-selection": false,
                    },
                    settingsMenu: false,
                    undoRedoMenu: false
                }
            });

Expand

Add the sketch widget to the top right of the view UI.

Expand
Use dark colors for code blocks
            const sketch = new Sketch({
                view: view,
                layer: graphicsLayer,
                updateOnGraphicClick: true,
                snappingOptions: {
                    enabled: true,
                    featureSources: [{
                        layer: graphicsLayer
                    }]
                },
                visibleElements: {
                    createTools: {
                        point: false
                    },
                    selectionTools: {
                        "lasso-selection": false,
                        "rectangle-selection": false,
                    },
                    settingsMenu: false,
                    undoRedoMenu: false
                }
            });

            view.ui.add(sketch, "top-right");
Expand

Run the code to verify that the sketch widget appears in the view.

Determine spatial relationships

Spatial relationships are determined based on the interiors, boundaries, and exteriors of two geometries. Use methods such as contains() and intersects(), to find the spatial relationship between the sketched geometries.

To format the results, create a showSpatialRelationship function. If the valueof the spatial relationship is true, then display the string in bold.

Expand
Use dark colors for code blocks
            view.ui.add(sketch, "top-right");

            function showSpatialRelationship(string, value) {
                const element = document.getElementById(string)
                if (value) {
                  element.innerHTML =   "<b>" + string + ": " + value + "</b>";
                } else {
                 element.innerHTML = string + ": " + value;
                }
            }
Expand

Create a function called onGraphicUpdate.

Expand
Use dark colors for code blocks
            view.ui.add(sketch, "top-right");

            function onGraphicUpdate() {

            }

            function showSpatialRelationship(string, value) {
                const element = document.getElementById(string)
                if (value) {
                  element.innerHTML =   "<b>" + string + ": " + value + "</b>";
                } else {
                 element.innerHTML = string + ": " + value;
                }
            }
Expand

Get the geometries to find the spatial relationships for from the array of selectedGraphics.

Expand
Use dark colors for code blocks
            function onGraphicUpdate() {

                let geometry1 = selectedGraphics[0].geometry;
                let geometry2 = selectedGraphics[1].geometry;

            }
Expand

Test each spatial relationship on the two geometries and display the results in the relationshipResults div. Call the showSpatialRelationship function to display the results.

Expand
Use dark colors for code blocks
            function onGraphicUpdate() {

                let geometry1 = selectedGraphics[0].geometry;
                let geometry2 = selectedGraphics[1].geometry;

                const contains = geometryEngine.contains(geometry1, geometry2);
                showSpatialRelationship("Contains", contains)

                const crosses = geometryEngine.crosses(geometry1, geometry2);
                showSpatialRelationship("Crosses", crosses)

                const disjoint = geometryEngine.disjoint(geometry1, geometry2);
                showSpatialRelationship("Disjoint", disjoint)

                const equals = geometryEngine.equals(geometry1, geometry2);
                showSpatialRelationship("Equals", equals)

                const intersects = geometryEngine.intersects(geometry1, geometry2);
                showSpatialRelationship("Intersects", intersects)

                const overlaps = geometryEngine.overlaps(geometry1, geometry2);
                showSpatialRelationship("Overlaps", overlaps)

                const touches = geometryEngine.touches(geometry1, geometry2);
                showSpatialRelationship("Touches", touches)

                const within = geometryEngine.within(geometry1, geometry2);
                showSpatialRelationship("Within", within)

            }
Expand

Add an event listener

Create an event listener to register a change when a new geometry is drawn or updated. If you draw a new geometry, the last one from the selectedGraphics array is removed. The onGraphicUpdate function is called to determine the spatial relationships between the remaining geometries.

Listen for events on the Sketch widget. Watch for the update, undo, or redo events, and call the onGraphicUpdate method to determine the spatial relationships when these events occur.

Expand
Use dark colors for code blocks
            view.ui.add(sketch, "top-right");

            sketch.on(["update", "undo", "redo"], onGraphicUpdate);

Expand

Listen for the create event on the Sketch widget. When a new graphic is created, get the last graphic from the selectedGraphics array and remove that graphic from the graphicsLayer so that only two graphics are in the view at one time. Call the onGraphicUpdate function to determine the spatial relationship between the geometries.

Expand
Use dark colors for code blocks
            sketch.on(["update", "undo", "redo"], onGraphicUpdate);

            sketch.on("create", (event) => {
                if (event.state === "start") {
                    const arrVal = selectedGraphics.pop();
                    graphicsLayer.remove(arrVal);
                }
                if (event.state === "complete") {
                    selectedGraphics.unshift(event.graphic);

                    onGraphicUpdate();

                }
            })

Expand

Call the onGraphicUpdate to calculate the spatial relationships when the app loads. Use the sketch widget's update method to select the polyline graphic so that the user knows they can move that graphic around.

Expand
Use dark colors for code blocks
            sketch.on("create", (event) => {
                if (event.state === "start") {
                    const arrVal = selectedGraphics.pop();
                    graphicsLayer.remove(arrVal);
                }
                if (event.state === "complete") {
                    selectedGraphics.unshift(event.graphic);

                    onGraphicUpdate();

                }
            })

            view.when(() => {
                sketch.update(polylineGraphic).then(onGraphicUpdate)
            });
Expand

Run the app

In CodePen, run your code to display the map.

The map loads and displays a line and polygon graphic. In the bottom right, the spatial relationships between the graphics are displayed. Move the graphics to see how the spatial relationships change. Create new graphics using the Sketch widget to explore the spatial relationships between different geometry types.

What's next?

Learn how to use additional API features and ArcGIS services in these tutorials: