Relate Method (GeometryEngine)

In This Topic

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

Syntax

Visual Basic (Declaration)
C#

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

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

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.
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 or 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. For examples of how to apply the DE-9IM, see the Relate and the Dimensionally Extended Nine-Intersection Model (DE 9IM) Pro Concepts topic .

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

Example

Determine relationship between two geometries

{
  // set up some geometries

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

  // multipoint
  List<MapPoint> points = [point0, point1, point2];
  Multipoint multipoint = MultipointBuilderEx.CreateMultipoint(points, SpatialReferences.WGS84);

  // polygon 
  List<Coordinate2D> polygonCoords =
  [
      new Coordinate2D(-10, 0),
  new Coordinate2D(0, 10),
  new Coordinate2D(10, 0),
  new Coordinate2D(-10, 0)
  ];
  polygon = PolygonBuilderEx.CreatePolygon(polygonCoords, SpatialReferences.WGS84);

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

  List<Segment> segments =
  [
      LineBuilderEx.CreateLineSegment(new Coordinate2D(5.05, -2.87), new Coordinate2D(6.35, 1.57)),
  LineBuilderEx.CreateLineSegment(new Coordinate2D(6.35, 1.57), new Coordinate2D(4.13, 2.59)),
  LineBuilderEx.CreateLineSegment(new Coordinate2D(4.13, 2.59), new Coordinate2D(5, 5))
  ];
  Polyline polyline5 = PolylineBuilderEx.CreatePolyline(segments, SpatialReferences.WGS84);

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

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

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

  Polyline polyline9 = PolylineBuilderEx.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 11 Home, Pro, Enterprise (64 bit)

ArcGIS Pro version: 3.0 or higher.

Reference

GeometryEngine Class
GeometryEngine Members

Send feedback