com.esri.arcgis.geometry
Interface ITopologicalOperator

All Superinterfaces:
Serializable
All Known Subinterfaces:
ITopologicalOperator2, ITopologicalOperator3, ITopologicalOperator4, ITopologicalOperator5
All Known Implementing Classes:
GeometryBag, MultiPatch, Multipoint, Point, Polygon, Polyline

public interface ITopologicalOperator
extends Serializable

Provides access to members for constructing new geometries based upon topological relationships between existing geometries.

Superseded By

ITopologicalOperator5

Remarks

Buffer, Clip, and Simplify are the only methods of ITopologicalOperator supported on GeometryBags.

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this interface with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bezier Curve), paths or rings, they must be wrapped into high-level geometry types.

For multipatch geometries, generally the footprint or envelope is used.

Every Geometry created within ArcGIS should be assigned a spatial reference. Always attach well-defined spatial references to new geometries. This improves processing efficiency, in particular, when using ITopologicalOperator on geometries that contain curved segments (circular arcs, bezier curves, elliptical arcs). New geometries include any geometry that is created in memory. It does not matter whether it will be stored in a feature class or not. Well-defined as applied to a spatial reference means that it not only has its coordinate system (projection) defined, but also its coordinate grid. The coordinate grid consists of the xy domain, xy resolution, and xy cluster tolerance properties of a spatial reference. If the Geometry includes z or m values, the z or m domains, z or m resolutions, and z or m cluster tolerance properties must also be defined. The cluster tolerance and resolutions can be quickly and easily set using SetDefault methods on ISpatialReferenceResolution and ISpatialReferenceTolerance interfaces.

Product Availability

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

See Also:
IRelationalOperator, IGeometry

Method Summary
 IGeometry buffer(double distance)
          Constructs a polygon that is the locus of points at a distance less than or equal to a specified distance from this geometry.
 void clip(IEnvelope clipperEnvelope)
          Constructs the intersection of this geometry and the specified envelope.
 void clipDense(IEnvelope clipperEnvelope, double denseDistance)
          Constructs the intersection of this geometry and the specified envelope; densifies lines in output contributed by the clipping envelope.
 void constructUnion(IEnumGeometry geometries)
          Defines this geometry to be the union of the inputs.
 IGeometry convexHull()
          Constructs the convex hull of this geometry.
 void cut(IPolyline cutter, IGeometry[] leftGeom, IGeometry[] rightGeom)
          Splits this geometry into a part left of the cutting polyline, and a part right of it.
 IGeometry difference(IGeometry other)
          Constructs the geometry containing points from this geometry but not the other geometry.
 IGeometry getBoundary()
          The boundary of this geometry.
 IGeometry intersect(IGeometry other, int resultDimension)
          Constructs the geometry that is the set-theoretic intersection of the input geometries.
 boolean isKnownSimple()
          Indicates whether this geometry is known (or assumed) to be topologically correct.
 boolean isSimple()
          Indicates whether this geometry is known (or assumed) to be topologically correct, after explicitly determining this if the geometry is not already known (or assumed) to be simple.
 void queryClipped(IEnvelope clipperEnvelope, IGeometry clippedGeometry)
          Redefines clippedGeometry to be the intersection of this geometry and the clipping envelope.
 void queryClippedDense(IEnvelope clipperEnvelope, double denseDistance, IGeometry clippedGeometry)
          Redefines clippedGeometry to be the intersection of this geometry and the clipping envelope; densifies lines in the output contributed by the clipping envelope.
 void simplify()
          Makes this geometry topologically correct.
 IGeometry symmetricDifference(IGeometry other)
          Constructs the geometry that contains points from either but not both input geometries.
 IGeometry union(IGeometry other)
          Constructs the geometry that is the set-theoretic union of the input geometries.
 

Method Detail

isSimple

boolean isSimple()
                 throws IOException,
                        AutomationException
Indicates whether this geometry is known (or assumed) to be topologically correct, after explicitly determining this if the geometry is not already known (or assumed) to be simple.

Description

Returns TRUE if the geometry is topologically Simple (refer to the discussion for the Simplify method). If the geometry is not Simple, it may be necessary to call Simplify to enforce topological consistency. Editing a geometry can change the IsSimple state of the geometry.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

The xy cluster tolerance value of the geometry's associated spatial reference is used by this method. If the goal of this method is to determine if a geometry can be persisted in an sde (or other integer-based) layer without alteration, you may wish to use the minimum xy cluster tolerance value (ISpatialReferenceTolerance::SetMinimumXYTolerance) before applying this method (don't forget to set it back).

This method does not support GeometryBags.

ITopologicalOperator IsSimple SimplePolygon Example

ITopologicalOperator IsSimple SimplePolyline Example

ITopologicalOperator IsSimple SimplePoint Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The isSimple
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isKnownSimple

boolean isKnownSimple()
                      throws IOException,
                             AutomationException
Indicates whether this geometry is known (or assumed) to be topologically correct.

Description

