Working with topologically related features

Summary

This topic discusses how to work with the topology graph in the editor to use the relationships between shared or coincident features, and how to update their geometry.

About working with topologically related features

Many types of geographic features share a common boundary or have coincident geometry. For example, ZIP Codes or postal codes might follow street centerlines, shorelines share a boundary with oceans, and soil or geology polygons share a common boundary with their neighbor. When making edits to these features, update the shared boundary or coincident geometry between features rather than the geometry of each individual feature and resolving any problems after the edit.

In ArcMap, coincident geometry between features can be updated via the tools and functions on the Topology toolbar when working with a map or geodatabase topology. Programmatically, shared boundaries are accessed through the TopologyGraph, which is used to define and discover topological relationships between features that are then represented as a set of topological elements that can be queried, analyzed, and updated.

Accessing the topology graph

In ArcMap, the topology graph is accessed via the TopologyExtension class when in an edit session. The ITopologyExtension.CurrentTopology property returns the current topology that the edit tools are working against. The current topology can be one of the following types:

Geodatabase topology (ITopology)
Map topology (IMapTopology)

The following code example references the topology graph from the current topology in an edit session:

[C#]


        UID extUid = new UIDClass();
extUid.Value = "esriEditorExt.TopologyExtension";
ITopologyExtension topologyExt = ArcMap.Application.FindExtensionByCLSID(extUid)as
    ITopologyExtension;
ITopologyGraph4 topoGraph = GetTopologyGraph(topologyExt);

ITopologyGraph4 GetTopologyGraph(ITopologyExtension topologyExt)
{
    if (topologyExt == null)
        return null;

    if (topologyExt.CurrentTopology is IMapTopology)
    {
        IMapTopology mapTopo = topologyExt.CurrentTopology as IMapTopology;
        return mapTopo.Cache as ITopologyGraph4;
    }
    else
    {
        ITopology2 topo = topologyExt.CurrentTopology as ITopology2;
        return topo.Cache as ITopologyGraph4;
    }
}

[VB.NET]


        Dim topoUiD As UID = New UIDClass()
topoUiD.Value = "esriEditorExt.TopologyExtension"
Dim topologyExt As ITopologyExtension = My.ArcMap.Application.FindExtensionByCLSID(topoUiD)
Dim topoGraph As ITopologyGraph4 = GetTopologyGraph(topologyExt)

Private Function GetTopologyGraph(ByVal topologyExt As ITopologyExtension) As ITopologyGraph4
    If topologyExt Is Nothing Then
        Return Nothing
    End If
    If TypeOf topologyExt.CurrentTopology Is IMapTopology Then
        Dim mapTopo As IMapTopology = TryCast(topologyExt.CurrentTopology, IMapTopology)
        Return mapTopo.Cache
    Else
        Dim topo As ITopology2 = TryCast(topologyExt.CurrentTopology, ITopology2)
        Return topo.Cache
    End If
End Function

If you are using an ArcGIS for Desktop Basic license, you only get a reference to a map topology. Editing of geodatabase topologies is not supported at this license level.

Building the topology graph

The topology graph is an in-memory representation of the integrated features within the current topology for a given area. The topology tools on the Topology toolbar build and maintain the topology graph when the user is working interactively. For example, when the user works with the Topology Edit tool, ArcMap builds the topology graph as required. During this process, spatial relationships between features are discovered and the topological elements (ITopologyElement), consisting of edges (ITopologyEdge) and nodes (ITopologyNode), are placed in memory. If the user pans to another extent and reuses the tool, the topology graph is rebuilt.

Programmatically, you can build the topology graph using the ITopologyGraph4.Build method, supplying an extent, or the ITopologyGraph4.BuildFromPolygon method, supplying a polygonal area. Refer to the component Help on these methods for code examples.

Building the graph can be time consuming for large extents containing a large number of features. Keep the size of the topology graph to a minimum when providing the build extent to reduce the memory footprint of the graph, and to increase performance. To minimize rebuilding the graph, verify that the applicable area is already contained within the existing topology graph using the ITopologyGraph4.BuildExtent property.

Once the topology graph is built for the applicable area, you can interrogate the elements contained in the graph to determine relationships—such as, adjacency or coincidence—and perform updates on the coincident geometry.

Working with the topology graph

After the topology graph is built, the topology elements represent integrated features, such as a shared polygon boundary's within a layer or coincident features between layers. You can use the properties and methods on the topology graph to query these relationships and return such information for the shared features that each topological element represents; or, for a given feature, return the topological element it participates in allowing you to access the other shared features. You can also traverse the graph by enumerating through the connectivity between the topology edges and topology nodes.

You can access topology elements in the following ways:

For a given feature in the topology graph, return its edges through ITopologyGraph4.GetParentEdges.
Select topological elements that intersect a specified geometry through ITopologyGraph4.SelectByGeometry.
Return an element closest to a given point via ITopologyGraph4.HitTest.

If the user has interactively selected elements (edges and nodes) with the Topology Edit tool, you can enumerate through that selection with ITopologyGraph4.Edges or ITopologyGraph4.Nodes. If you are relying on the user to select the elements interactively with this tool, you do not have to programmatically build the topology graph, as this is done when the tool is used.

Adjacency

Topological elements maintain a list of shared features they represent. For topology edges, you can enumerate through the ITopologyEdge.LeftParents and ITopologyEdge.RightParents properties to return the features (polygons) on the left and right side of a topology edge. This allows you, as an example, to calculate a left and right attribute for a line that coincides with a polygon boundary, such as street and ZIP Code boundaries. In this case, the ITopologyElement.Parents property returns the street and the two polygon features without an indication of side.

The following truncated code example calculates the left polygon for a supplied feature cursor of polylines:

[C#]


        m_editor.StartOperation();
lineFeature = featCursor.NextFeature; //An IFeature.
while ((lineFeature != null))
{
    //Build the topology graph around the feature.
    IEnvelope topoEnv = lineFeature.Shape.Envelope;
    topoEnv.Expand(1.25, 1.25, true);
    topoGraph.Build(topoEnv, false);
    IEnumTopologyEdge enumTopoEdge = topoGraph.GetParentEdges(lineFeature.Class,
        lineFeature.OID);
    enumTopoEdge.Reset();
    ITopologyEdge topoEdge = enumTopoEdge.Next;
    IEnumTopologyParent leftParents = topoEdge.LeftParents(true);
    leftParents.Reset();
    esriTopologyParent leftParent = leftParents.Next;
    lineFeature.Value(iLeftPolyField) = leftParent.m_FID;
    featCursor.UpdateFeature(pFeat);
    lineFeature = featCursor.NextFeature;
}

m_editor.StopOperation("Update LPOLY");

[VB.NET]


        m_editor.StartOperation()
lineFeature = featCursor.NextFeature 'An IFeature.
Do While Not lineFeature Is Nothing
    'Build the topology graph around the feature.
    Dim topoEnv As IEnvelope = lineFeature.Shape.Envelope
    topoEnv.Expand(1.25, 1.25, True)
    topoGraph.Build(topoEnv, False)
    Dim enumTopoEdge As IEnumTopologyEdge = topoGraph.GetParentEdges(lineFeature.Class, lineFeature.OID)
    enumTopoEdge.Reset()
    Dim topoEdge As ITopologyEdge = enumTopoEdge.Next
    Dim leftParents As IEnumTopologyParent = topoEdge.LeftParents(True)
    leftParents.Reset()
    Dim leftParent As esriTopologyParent = leftParents.Next
    lineFeature.Value(iLeftPolyField) = leftParent.m_FID
    featCursor.UpdateFeature(pFeat)
    lineFeature = featCursor.NextFeature
Loop
m_editor.StopOperation("Update LPOLY")

Updating coincident geometry

The methods on ITopologyGraph4 provide several ways to update coincident geometry. You can replace or reshape topology edges with ITopologyGraph4.SetEdgeGeometry and ITopologyGraph4.ReshapeEdgeGeometry. Topology edges and nodes can be moved or transformed with the ITopologyGraph4.TransformSelection method. In all these cases, changes to the topology elements will change the location and maintain connectivity of the underlying features.

To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):

ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)
ESRI.ArcGIS.Geodatabase
ESRI.ArcGIS.EditorExt

Development licensing	Deployment licensing
ArcGIS for Desktop Basic	ArcGIS for Desktop Basic
ArcGIS for Desktop Standard	ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced	ArcGIS for Desktop Advanced