Relate Method—ArcGIS Pro

Performs custom relational operations between two geometries using a Dimensionally Extended Nine-Intersection Model, DE-9IM, formatted string.

Syntax

C#
Visual Basic (Declaration)

bool Relate( 
   Geometry geometry1,
   Geometry geometry2,
   string relateString
)

Function Relate( _
   ByVal geometry1 As Geometry, _
   ByVal geometry2 As Geometry, _
   ByVal relateString As String _
) As Boolean

Parameters

geometry1: The first geometry in the relation.
geometry2: The second geometry in the relation.
relateString: The DE-9IM matrix relation encoded as a string.

Return Value

Returns true if the relation holds, false otherwise.

Exceptions

Exception	Description
System.ArgumentNullException	Either geometry1 or geometry2 or both are null or empty.
System.NotImplementedException	The method is not implemented for GeometryBag or Multipatch.
System.InvalidOperationException	Incompatible spatial references between the input geometries.
System.ArgumentException	Invalid relate string; the string is null.
System.NotImplementedException	Spatial reference of geometry1or geometry2is an image coordinate system.

Remarks

The DE-9IM is a standard used to describe spatial relationships between two geometries and can be referenced at https://en.wikipedia.org/wiki/DE-9IM.

Examples of how to use the Relate method can be found here. All of the predefined relational operations can be defined (including Intersect, Within, Contains, Crosses, Disjoint, Overlaps, Equals and Touches).

Example

// set up some geometries

// points
MapPoint point0 = MapPointBuilder.CreateMapPoint(0, 0, SpatialReferences.WGS84);
MapPoint point1 = MapPointBuilder.CreateMapPoint(1, 1, SpatialReferences.WGS84);
MapPoint point2 = MapPointBuilder.CreateMapPoint(-5, 5, SpatialReferences.WGS84);

// multipoint
List<MapPoint> points = new List<MapPoint>() { point0, point1, point2 };
Multipoint multipoint = MultipointBuilder.CreateMultipoint(points, SpatialReferences.WGS84);

// polygon 
List<Coordinate2D> polygonCoords = new List<Coordinate2D>()
{
    new Coordinate2D(-10, 0),
    new Coordinate2D(0, 10),
    new Coordinate2D(10, 0),
    new Coordinate2D(-10, 0)
};
Polygon polygon = PolygonBuilder.CreatePolygon(polygonCoords, SpatialReferences.WGS84);

// polylines
Polyline polyline1 = PolylineBuilder.CreatePolyline(LineBuilder.CreateLineSegment(new Coordinate2D(-9.1, 0.1), new Coordinate2D(0, 9)), SpatialReferences.WGS84);
Polyline polyline2 = PolylineBuilder.CreatePolyline(LineBuilder.CreateLineSegment(new Coordinate2D(-5, 5), new Coordinate2D(0, 5)), SpatialReferences.WGS84);
Polyline polyline3 = PolylineBuilder.CreatePolyline(LineBuilder.CreateLineSegment(new Coordinate2D(2.09, -2.04), new Coordinate2D(5, 10)), SpatialReferences.WGS84);
Polyline polyline4 = PolylineBuilder.CreatePolyline(LineBuilder.CreateLineSegment(new Coordinate2D(10, -5), new Coordinate2D(10, 5)), SpatialReferences.WGS84);

List<Segment> segments = new List<Segment>()
{
    LineBuilder.CreateLineSegment(new Coordinate2D(5.05, -2.87), new Coordinate2D(6.35, 1.57)),
    LineBuilder.CreateLineSegment(new Coordinate2D(6.35, 1.57), new Coordinate2D(4.13, 2.59)),
    LineBuilder.CreateLineSegment(new Coordinate2D(4.13, 2.59), new Coordinate2D(5, 5))
};
Polyline polyline5 = PolylineBuilder.CreatePolyline(segments, SpatialReferences.WGS84);

segments.Add(LineBuilder.CreateLineSegment(new Coordinate2D(5, 5), new Coordinate2D(10, 10)));

Polyline polyline6 = PolylineBuilder.CreatePolyline(segments, SpatialReferences.WGS84);
Polyline polyline7 = PolylineBuilder.CreatePolyline(polyline5);
Polyline polyline8 = PolylineBuilder.CreatePolyline(LineBuilder.CreateLineSegment(new Coordinate2D(5, 5), new Coordinate2D(10, 10)), SpatialReferences.WGS84);

segments.Clear();
segments.Add(LineBuilder.CreateLineSegment(new Coordinate2D(0.6, 3.5), new Coordinate2D(0.7, 7)));
segments.Add(LineBuilder.CreateLineSegment(new Coordinate2D(0.7, 7), new Coordinate2D(3, 9)));

Polyline polyline9 = PolylineBuilder.CreatePolyline(segments, SpatialReferences.WGS84);

// now do the Related tests

// Interior/Interior Intersects
string scl = "T********";
bool related = GeometryEngine.Instance.Relate(polygon, polyline1, scl);     // related = true
related = GeometryEngine.Instance.Relate(point0, point1, scl);              // related = false
related = GeometryEngine.Instance.Relate(point0, multipoint, scl);          // related = true
related = GeometryEngine.Instance.Relate(multipoint, polygon, scl);         // related = true
related = GeometryEngine.Instance.Relate(multipoint, polyline1, scl);       // related = false
related = GeometryEngine.Instance.Relate(polyline2, point2, scl);           // related = false
related = GeometryEngine.Instance.Relate(point1, polygon, scl);             // related = true

// Interior/Boundary Intersects
scl = "*T*******";
related = GeometryEngine.Instance.Relate(polygon, polyline2, scl);          // related = true
related = GeometryEngine.Instance.Relate(polygon, polyline3, scl);          // related = false
related = GeometryEngine.Instance.Relate(point1, polygon, scl);             // related = false

// Boundary/Boundary Interior intersects
scl = "***T*****";
related = GeometryEngine.Instance.Relate(polygon, polyline4, scl);          // related = true

// Overlaps Dim1
scl = "1*T***T**";
related = GeometryEngine.Instance.Relate(polygon, polyline5, scl);          // related = true

// Crosses Area/Line (LineB crosses PolygonA)
scl = "1020F1102";
related = GeometryEngine.Instance.Relate(polygon, polyline6, scl);          // related = false
related = GeometryEngine.Instance.Relate(polygon, polyline9, scl);          // related = true

// Boundary/Boundary Touches
scl = "F***T****";
related = GeometryEngine.Instance.Relate(polygon, polyline7, scl);          // related = false
related = GeometryEngine.Instance.Relate(polygon, polyline8, scl);          // related = true

Requirements

Target Platforms: Windows 10, Windows 8.1

Reference

IGeometryEngine Interface
IGeometryEngine Members