Returns TRUE when the geometry is aware that it is Simple. IsKnownSimple may return FALSE even if the geometry is simple as long as the geometry is not aware of its IsSimple state. Calling either IsSimple or Simplify makes the IsSimple state known to the geometry. Topologically altering the geometry makes the IsKnownSimple state FALSE until the IsSimple state is again checked.

Remarks

Here is the status of the IsKnownSimple flag in some common situations:


IsKnownSimple = 'False'
- A non-empty newly created geometry. For example, creating a polygon using IPointCollection sets the flag IsKnownSimple = 'false' on that geometry.
- Geometry after projection (IGeometry::Project )
- Geometry after generalization (IPolycurve::Generalize ) or smoothing(IPolycurve::Smooth )
- …

IsKnownSimple = 'True'
- A geometry coming directly from a feature class
- An empty geometry
- Output geometry of any method on ITopologicalOperator
- …

This method does not support GeometryBags.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The isKnownSimple
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

simplify

void simplify()
              throws IOException,
                     AutomationException
Makes this geometry topologically correct.

Description

Simplify permanently alters the input geometry, making its definition "topologically legal" with respect to its geometry type:


The XY tolerance property of the geometry's associated spatial reference is used during the simplify operation for polylines and polygons.

Remarks

This method first looks at the ITopologicalOperator::IsKnownSimple flag before starting processing. If the flag is 'true' then operation is interrupted and the geometry is considered simple. If the flag is 'false' then the geometry consistency is checked and the geometry is updated as needed.

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

Simplify Polygon Example

Simplify Polyline Example

Simplify Point Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

buffer

IGeometry buffer(double distance)
                 throws IOException,
                        AutomationException
Constructs a polygon that is the locus of points at a distance less than or equal to a specified distance from this geometry.

Remarks


The buffer distance is in the same units as the source shape that is being buffered.

A negative distance can be specified to produce a buffer inside the original polygon. This cannot be used with polyline. ITopologicalOperator methods must be applied on top-level geometries only. Top-Level geometries are point, multipoint, polyline and polygon. To use this method with segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped with a top-level type.

Buffer Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

convexHull

IGeometry convexHull()
                     throws IOException,
                            AutomationException
Constructs the convex hull of this geometry.

Description

The ConvexHull of a geometry is the minimal bounding polygon such that all outer angles are convex. The ConvexHull of a point is the point itself.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.

ConvexHull method does not deal with Z attribute now.

ConvexHull Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.geometry.IGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

intersect

IGeometry intersect(IGeometry other,
                    int resultDimension)
                    throws IOException,
                           AutomationException
Constructs the geometry that is the set-theoretic intersection of the input geometries. Use different resultDimension values to generate results of different dimensions.

Description

The Intersection of two Geometries of the same Dimension is a Geometry containing only the regions of overlap between the original geometries.

Remarks

Intersection is basically an AND between input geometries.

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.

Since ArcGIS 9.2, Intersect has a larger cost - it takes longer to run the method. Therefore, it is a better approach to test if the two geometries are disjoint before calling Intersect.

Intersection Example

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)
resultDimension - A com.esri.arcgis.geometry.esriGeometryDimension constant (in)
Returns:
A reference to a com.esri.arcgis.geometry.IGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IConstructMultipoint.constructIntersectionEx(com.esri.arcgis.geometry.ISegment, int, com.esri.arcgis.geometry.ISegment, int, double[], double[], int[]), IConstructMultipoint.constructIntersection(com.esri.arcgis.geometry.ISegment, int, com.esri.arcgis.geometry.ISegment, int, Object[], Object[], Object[]), ITopologicalOperator.intersect(com.esri.arcgis.geometry.IGeometry, int)

union

IGeometry union(IGeometry other)
                throws IOException,
                       AutomationException
Constructs the geometry that is the set-theoretic union of the input geometries.

Description

The Union of two Geometries of the same Dimension is a single Geometry corresponding to the combination of both Geometries such that anything within either of the original geometries is also part of the unioned geometry, but anything common to both geometries only exists once in the unioned geometry.

Remarks

The Union is basically an OR between the input geometries.

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.

Union Example

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:
A reference to a com.esri.arcgis.geometry.IGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

constructUnion

void constructUnion(IEnumGeometry geometries)
                    throws IOException,
                           AutomationException
Defines this geometry to be the union of the inputs. More efficient for unioning multiple geometries than calling Union repeatedly.

Description

ConstructUnion simultaneously Unions an Enumeration of geometries of the same Dimension into a single geometry. ConstructUnion is more efficient for unioning a large collection of geometries simultaneously rather than cycling through each geometry individually.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.

Temproray files might be created. If environment variable "ARCTMPDIR" exists, then the files are written to the path, otherwise written to current directory or system temp directory.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

difference

IGeometry difference(IGeometry other)
                     throws IOException,
                            AutomationException
Constructs the geometry containing points from this geometry but not the other geometry.

Description

Difference create a Geometry that is composed only of the region unique to the base geometry but not part of the input geometry.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.

