com.esri.arcgis.geometry
Interface IRelationalOperator

All Superinterfaces:
Serializable
All Known Implementing Classes:
Envelope, GeometryBag, Multipoint, Point, Polygon, Polyline

public interface IRelationalOperator
extends Serializable

Provides access to members that determine if a certain spatial relationship exists between two geometries.

Description

Relational Operators compare two geometries and return a boolean indicating whether or not the desired relationship exists. Some relationships require that the input geometries be of the same dimension while other have more flexible dimensional constraints. Most of the predefined Relational Operators are mutually exclusive Clementini operators. Please see the "Shape Comparison Language" topic in the Technical Documents section in the help.

Remarks

Only geometries that support the IRelationalOperator interface can be used as input geometries.

RelationalOperator Boundary/Interior Example

When To Use

Relational Operators are used to determine whether or not a specific relationship exists between two geometries.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

See Also:
ITopologicalOperator, IGeometry

Method Summary
 boolean contains(IGeometry other)
          Indicates if this geometry contains the other geometry.
 boolean crosses(IGeometry other)
          Indicates if the two geometries intersect in a geometry of lesser dimension.
 boolean disjoint(IGeometry other)
          Indicates if the two geometries share no points in common.
 boolean esri_equals(IGeometry other)
          Indicates if the two geometries are of the same type and define the same set of points in the plane.
 boolean overlaps(IGeometry other)
          Indicates if the intersection of the two geometries has the same dimension as one of the input geometries.
 boolean relation(IGeometry other, String relationDescription)
          Indicates if the defined relationship exists.
 boolean touches(IGeometry other)
          Indicates if the boundaries of the geometries intersect.
 boolean within(IGeometry other)
          Indicates if this geometry is contained (is within) another geometry.
 

Method Detail

esri_equals

boolean esri_equals(IGeometry other)
                    throws IOException,
                           AutomationException
Indicates if the two geometries are of the same type and define the same set of points in the plane.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Returns:
The esri_equals
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

touches

boolean touches(IGeometry other)
                throws IOException,
                       AutomationException
Indicates if the boundaries of the geometries intersect.

Description

Two geometries are said to touch when the intersection of the geometries is non-empty, but the intersection of their interiors is empty. Touches is a Clementini operator. For example, a point touches a polyline only if the point is coincident with one of the polyline end points.

Touches examples. Only "true" relationships are showed in this picture.

Remarks

Only geometries that support the IRelationalOperator interface can be used as input geometries.

Touch does not apply for point/point comparison.

If either one of the two geometries is empty, the geometries are not touched.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Returns:
The touches
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

contains

boolean contains(IGeometry other)
                 throws IOException,
                        AutomationException
Indicates if this geometry contains the other geometry.

Description

The base geometry contains the comparison geometry (other) if the comparison geometry is a subset of the base geometry and the intersection of their interiors is not empty. Therefore a polygon does not contain any part of its 1D boundary. Contains is the opposite operator of Within.

Remarks

Only geometries that support the IRelationalOperator interface can be used as input geometries.

If geometry1 Contains geometry2, then geometry2 is Within geometry1.

An empty geometry does not contain another geometry. On the other hand, an empty geometry is contained in another geometry, unless the other geometry is empty.

Contains examples. Only "true" relationships are showed in this picture.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Returns:
The contains
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

within

boolean within(IGeometry other)
               throws IOException,
                      AutomationException
Indicates if this geometry is contained (is within) another geometry.

Description

The base geometry is within the comparison geometry if the base geometry is the intersection of the geometries and the intersection of their interiors is not empty. Within is a Clementini operator. Within is the opposite operator of contains.

Remarks

Only geometries that support the IRelationalOperator interface can be used as input geometries.

If geometry1 is Within geometry2, then geometry2 Contains geometry1.

An empty geometry is within another geometry, unless the other geometry is empty.

Within examples. Only "true" relationships are showed in this picture.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Returns:
The within
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

disjoint

boolean disjoint(IGeometry other)
                 throws IOException,
                        AutomationException
Indicates if the two geometries share no points in common. Negate this result to compute the Intersect relation.

Description

Two geometries are disjoint if their intersection is empty. Two geometries intersect if disjoint is "false". Disjoint is a Clementini operator.

Remarks

Only geometries that support the IRelationalOperator interface can be used as input geometries.

Two geometries are disjoint if either one is empty.

Disjoint example. Only "true" relationships are showed in this picture.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Returns:
The disjoint
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

crosses

boolean crosses(IGeometry other)
                throws IOException,
                       AutomationException
Indicates if the two geometries intersect in a geometry of lesser dimension.

Description

Two polylines cross if they share only points in common, at least one of which is not an endpoint. A polyline and an polygon cross if they share a polyline in common on the interior of the polygon which is not equivalent to the entire polyline. Cross is a Clementini operator.

Remarks

Only geometries that support the IRelationalOperator interface can be used as input geometries.

Cross only applies to polyline/polyline, polyline/polygon, or polygon/polyline relations.

If either one of the geometries is empty, the geometries do not cross.

Crosses examples. Only "true" relationships are showed in this picture.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Returns:
The crosses
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

overlaps

boolean overlaps(IGeometry other)
                 throws IOException,
                        AutomationException
Indicates if the intersection of the two geometries has the same dimension as one of the input geometries.

Description

Two geometries overlap if the region of their intersection is of the same dimension as the geometries involved and is not equivalent to either of the geometries. Overlaps is a Clementini operator.

Remarks

Only geometries that support the IRelationalOperator interface can be used as input geometries.

Overlaps only applies to polyline/polyline, polygon/polygon and multipoint/multipoint relations.

Two geometries do not overlap if either one is empty.

Overlaps examples. Only "true" relationships are showed in this picture.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Returns:
The overlaps
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

relation

boolean relation(IGeometry other,
                 String relationDescription)
                 throws IOException,
                        AutomationException
Indicates if the defined relationship exists.

Description

Relation allows a general relation defined using the Shape Comparison Language to be determined between two input geometries. The Shape Comparison Language is based on the Calculus-Based Method (CBM), as described and defined by Clementini and Felice, but has some extensions specific to working with vertex-based geometries and is fully described in the Technical Documents section of the ArcObjects Developer Help. Please refer to the Shape Comparison Language documentation for proper syntax and available functionality.

Note that at the current release, Relation only operates with straight lines.

Remarks

Here is a VBA example of using the "RELATE" function to detect overlapping polylines. It assumes two polyline features are selected. G1 and G2 are placeholders for, in this example, the VBA variables r1 and r2.

Option Explicit

Public Sub overlapstest()
Dim ef As IEnumFeature
Dim d As IMxDocument
Set d = ThisDocument
Set ef = d.FocusMap.FeatureSelection
Dim r1 As IRelationalOperator, r2 As IRelationalOperator
Set r1 = ef.Next.Shape
Set r2 = ef.Next.Shape

Debug.Print "relation:", r1.Relation(r2, "RELATE(G1, G2, ""1********"")")

End Sub

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
other - A reference to a com.esri.arcgis.geometry.IGeometry (in)
relationDescription - The relationDescription (in)
Returns:
The relationResult
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.