ITopologicalOperator Differenece Example

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:
A reference to a com.esri.arcgis.geometry.IGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

symmetricDifference

IGeometry symmetricDifference(IGeometry other)
                              throws IOException,
                                     AutomationException
Constructs the geometry that contains points from either but not both input geometries.

Description

The SymmetricDifference between two Geometries of the same Dimension is the Union of those Geometries minus the Intersection of those Geometries. Thus, the SymmetricDifference is composed only of regions unique to only one of the geometries.

This method does not support GeometryBags.

Remarks

SymmetricDifference is basically an XOR between the input geometries.

SymmetricDifference of G1 and G2 can also be described as the Union(Difference(G1, G2), Difference(G2, G1)).

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.

Symmetric Difference Example

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:
A reference to a com.esri.arcgis.geometry.IGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

clip

void clip(IEnvelope clipperEnvelope)
          throws IOException,
                 AutomationException
Constructs the intersection of this geometry and the specified envelope.

Description

The Clip method clips the geometry of the feature that is receiving the method call. The Clip method does not return an envelope. The geometry that is clipped will depend on what is Contained by the input clipperEnvelope.

Remarks

Use QueryClipped or QueryClippedDense methods to send the results to a different polygon.

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

ITopologicalOperator Clip Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

queryClipped

void queryClipped(IEnvelope clipperEnvelope,
                  IGeometry clippedGeometry)
                  throws IOException,
                         AutomationException
Redefines clippedGeometry to be the intersection of this geometry and the clipping envelope.

Description

QueryClipped returns the portion of the input Geometry that is Contained by the input Envelope. The returned geometry is the same type as the original geometry.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

The other geometry must be an high-level geometry. High-Level geometries are point, multipoint, polyline and polygon. To use it with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), path or ring they must be wrapped into high-level geometries type. The output geometry must be co-created prior to the query. The output geometry is not co-created by the method; it is populated. This can be used in performance critical situations. For example, creating the geometry only once outside a loop and use the query method could improve performance.

This method does not support GeometryBags.

QueryClipped Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

queryClippedDense

void queryClippedDense(IEnvelope clipperEnvelope,
                       double denseDistance,
                       IGeometry clippedGeometry)
                       throws IOException,
                              AutomationException
Redefines clippedGeometry to be the intersection of this geometry and the clipping envelope; densifies lines in the output contributed by the clipping envelope.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

The other geometry must be an high-level geometry. High-Level geometries are point, multipoint, polyline and polygon. To use it with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), path or ring they must be wrapped into high-level geometries type. The output geometry must be co-created prior to the query. The output geometry is not co-created by the method; it is populated. This can be used in performance critical situations. For example, creating the geometry only once outside a loop and use the query method could improve performance.

This method does not support GeometryBags.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

cut

void cut(IPolyline cutter,
         IGeometry[] leftGeom,
         IGeometry[] rightGeom)
         throws IOException,
                AutomationException
Splits this geometry into a part left of the cutting polyline, and a part right of it.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

When a polyline/polygon is cut, it is split where it intersects the cutter polyline. Each piece is classified as ‘left of’ or ‘right of’ the cutter. This classification is based on the orientation of the cutter line. Parts of the target polyline that do not intersect the cutting polyline are returned as part of the ‘right of’ result for that input polyline. If a geometry is not cut, the left geometry will be empty.

When using a multi-part polyline to cut a single ring of a polyline, the orientation of the polyline paths is important. The cut piece of the ring must be on the same side of each cutting path as defined by the orientation of each path.

This method does not support GeometryBags.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
cutter - A reference to a com.esri.arcgis.geometry.IPolyline (in)
leftGeom - A reference to a com.esri.arcgis.geometry.IGeometry (out: use single element array)
rightGeom - A reference to a com.esri.arcgis.geometry.IGeometry (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getBoundary

IGeometry getBoundary()
                      throws IOException,
                             AutomationException
The boundary of this geometry. A polygon's boundary is a polyline. A polyline's boundary is a multipoint. A point or multipoint's boundary is an empty point or multipoint.

Description

The Boundary of a Geometry is the part one the exterior of the Geometry. The Boundary is one Dimension lower than the Dimension of the original Geometry. The Boundary of a Polygon are the Polylines that form the Rings of the Polygon. The Boundary of a Polyline is a Multipoint corresponding to the endpoints of each Path in the Polyline. The Boundary of a Multipoint is an empty set.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.



Boundary Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.geometry.IGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

clipDense

void clipDense(IEnvelope clipperEnvelope,
               double denseDistance)
               throws IOException,
                      AutomationException
Constructs the intersection of this geometry and the specified envelope; densifies lines in output contributed by the clipping envelope.

Remarks

ITopologicalOperator methods must be applied on high-level geometries only. High-Level geometries are point, multipoint, polyline and polygon. To use this method with low-level geometries such as segments (Line, Circular Arc, Elliptic Arc, Bézier Curve), paths or rings, they must be wrapped into high-level geometries types.

This method does not support GeometryBags.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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